# PrimisAI Nexus
[](https://arxiv.org/abs/2502.19091) [](https://arxiv.org/abs/2507.14393)
   [](https://pepy.tech/projects/primisai)  
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:
```bash
pip install primisai
```
### Building from Source
If you prefer to build the package from source, clone the repository and install it with pip:
```bash
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:
```python
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:
```yaml
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:
```python
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](examples/task_management_with_yaml).
### 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:
```bash
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.
```python
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.
```python
# 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.
```python
# 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](examples/output_schema_examples.py) and [schema-aware workflow example](examples/schema_aware_workflow_example.py).
### Hierarchical Supervisor Structure
PrimisAI Nexus supports a hierarchical supervisor structure with two types of supervisors:
1. Main Supervisor: The root supervisor that manages the overall workflow
2. Assistant Supervisor: Specialized supervisors that handle specific task domains
Here's how to create and use different types of supervisors:
```python
# Create a main supervisor with a specific workflow ID
main_supervisor = Supervisor(
name="MainSupervisor",
llm_config=llm_config,
workflow_id="custom_workflow_123"
)
# Create an assistant supervisor
assistant_supervisor = Supervisor(
name="AnalysisManager",
llm_config=llm_config,
is_assistant=True,
system_message="You manage data analysis tasks."
)
# Create agents
data_agent = Agent("DataAnalyst", llm_config, system_message="You analyze data.")
viz_agent = Agent("Visualizer", llm_config, system_message="You create visualizations.")
# Register assistant supervisor with main supervisor
main_supervisor.register_agent(assistant_supervisor)
# Register agents with assistant supervisor
assistant_supervisor.register_agent(data_agent)
assistant_supervisor.register_agent(viz_agent)
# Display the complete hierarchy
main_supervisor.display_agent_graph()
```
The above code creates a hierarchical structure where:
- Main Supervisor manages the overall workflow
- Assistant Supervisor handles specialized tasks
- Agents perform specific operations
The `display_agent_graph()` output will show:
```
Main Supervisor: MainSupervisor
│
└── Assistant Supervisor: AnalysisManager
│
├── Agent: DataAnalyst
│ └── No tools available
│
└── Agent: Visualizer
└── No tools available
```
Each workflow is automatically assigned a unique ID and maintains its conversation history in a dedicated directory structure:
```
custom_workflow_123/
├── history.jsonl
└── logs
├── AnalysisManager.log
├── DataAnalyst.log
├── MainSupervisor.log
└── Visualizer.log
```
All interactions, delegations, and tool usage are automatically logged and stored in the workflow directory, providing complete visibility into the decision-making process and execution flow.
## MCP Server Integration
PrimisAI Nexus supports automatic tool discovery and usage via external Model Context Protocol (MCP) servers. This enables seamless integration of local or remote tool infrastructures, including both SSE (HTTP) and stdio (local subprocess) transports.
### Supported Transports
- **SSE (HTTP/Server-Sent Events):**
- Connect to any MCP-compatible HTTP server exposing tools via an SSE endpoint.
- Recommended for remote, network-accessible, or containerized tool servers.
- **Stdio (Local Subprocess):**
- Launches a local MCP server using Python as a subprocess and communicates over stdin/stdout.
- Recommended for securely sandboxed or development tool servers.
### Configuration
When creating an `Agent`, use the `mcp_servers` argument to specify a list of tool servers and their transport types:
```python
mcp_servers = [
{
"type": "sse",
"url": "http://localhost:8000/sse"
},
{
"type": "sse",
"url": "https://remote.mcpservers.org/fetch"
},
{
"type": "stdio",
"script_path": "examples/agent_with_mcp_stdio/weather_server.py"
}
]
```
- For `"type": "sse"`, the `"url"` field must be the **exact SSE endpoint provided by your MCP server** (for example: `/sse`, `/fetch`, or another custom path). No path rewriting or appending is performed by the framework.
- For `"type": "stdio"`, provide the path to your MCP server Python script as `"script_path"`.
### Usage Example
```python
from primisai.nexus.core import Agent
agent = Agent(
name="RemoteMCPAgent",
llm_config=llm_config,
mcp_servers=[
{"type": "sse", "url": "https://remote.mcpservers.org/fetch"},
{"type": "stdio", "script_path": "weather_server.py"}
],
use_tools=True
)
agent.chat("What is 2 plus 3?")
```
### Manual Tool Refresh
If tools are added, removed, or modified on any MCP server during runtime, call:
```python
agent.update_mcp_tools()
```
This will refresh the list of available MCP tools without restarting the agent.
### Notes
- If your SSE MCP server requires authentication, add an `"auth_token"` field to the server dictionary.
- You can mix and match any number of SSE and stdio MCP servers per agent.
- Tool schemas are converted automatically for use with function-calling models.
For a complete working demonstration of using a Supervisor with multiple agents, each utilizing different MCP transport mechanisms (SSE and stdio), see the example and detailed instructions in: [Multiple Agents with MCP](examples/supervisor_multi_mcp/README.md)
## Citation
If you find Nexus useful, please consider citing our preprint.
```bibtex
@article{sami2025nexus,
title={Nexus: A Lightweight and Scalable Multi-Agent Framework for Complex Tasks Automation},
author={Sami, Humza and ul Islam, Mubashir and Charas, Samy and Gandhi, Asav and Gaillardon, Pierre-Emmanuel and Tenace, Valerio},
journal={arXiv preprint arXiv:2502.19091},
year={2025}
}
```
If you leveraged the Architect in your work, please consider citing our dedicated paper as well.
```bibtex
@article{sami2025adaptive,
title={Adaptive Multi-Agent Reasoning via Automated Workflow Generation},
author={Sami, Humza and ul Islam, Mubashir and Gaillardon, Pierre-Emmanuel and Tenace, Valerio},
journal={arXiv preprint arXiv:2507.14393},
year={2025}
}
```
## License
This project is licensed under the MIT License.
Raw data
{
"_id": null,
"home_page": null,
"name": "primisai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "AI, LLM, framework, AI agents",
"author": null,
"author_email": "PrimisAI <info@primis.ai>",
"download_url": "https://files.pythonhosted.org/packages/f7/4c/15697eed2dc12c552f6e33f2f4c36553fae5c20e76e01e14e5cfedb2102a/primisai-0.8.1.tar.gz",
"platform": null,
"description": "# PrimisAI Nexus\n[](https://arxiv.org/abs/2502.19091) [](https://arxiv.org/abs/2507.14393)\n\n   [](https://pepy.tech/projects/primisai)  \n\nPrimisAI 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.\n\n<div align=\"center\">\n<img src=\"./examples/images/performance-coding.png\" width=\"275\"> <img src=\"./examples/images/performance-timing-closure.png\" width=\"461\">\n</div>\n\n## Demo\nhttps://github.com/user-attachments/assets/fc7f1cc1-f817-494d-aca8-586775e9062c\n\n## Features\n\n- **AI Base Class**: A foundational class for AI interactions.\n- **Agent Class**: Extends the AI base class with additional features for specialized tasks.\n- **Supervisor Class**: Manages multiple agents, coordinates tasks, and handles user interactions.\n- **Hierarchical Supervision**: Support for main and assistant supervisors enabling complex task hierarchies.\n- **Persistent History**: Built-in conversation history management with JSONL storage.\n- **Integrated Logging**: Organized logging system within workflow structure.\n- **Debugger Utility**: Integrated debugging capabilities for logging and troubleshooting.\n- **Structured Agent Outputs**: Support for schema-defined, structured responses with validation.\n- **Flexible Configuration**: Easy-to-use configuration options for language models and agents.\n- **Flexible LLM Parameters**: Direct control over all language model parameters through configuration.\n- **Interactive Sessions**: Built-in support for interactive chat sessions with the AI system.\n- **YAML Configuration**: Define complex agent hierarchies using YAML files for easy setup and modification.\n- **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.\n\n## Installation\n\nYou can install PrimisAI Nexus directly from PyPI using pip:\n\n```bash\npip install primisai\n```\n\n### Building from Source\n\nIf you prefer to build the package from source, clone the repository and install it with pip:\n\n```bash\ngit clone git@github.com:PrimisAI/nexus.git\ncd nexus\npip install -e .\n```\n\n## Quick Start\n\nHere's a simple example to get you started with Nexus:\n\n```python\nfrom primisai.nexus.core import AI, Agent, Supervisor\nfrom primisai.nexus.utils.debugger import Debugger\n\n# Configure your OpenAI API key\nllm_config = {\n \"api_key\": \"your-api-key-here\",\n \"model\": \"gpt-4o\",\n \"base_url\": \"https://api.openai.com/v1\",\n}\n\n# Create a supervisor\nsupervisor = Supervisor(\"MainSupervisor\", llm_config)\n\n# Create and register agents\nagent1 = Agent(\"Agent1\", llm_config, system_message=\"You are a helpful assistant.\")\nagent2 = Agent(\"Agent2\", llm_config, system_message=\"You are a creative writer.\")\n\nsupervisor.register_agent(agent1)\nsupervisor.register_agent(agent2)\n\n# Start an interactive session\nsupervisor.display_agent_graph()\nsupervisor.start_interactive_session()\n```\n\n## YAML Configuration\n\nPrimisAI 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.\n\n### Example YAML Configuration\n\nHere's a simple example of a YAML configuration file:\n\n```yaml\nsupervisor:\n name: TaskManager\n type: supervisor\n llm_config:\n model: ${LLM_MODEL}\n api_key: ${LLM_API_KEY}\n base_url: ${LLM_BASE_URL}\n system_message: \"You are the task management supervisor.\"\n children:\n - name: TaskCreator\n type: agent\n llm_config:\n model: ${LLM_MODEL}\n api_key: ${LLM_API_KEY}\n base_url: ${LLM_BASE_URL}\n system_message: \"You are responsible for creating new tasks.\"\n keep_history: true\n tools:\n - name: add_task\n type: function\n python_path: examples.task_management_with_yaml.task_tools.add_task\n```\n\nThe `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.\n\nTo use this YAML configuration:\n\n```python\nfrom primisai.nexus.config import load_yaml_config, AgentFactory\n\n# Load the YAML configuration\nconfig = load_yaml_config('path/to/your/config.yaml')\n\n# Create the agent structure\nfactory = AgentFactory()\ntask_manager = factory.create_from_config(config)\n\n# Start an interactive session\ntask_manager.start_interactive_session()\n```\n\nFor a more detailed example of YAML configuration, check out the [task management example](examples/task_management_with_yaml).\n\n### Benefits of YAML Configuration\n\n- **Flexibility**: Easily modify agent structures without changing Python code.\n- **Readability**: YAML configurations are human-readable and easy to understand.\n- **Scalability**: Define complex hierarchies of supervisors and agents in a clear, structured manner.\n- **Separation of Concerns**: Keep agent definitions separate from application logic.\n\n## Documentation\n\nFor detailed documentation on each module and class, please refer to the inline docstrings in the source code.\n\n## History and Logging\nPrimisAI Nexus provides comprehensive history management and logging capabilities organized within workflow directories:\n\n```bash\nnexus_workflows/\n\u251c\u2500\u2500 workflow_123/ # Workflow specific directory\n\u2502 \u251c\u2500\u2500 history.jsonl # Conversation history\n\u2502 \u2514\u2500\u2500 logs/ # Workflow logs\n\u2502 \u251c\u2500\u2500 MainSupervisor.log\n\u2502 \u251c\u2500\u2500 AssistantSupervisor.log\n\u2502 \u2514\u2500\u2500 Agent1.log\n\u2514\u2500\u2500 standalone_logs/ # Logs for agents not in workflows\n \u2514\u2500\u2500 StandaloneAgent.log\n```\n\n## Loading Persistent Chat History\n\nYou 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.\n\n```python\nfrom primisai.nexus.history import HistoryManager\n\nmanager = HistoryManager(workflow_id)\nsupervisor.chat_history = manager.load_chat_history(\"SupervisorName\")\nagent.chat_history = manager.load_chat_history(\"AgentName\")\n```\nThis ensures that only the relevant delegated turns, tool calls, and responses are loaded for each entity, preserving correct and replayable LLM state across runs.\n\n## Advanced Usage\n\nPrimisAI 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.\n\n```python\n# Example of creating a specialized agent with tools\ntools = [\n {\n \"metadata\": {\n \"name\": \"search_tool\",\n \"description\": \"Searches the internet for information\"\n },\n \"tool\": some_search_function\n }\n]\n\nresearch_agent = Agent(\"Researcher\", llm_config, tools=tools, system_message=\"You are a research assistant.\", use_tools=True)\nsupervisor.register_agent(research_agent)\n```\n\n### Structured Agent Outputs\nPrimisAI Nexus allows agents to provide schema-validated, structured outputs. This ensures consistent response formats and enables reliable downstream processing.\n\n```python\n# Define an output schema for a code-writing agent\ncode_schema = {\n \"type\": \"object\",\n \"properties\": {\n \"description\": {\n \"type\": \"string\",\n \"description\": \"Explanation of the code's purpose\"\n },\n \"code\": {\n \"type\": \"string\",\n \"description\": \"The actual code implementation\"\n },\n \"language\": {\n \"type\": \"string\",\n \"description\": \"Programming language used\"\n }\n },\n \"required\": [\"description\", \"code\"]\n}\n\n# Create an agent with structured output\ncode_agent = Agent(\n name=\"CodeWriter\",\n llm_config=llm_config,\n system_message=\"You are a skilled programmer.\",\n output_schema=code_schema,\n strict=True # Enforce schema validation\n)\n\n# Agent responses will be automatically formatted and validated\nresponse = code_agent.chat(\"Write a function to calculate factorial\")\n# Response will be JSON-structured:\n# {\n# \"description\": \"Function to calculate factorial of a number\",\n# \"code\": \"def factorial(n):\\n if n <= 1: return 1\\n return n * factorial(n-1)\",\n# \"language\": \"python\"\n# }\n```\n\nThe `output_schema` parameter defines the expected structure of the agent's responses, while the `strict` parameter controls validation:\n- When `strict=True`, responses are guaranteed to match the schema\n- When `strict=False`, the agent attempts to follow the schema but falls back to unstructured responses if needed\n\nThis feature is particularly useful for:\n- Ensuring consistent output formats\n- Building reliable agent pipelines\n- Automated processing of agent responses\n- Integration with downstream systems\n\nFor detailed examples of schema usage, including complex workflows with multiple schema-aware agents, see the [output schema examples](examples/output_schema_examples.py) and [schema-aware workflow example](examples/schema_aware_workflow_example.py).\n\n### Hierarchical Supervisor Structure\n\nPrimisAI Nexus supports a hierarchical supervisor structure with two types of supervisors:\n\n1. Main Supervisor: The root supervisor that manages the overall workflow\n\n2. Assistant Supervisor: Specialized supervisors that handle specific task domains\n\nHere's how to create and use different types of supervisors:\n\n```python\n# Create a main supervisor with a specific workflow ID\nmain_supervisor = Supervisor(\n name=\"MainSupervisor\",\n llm_config=llm_config,\n workflow_id=\"custom_workflow_123\"\n)\n\n# Create an assistant supervisor\nassistant_supervisor = Supervisor(\n name=\"AnalysisManager\",\n llm_config=llm_config,\n is_assistant=True,\n system_message=\"You manage data analysis tasks.\"\n)\n\n# Create agents\ndata_agent = Agent(\"DataAnalyst\", llm_config, system_message=\"You analyze data.\")\nviz_agent = Agent(\"Visualizer\", llm_config, system_message=\"You create visualizations.\")\n\n# Register assistant supervisor with main supervisor\nmain_supervisor.register_agent(assistant_supervisor)\n\n# Register agents with assistant supervisor\nassistant_supervisor.register_agent(data_agent)\nassistant_supervisor.register_agent(viz_agent)\n\n# Display the complete hierarchy\nmain_supervisor.display_agent_graph()\n```\n\nThe above code creates a hierarchical structure where:\n- Main Supervisor manages the overall workflow\n- Assistant Supervisor handles specialized tasks\n- Agents perform specific operations\n\nThe `display_agent_graph()` output will show:\n\n```\nMain Supervisor: MainSupervisor\n\u2502\n\u2514\u2500\u2500 Assistant Supervisor: AnalysisManager\n \u2502\n \u251c\u2500\u2500 Agent: DataAnalyst\n \u2502 \u2514\u2500\u2500 No tools available\n \u2502\n \u2514\u2500\u2500 Agent: Visualizer\n \u2514\u2500\u2500 No tools available\n```\n\nEach workflow is automatically assigned a unique ID and maintains its conversation history in a dedicated directory structure:\n\n```\ncustom_workflow_123/\n\u251c\u2500\u2500 history.jsonl\n\u2514\u2500\u2500 logs\n \u251c\u2500\u2500 AnalysisManager.log\n \u251c\u2500\u2500 DataAnalyst.log\n \u251c\u2500\u2500 MainSupervisor.log\n \u2514\u2500\u2500 Visualizer.log\n```\n\nAll interactions, delegations, and tool usage are automatically logged and stored in the workflow directory, providing complete visibility into the decision-making process and execution flow.\n\n## MCP Server Integration\n\nPrimisAI Nexus supports automatic tool discovery and usage via external Model Context Protocol (MCP) servers. This enables seamless integration of local or remote tool infrastructures, including both SSE (HTTP) and stdio (local subprocess) transports.\n\n### Supported Transports\n\n- **SSE (HTTP/Server-Sent Events):**\n - Connect to any MCP-compatible HTTP server exposing tools via an SSE endpoint.\n - Recommended for remote, network-accessible, or containerized tool servers.\n\n- **Stdio (Local Subprocess):**\n - Launches a local MCP server using Python as a subprocess and communicates over stdin/stdout.\n - Recommended for securely sandboxed or development tool servers.\n\n### Configuration\n\nWhen creating an `Agent`, use the `mcp_servers` argument to specify a list of tool servers and their transport types:\n\n```python\nmcp_servers = [\n {\n \"type\": \"sse\",\n \"url\": \"http://localhost:8000/sse\"\n },\n {\n \"type\": \"sse\",\n \"url\": \"https://remote.mcpservers.org/fetch\"\n },\n {\n \"type\": \"stdio\",\n \"script_path\": \"examples/agent_with_mcp_stdio/weather_server.py\"\n }\n]\n```\n\n- For `\"type\": \"sse\"`, the `\"url\"` field must be the **exact SSE endpoint provided by your MCP server** (for example: `/sse`, `/fetch`, or another custom path). No path rewriting or appending is performed by the framework.\n- For `\"type\": \"stdio\"`, provide the path to your MCP server Python script as `\"script_path\"`.\n\n### Usage Example\n\n```python\nfrom primisai.nexus.core import Agent\n\nagent = Agent(\n name=\"RemoteMCPAgent\",\n llm_config=llm_config,\n mcp_servers=[\n {\"type\": \"sse\", \"url\": \"https://remote.mcpservers.org/fetch\"},\n {\"type\": \"stdio\", \"script_path\": \"weather_server.py\"}\n ],\n use_tools=True\n)\n\nagent.chat(\"What is 2 plus 3?\")\n```\n\n### Manual Tool Refresh\n\nIf tools are added, removed, or modified on any MCP server during runtime, call:\n\n```python\nagent.update_mcp_tools()\n```\n\nThis will refresh the list of available MCP tools without restarting the agent.\n\n### Notes\n\n- If your SSE MCP server requires authentication, add an `\"auth_token\"` field to the server dictionary.\n- You can mix and match any number of SSE and stdio MCP servers per agent.\n- Tool schemas are converted automatically for use with function-calling models.\n\nFor a complete working demonstration of using a Supervisor with multiple agents, each utilizing different MCP transport mechanisms (SSE and stdio), see the example and detailed instructions in: [Multiple Agents with MCP](examples/supervisor_multi_mcp/README.md)\n\n## Citation\nIf you find Nexus useful, please consider citing our preprint.\n```bibtex\n@article{sami2025nexus,\n title={Nexus: A Lightweight and Scalable Multi-Agent Framework for Complex Tasks Automation},\n author={Sami, Humza and ul Islam, Mubashir and Charas, Samy and Gandhi, Asav and Gaillardon, Pierre-Emmanuel and Tenace, Valerio},\n journal={arXiv preprint arXiv:2502.19091},\n year={2025}\n}\n```\n\nIf you leveraged the Architect in your work, please consider citing our dedicated paper as well.\n```bibtex\n@article{sami2025adaptive,\n title={Adaptive Multi-Agent Reasoning via Automated Workflow Generation},\n author={Sami, Humza and ul Islam, Mubashir and Gaillardon, Pierre-Emmanuel and Tenace, Valerio},\n journal={arXiv preprint arXiv:2507.14393},\n year={2025}\n}\n```\n\n## License\n\nThis project is licensed under the MIT License.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Nexus is a powerful and flexible Python package for managing AI agents and coordinating complex tasks using LLMs.",
"version": "0.8.1",
"project_urls": {
"changelog": "https://github.com/PrimisAI/nexus/blob/main/CHANGELOG.md",
"homepage": "https://github.com/PrimisAI/nexus",
"issues": "https://github.com/PrimisAI/nexus/issues",
"repository": "https://github.com/PrimisAI/nexus.git"
},
"split_keywords": [
"ai",
" llm",
" framework",
" ai agents"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0de87783c20bb83ea756d37dc4980429227a050621946af548fe0d290a561ac2",
"md5": "102abb7ec34522684db4ea218dda1f41",
"sha256": "c87279a71d39e8eaa60085ef0fe6b7e7c3ea74314371faa1cb91150d336c1fd2"
},
"downloads": -1,
"filename": "primisai-0.8.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "102abb7ec34522684db4ea218dda1f41",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 90563,
"upload_time": "2025-07-25T23:14:54",
"upload_time_iso_8601": "2025-07-25T23:14:54.993966Z",
"url": "https://files.pythonhosted.org/packages/0d/e8/7783c20bb83ea756d37dc4980429227a050621946af548fe0d290a561ac2/primisai-0.8.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f74c15697eed2dc12c552f6e33f2f4c36553fae5c20e76e01e14e5cfedb2102a",
"md5": "1a4209fd5838bffad9f0c273825891a9",
"sha256": "241f6d932a35ab89eb884c36a3652d1d82cb0e627b406e9e83523fb9ea711a17"
},
"downloads": -1,
"filename": "primisai-0.8.1.tar.gz",
"has_sig": false,
"md5_digest": "1a4209fd5838bffad9f0c273825891a9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 71365,
"upload_time": "2025-07-25T23:14:56",
"upload_time_iso_8601": "2025-07-25T23:14:56.183613Z",
"url": "https://files.pythonhosted.org/packages/f7/4c/15697eed2dc12c552f6e33f2f4c36553fae5c20e76e01e14e5cfedb2102a/primisai-0.8.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 23:14:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PrimisAI",
"github_project": "nexus",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "openai",
"specs": [
[
"==",
"1.66.3"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
"==",
"1.0.1"
]
]
},
{
"name": "streamlit",
"specs": [
[
">=",
"1.38.0"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"8.3.4"
]
]
},
{
"name": "PyYAML",
"specs": [
[
"==",
"6.0.2"
]
]
},
{
"name": "mcp",
"specs": [
[
">=",
"1.10.0"
]
]
}
],
"lcname": "primisai"
}
JSON
