PrimisAI Nexus

PrimisAI Nexus is a powerful and flexible Python package for managing AI agents and coordinating complex tasks using LLMs. It provides a robust framework for creating, managing, and interacting with multiple specialized AI agents under the supervision of a central coordinator.

<div align="center"> <img src="./examples/images/performance-coding.png" width="275"> <img src="./examples/images/performance-timing-closure.png" width="461"> </div>

Demo

https://github.com/user-attachments/assets/fc7f1cc1-f817-494d-aca8-586775e9062c

Features

• AI Base Class: A foundational class for AI interactions.
• Agent Class: Extends the AI base class with additional features for specialized tasks.
• Supervisor Class: Manages multiple agents, coordinates tasks, and handles user interactions.
• Hierarchical Supervision: Support for main and assistant supervisors enabling complex task hierarchies.
• Persistent History: Built-in conversation history management with JSONL storage.
• Integrated Logging: Organized logging system within workflow structure.
• Debugger Utility: Integrated debugging capabilities for logging and troubleshooting.
• Structured Agent Outputs: Support for schema-defined, structured responses with validation.
• Flexible Configuration: Easy-to-use configuration options for language models and agents.
• Flexible LLM Parameters: Direct control over all language model parameters through configuration.
• Interactive Sessions: Built-in support for interactive chat sessions with the AI system.
• YAML Configuration: Define complex agent hierarchies using YAML files for easy setup and modification.
• Model Context Protocol (MCP) Integration: Support for automatic discovery and usage of external tool servers via MCP, including SSE (HTTP) and stdio (local subprocess) transports.

Installation

You can install PrimisAI Nexus directly from PyPI using pip:

pip install primisai

Building from Source

If you prefer to build the package from source, clone the repository and install it with pip:

git clone git@github.com:PrimisAI/nexus.git
cd nexus
pip install -e .

Quick Start

Here's a simple example to get you started with Nexus:

from primisai.nexus.core import AI, Agent, Supervisor
from primisai.nexus.utils.debugger import Debugger

# Configure your OpenAI API key
llm_config = {
    "api_key": "your-api-key-here",
    "model": "gpt-4o",
    "base_url": "https://api.openai.com/v1",
}

# Create a supervisor
supervisor = Supervisor("MainSupervisor", llm_config)

# Create and register agents
agent1 = Agent("Agent1", llm_config, system_message="You are a helpful assistant.")
agent2 = Agent("Agent2", llm_config, system_message="You are a creative writer.")

supervisor.register_agent(agent1)
supervisor.register_agent(agent2)

# Start an interactive session
supervisor.display_agent_graph()
supervisor.start_interactive_session()

YAML Configuration

PrimisAI Nexus supports defining complex agent hierarchies using YAML configuration files. This feature allows for easy setup and modification of agent structures without changing the Python code.

Example YAML Configuration

Here's a simple example of a YAML configuration file:

supervisor:
  name: TaskManager
  type: supervisor
  llm_config:
    model: ${LLM_MODEL}
    api_key: ${LLM_API_KEY}
    base_url: ${LLM_BASE_URL}
  system_message: "You are the task management supervisor."
  children:
    - name: TaskCreator
      type: agent
      llm_config:
        model: ${LLM_MODEL}
        api_key: ${LLM_API_KEY}
        base_url: ${LLM_BASE_URL}
      system_message: "You are responsible for creating new tasks."
      keep_history: true
      tools:
        - name: add_task
          type: function
          python_path: examples.task_management_with_yaml.task_tools.add_task

The keep_history parameter allows you to control whether an agent maintains conversation history between interactions. When set to False, the agent treats each query independently, useful for stateless operations. When True (default), the agent maintains context from previous interactions.

To use this YAML configuration:

from primisai.nexus.config import load_yaml_config, AgentFactory

# Load the YAML configuration
config = load_yaml_config('path/to/your/config.yaml')

# Create the agent structure
factory = AgentFactory()
task_manager = factory.create_from_config(config)

# Start an interactive session
task_manager.start_interactive_session()

For a more detailed example of YAML configuration, check out the task management example.

Benefits of YAML Configuration

• Flexibility: Easily modify agent structures without changing Python code.
• Readability: YAML configurations are human-readable and easy to understand.
• Scalability: Define complex hierarchies of supervisors and agents in a clear, structured manner.
• Separation of Concerns: Keep agent definitions separate from application logic.

Documentation

For detailed documentation on each module and class, please refer to the inline docstrings in the source code.

History and Logging

PrimisAI Nexus provides comprehensive history management and logging capabilities organized within workflow directories:

nexus_workflows/
├── workflow_123/              # Workflow specific directory
│   ├── history.jsonl         # Conversation history
│   └── logs/                 # Workflow logs
│       ├── MainSupervisor.log
│       ├── AssistantSupervisor.log
│       └── Agent1.log
└── standalone_logs/          # Logs for agents not in workflows
    └── StandaloneAgent.log

Loading Persistent Chat History

You can restore any agent or supervisor's LLM-compatible context with a single call, enabling true warm starts and reproducibility, even for multi-level workflows.

from primisai.nexus.history import HistoryManager

manager = HistoryManager(workflow_id)
supervisor.chat_history = manager.load_chat_history("SupervisorName")
agent.chat_history = manager.load_chat_history("AgentName")

This ensures that only the relevant delegated turns, tool calls, and responses are loaded for each entity, preserving correct and replayable LLM state across runs.

Advanced Usage

PrimisAI Nexus allows for complex interactions between multiple agents. You can create specialized agents for different tasks, register them with a supervisor, and let the supervisor manage the flow of information and task delegation.

# Example of creating a specialized agent with tools
tools = [
    {
        "metadata": {
            "name": "search_tool",
            "description": "Searches the internet for information"
        },
        "tool": some_search_function
    }
]

research_agent = Agent("Researcher", llm_config, tools=tools, system_message="You are a research assistant.", use_tools=True)
supervisor.register_agent(research_agent)

Structured Agent Outputs

PrimisAI Nexus allows agents to provide schema-validated, structured outputs. This ensures consistent response formats and enables reliable downstream processing.

# Define an output schema for a code-writing agent
code_schema = {
    "type": "object",
    "properties": {
        "description": {
            "type": "string",
            "description": "Explanation of the code's purpose"
        },
        "code": {
            "type": "string",
            "description": "The actual code implementation"
        },
        "language": {
            "type": "string",
            "description": "Programming language used"
        }
    },
    "required": ["description", "code"]
}

# Create an agent with structured output
code_agent = Agent(
    name="CodeWriter",
    llm_config=llm_config,
    system_message="You are a skilled programmer.",
    output_schema=code_schema,
    strict=True  # Enforce schema validation
)

# Agent responses will be automatically formatted and validated
response = code_agent.chat("Write a function to calculate factorial")
# Response will be JSON-structured:
# {
#     "description": "Function to calculate factorial of a number",
#     "code": "def factorial(n):\n    if n <= 1: return 1\n    return n * factorial(n-1)",
#     "language": "python"
# }

The output_schema parameter defines the expected structure of the agent's responses, while the strict parameter controls validation:

• When strict=True, responses are guaranteed to match the schema
• When strict=False, the agent attempts to follow the schema but falls back to unstructured responses if needed

This feature is particularly useful for:

• Ensuring consistent output formats
• Building reliable agent pipelines
• Automated processing of agent responses
• Integration with downstream systems

For detailed examples of schema usage, including complex workflows with multiple schema-aware agents, see the output schema examples and schema-aware workflow example.

Hierarchical Supervisor Structure

PrimisAI Nexus suppor