# cognizant-ai-lab/neuro-san architecture

> Architecture diagram of the GitHub repository cognizant-ai-lab/neuro-san, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cognizant-ai-lab/neuro-san
- Repository: https://github.com/cognizant-ai-lab/neuro-san

## Overview

Neuro SAN is a Python library and service for defining and running data-driven multi-agent networks. The primary workflow is a user sending a prompt through a direct or HTTP client; the selected network’s front-man coordinates agent/tool work and returns a response. Network configuration, LLM-provider policies, coded tools, messaging, MCP, authorization, and service-side network updates are distinct capabilities. The graph combines README-documented behavior with relationships visible in the supplied source index and excerpts; unsampled implementation links are omitted where evidence is unavailable.

Main entry points: [`neuro_san/client/agent_session_factory.py`](https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/client/agent_session_factory.py) (Session factories), [`neuro_san/service/generic/async_agent_service.py`](https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/service/generic/async_agent_service.py) (Agent service), [`neuro_san/client/agent_cli.py`](https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/client/agent_cli.py) (Agent CLI), [`neuro_san/session/http_service_agent_session.py`](https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/session/http_service_agent_session.py) (HTTP session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client and sessions"]
  node_cli["Agent CLI<br/>[agent_cli.py]"]
  node_session_factories["Session factories"]
  node_direct_session["Direct session"]
  node_http_session["HTTP session"]
  node_session_contract["Session contract<br/>[agent_session.py]"]
end

subgraph group_runtime["Network runtime"]
  node_network["Agent network<br/>[agent_network.py]"]
  node_config_filters["Config resolution"]
  node_activations["Agent activations"]
  node_chat_session["Chat session"]
  node_message_processing["Message processing"]
end

subgraph group_execution["Models and tools"]
  node_llm_policies["LLM providers"]
  node_tool_runtime["Tool runtime"]
  node_coded_tools["Coded tools"]
end

subgraph group_service["Service and network management"]
  node_mcp_service["MCP service"]
  node_http_service["HTTP service<br/>[http_server.py]"]
  node_service_agent["Agent service"]
  node_authorization["Authorization"]
  node_network_storage[("Network storage")]
  node_manifest_restorer["Manifest restore"]
  node_registry_updater["Registry updater"]
  node_reservations[("Reservations")]
  node_temp_updater["Temporary deployments"]
  node_reservation_interface["Reservation data<br/>[reservation.py]"]
end

node_user(("User"))

node_user -->|"submits prompt"| node_cli
node_cli -.->|"creates session"| node_session_factories
node_session_factories -.->|"opens direct"| node_direct_session
node_session_factories -.->|"opens HTTP"| node_http_session
node_direct_session -->|"implements"| node_session_contract
node_http_session -->|"implements"| node_session_contract
node_cli -->|"uses HTTP"| node_http_session
node_session_factories -->|"loads network"| node_network
node_network -.->|"resolves config"| node_config_filters
node_chat_session -.->|"runs network"| node_network
node_chat_session -.->|"processes messages"| node_message_processing
node_activations -.->|"calls models"| node_llm_policies
node_activations -.->|"dispatches tools"| node_tool_runtime
node_tool_runtime -->|"creates tools"| node_coded_tools
node_http_service -.->|"serves agents"| node_service_agent
node_service_agent -.->|"gets networks"| node_network_storage
node_service_agent -.->|"checks access"| node_authorization
node_service_agent -->|"exposes MCP"| node_mcp_service
node_registry_updater -->|"restores manifest"| node_manifest_restorer
node_registry_updater -->|"updates networks"| node_network_storage
node_temp_updater -->|"deploys reservations"| node_reservations
node_reservations -->|"stores records"| node_reservation_interface

click node_cli "https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/client/agent_cli.py"
click node_session_factories "https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/client/agent_session_factory.py"
click node_direct_session "https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/session/direct_agent_session.py"
click node_http_session "https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/session/http_service_agent_session.py"
click node_session_contract "https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/interfaces/agent_session.py"
click node_network "https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/internals/graph/registry/agent_network.py"
click node_config_filters "https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/internals/graph/filters/resolved_network_config_filter.py"
click node_activations "https://github.com/cognizant-ai-lab/neuro-san/tree/main/neuro_san/internals/graph/activations"
click node_chat_session "https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/internals/chat/data_driven_chat_session.py"
click node_message_processing "https://github.com/cognizant-ai-lab/neuro-san/tree/main/neuro_san/message/processors"
click node_llm_policies "https://github.com/cognizant-ai-lab/neuro-san/tree/main/neuro_san/internals/run_context/langchain/llms"
click node_tool_runtime "https://github.com/cognizant-ai-lab/neuro-san/tree/main/neuro_san/internals/run_context/langchain/tools"
click node_coded_tools "https://github.com/cognizant-ai-lab/neuro-san/tree/main/neuro_san/coded_tools"
click node_mcp_service "https://github.com/cognizant-ai-lab/neuro-san/tree/main/neuro_san/service/mcp"
click node_http_service "https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/service/http/server/http_server.py"
click node_service_agent "https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/service/generic/async_agent_service.py"
click node_authorization "https://github.com/cognizant-ai-lab/neuro-san/tree/main/neuro_san/service/authorization"
click node_network_storage "https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/internals/network_providers/agent_network_storage.py"
click node_manifest_restorer "https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/internals/graph/persistence/registry_manifest_restorer.py"
click node_registry_updater "https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/service/watcher/registries/registry_storage_updater.py"
click node_reservations "https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/internals/interfaces/reservations_storage.py"
click node_temp_updater "https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/service/watcher/temp_networks/updater/temp_network_storage_updater.py"
click node_reservation_interface "https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/interfaces/reservation.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_session_factories,node_direct_session,node_http_session,node_session_contract,node_user toneBlue
class node_network,node_config_filters,node_activations,node_chat_session,node_message_processing toneAmber
class node_llm_policies,node_tool_runtime,node_coded_tools toneMint
class node_mcp_service,node_http_service,node_service_agent,node_authorization,node_network_storage,node_manifest_restorer,node_registry_updater,node_reservations,node_temp_updater,node_reservation_interface toneRose
```

## Components

### Client and sessions

- [Agent CLI](https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/client/agent_cli.py): `neuro_san/client/agent_cli.py`
- [Session factories](https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/client/agent_session_factory.py): `neuro_san/client/agent_session_factory.py`
- [Direct session](https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/session/direct_agent_session.py): `neuro_san/session/direct_agent_session.py`
- [HTTP session](https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/session/http_service_agent_session.py): `neuro_san/session/http_service_agent_session.py`
- [Session contract](https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/interfaces/agent_session.py): `neuro_san/interfaces/agent_session.py`

### Network runtime

- [Agent network](https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/internals/graph/registry/agent_network.py): `neuro_san/internals/graph/registry/agent_network.py`
- [Config resolution](https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/internals/graph/filters/resolved_network_config_filter.py): `neuro_san/internals/graph/filters/resolved_network_config_filter.py`
- [Agent activations](https://github.com/cognizant-ai-lab/neuro-san/tree/main/neuro_san/internals/graph/activations): `neuro_san/internals/graph/activations`
- [Chat session](https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/internals/chat/data_driven_chat_session.py): `neuro_san/internals/chat/data_driven_chat_session.py`
- [Message processing](https://github.com/cognizant-ai-lab/neuro-san/tree/main/neuro_san/message/processors): `neuro_san/message/processors`

### Models and tools

- [LLM providers](https://github.com/cognizant-ai-lab/neuro-san/tree/main/neuro_san/internals/run_context/langchain/llms): `neuro_san/internals/run_context/langchain/llms`
- [Tool runtime](https://github.com/cognizant-ai-lab/neuro-san/tree/main/neuro_san/internals/run_context/langchain/tools): `neuro_san/internals/run_context/langchain/tools`
- [Coded tools](https://github.com/cognizant-ai-lab/neuro-san/tree/main/neuro_san/coded_tools): `neuro_san/coded_tools`

### Service and network management

- [MCP service](https://github.com/cognizant-ai-lab/neuro-san/tree/main/neuro_san/service/mcp): `neuro_san/service/mcp`
- [HTTP service](https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/service/http/server/http_server.py): `neuro_san/service/http/server/http_server.py`
- [Agent service](https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/service/generic/async_agent_service.py): `neuro_san/service/generic/async_agent_service.py`
- [Authorization](https://github.com/cognizant-ai-lab/neuro-san/tree/main/neuro_san/service/authorization): `neuro_san/service/authorization`
- [Network storage](https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/internals/network_providers/agent_network_storage.py): `neuro_san/internals/network_providers/agent_network_storage.py`
- [Manifest restore](https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/internals/graph/persistence/registry_manifest_restorer.py): `neuro_san/internals/graph/persistence/registry_manifest_restorer.py`
- [Registry updater](https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/service/watcher/registries/registry_storage_updater.py): `neuro_san/service/watcher/registries/registry_storage_updater.py`
- [Reservations](https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/internals/interfaces/reservations_storage.py): `neuro_san/internals/interfaces/reservations_storage.py`
- [Temporary deployments](https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/service/watcher/temp_networks/updater/temp_network_storage_updater.py): `neuro_san/service/watcher/temp_networks/updater/temp_network_storage_updater.py`
- [Reservation data](https://github.com/cognizant-ai-lab/neuro-san/blob/main/neuro_san/interfaces/reservation.py): `neuro_san/interfaces/reservation.py`

### Other components

- **User**

## Connections

- User → Agent CLI: submits prompt (evidence: `README.md`)
- Agent CLI → Session factories: creates session
- Session factories → Direct session: opens direct
- Session factories → HTTP session: opens HTTP
- Direct session → Session contract: implements
- HTTP session → Session contract: implements (evidence: `neuro_san/session/http_service_agent_session.py`)
- Agent CLI → HTTP session: uses HTTP (evidence: `README.md`)
- Session factories → Agent network: loads network
- Agent network → Config resolution: resolves config
- Chat session → Agent network: runs network
- Chat session → Message processing: processes messages
- Agent activations → LLM providers: calls models
- Agent activations → Tool runtime: dispatches tools
- Tool runtime → Coded tools: creates tools (evidence: `README.md`)
- HTTP service → Agent service: serves agents
- Agent service → Network storage: gets networks
- Agent service → Authorization: checks access
- Agent service → MCP service: exposes MCP (evidence: `README.md`)
- Registry updater → Manifest restore: restores manifest (evidence: `neuro_san/service/watcher/registries/registry_storage_updater.py`)
- Registry updater → Network storage: updates networks (evidence: `neuro_san/service/watcher/registries/registry_storage_updater.py`)
- Temporary deployments → Reservations: deploys reservations (evidence: `neuro_san/service/watcher/temp_networks/updater/temp_network_storage_updater.py`)
- Reservations → Reservation data: stores records (evidence: `neuro_san/internals/interfaces/reservations_storage.py`)
