# ai-setu-yn/ai-runtime architecture

> Architecture diagram of the GitHub repository ai-setu-yn/ai-runtime, 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/ai-setu-yn/ai-runtime
- Repository: https://github.com/ai-setu-yn/ai-runtime

## Overview

AI Runtime is an enterprise orchestration service for answering `/chat` requests through planning, tool execution, observation, and response generation. The graph emphasizes that documented request flow, with supporting security, guardrail, authorization, search, and capability-retrieval subsystems. Edges use README statements or source-index references; several runtime modules were not sampled, so undocumented wiring is omitted.

Main entry points: [`app/agent/agent.py`](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/agent/agent.py) (General agent), [`app/tool_executor/service.py`](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/tool_executor/service.py) (Tool executor), [`app/services/chat_service.py`](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/services/chat_service.py) (Chat service), [`app/api/routes/runtime.py`](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/api/routes/runtime.py) (Chat API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request["Request and agent"]
  node_chat_api["Chat API<br/>[runtime.py]"]
  node_chat_service["Chat service<br/>[chat_service.py]"]
  node_workflow["Workflow manager<br/>[workflow.py]"]
  node_agent["General agent<br/>[agent.py]"]
  node_agent_decision["Agent decisions<br/>[decision.py]"]
  node_agent_observation["Agent observations<br/>[observation.py]"]
  node_agent_memory["Agent memory<br/>[memory.py]"]
  node_runtime_state["Runtime state<br/>[state.py]"]
end

subgraph group_planning["Planning and generation"]
  node_planner["Planner service<br/>[service.py]"]
  node_planner_parser["Planner parser<br/>[parser.py]"]
  node_planner_models["Plan models<br/>[planner.py]"]
  node_gateway["Model gateway<br/>[client.py]"]
  node_response_generator["Response generator"]
end

subgraph group_tools["Tools and integrations"]
  node_tool_executor["Tool executor<br/>[service.py]"]
  node_tool_registry["Tool registry<br/>[service.py]"]
  node_mcp_client["MCP client<br/>[client.py]"]
  node_mcp_servers["MCP servers"]
  node_web_search["Web search<br/>[client.py]"]
end

subgraph group_safety["Security and safety"]
  node_security["Security classifier<br/>[service.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_guardrails["Guardrail engine<br/>[engine.py]"]
  node_guardrail_audit["Guardrail audit<br/>[audit.py]"]
  node_rbac["RBAC authorization<br/>[service.py]"]
end

subgraph group_support["Runtime support"]
  node_capability_retrieval["Capability retrieval<br/>[service.py]"]
  node_capability_repository[("Capability repository<br/>[repository.py]")]
  node_capability_models["Capability models<br/>[models.py]"]
  node_conversation_context["Conversation context<br/>[context.py]"]
  node_request_context["Request context<br/>[request_context.py]"]
end

node_user(("Chat caller"))

node_user -->|"submits chat"| node_chat_api
node_chat_api -->|"routes request"| node_chat_service
node_chat_service -->|"starts workflow"| node_workflow
node_workflow -->|"runs agent"| node_agent
node_agent -->|"plans request"| node_planner
node_planner -->|"requests plan"| node_gateway
node_planner -->|"parses plan"| node_planner_parser
node_planner_parser -->|"produces plan models"| node_planner_models
node_agent -->|"executes plan"| node_tool_executor
node_tool_executor -->|"resolves tools"| node_tool_registry
node_tool_executor -->|"invokes tools"| node_mcp_client
node_mcp_client -->|"calls server"| node_mcp_servers
node_tool_executor -->|"searches web"| node_web_search
node_agent -->|"records observations"| node_agent_observation
node_agent -->|"chooses next step"| node_agent_decision
node_agent -.->|"uses memory"| node_agent_memory
node_agent -->|"finalizes response"| node_response_generator
node_response_generator -->|"generates response"| node_gateway
node_workflow -->|"converts state"| node_runtime_state
node_chat_service -->|"classifies request"| node_security
node_chat_service -->|"checks content"| node_guardrails
node_guardrails -->|"records decisions"| node_guardrail_audit
node_chat_api -.->|"authenticates caller"| node_auth
node_tool_executor -.->|"checks authorization"| node_rbac
node_capability_retrieval -->|"reads and writes"| node_capability_repository
node_capability_retrieval -->|"uses data models"| node_capability_models
node_request_context -->|"sets request context"| node_conversation_context

click node_chat_api "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/api/routes/runtime.py"
click node_chat_service "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/services/chat_service.py"
click node_workflow "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/graph/workflow.py"
click node_agent "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/agent/agent.py"
click node_agent_decision "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/agent/decision.py"
click node_agent_observation "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/agent/observation.py"
click node_agent_memory "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/agent/memory.py"
click node_runtime_state "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/graph/state.py"
click node_planner "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/planner/service.py"
click node_planner_parser "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/planner/parser.py"
click node_planner_models "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/models/planner.py"
click node_gateway "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/model_gateway/client.py"
click node_response_generator "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/graph/nodes/response_generator.py"
click node_tool_executor "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/tool_executor/service.py"
click node_tool_registry "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/tool_registry/service.py"
click node_mcp_client "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/mcp_client/client/client.py"
click node_web_search "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/web_search/client.py"
click node_security "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/security/service.py"
click node_auth "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/security/auth.py"
click node_guardrails "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/guardrails/engine.py"
click node_guardrail_audit "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/guardrails/audit.py"
click node_rbac "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/rbac/service.py"
click node_capability_retrieval "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/capability_retrieval/service.py"
click node_capability_repository "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/capability_retrieval/repository.py"
click node_capability_models "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/capability_retrieval/models.py"
click node_conversation_context "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/conversation/context.py"
click node_request_context "https://github.com/ai-setu-yn/ai-runtime/blob/main/app/middleware/request_context.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_chat_api,node_chat_service,node_workflow,node_agent,node_agent_decision,node_agent_observation,node_agent_memory,node_runtime_state toneBlue
class node_planner,node_planner_parser,node_planner_models,node_gateway,node_response_generator toneAmber
class node_tool_executor,node_tool_registry,node_mcp_client,node_mcp_servers,node_web_search toneMint
class node_security,node_auth,node_guardrails,node_guardrail_audit,node_rbac toneRose
class node_capability_retrieval,node_capability_repository,node_capability_models,node_conversation_context,node_request_context,node_user toneIndigo
```

## Components

### Request and agent

- [Chat API](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/api/routes/runtime.py): `app/api/routes/runtime.py`
- [Chat service](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/services/chat_service.py): `app/services/chat_service.py`
- [Workflow manager](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/graph/workflow.py): `app/graph/workflow.py`
- [General agent](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/agent/agent.py): `app/agent/agent.py`
- [Agent decisions](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/agent/decision.py): `app/agent/decision.py`
- [Agent observations](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/agent/observation.py): `app/agent/observation.py`
- [Agent memory](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/agent/memory.py): `app/agent/memory.py`
- [Runtime state](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/graph/state.py): `app/graph/state.py`

### Planning and generation

- [Planner service](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/planner/service.py): `app/planner/service.py`
- [Planner parser](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/planner/parser.py): `app/planner/parser.py`
- [Plan models](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/models/planner.py): `app/models/planner.py`
- [Model gateway](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/model_gateway/client.py): `app/model_gateway/client.py`
- [Response generator](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/graph/nodes/response_generator.py): `app/graph/nodes/response_generator.py`

### Tools and integrations

- [Tool executor](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/tool_executor/service.py): `app/tool_executor/service.py`
- [Tool registry](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/tool_registry/service.py): `app/tool_registry/service.py`
- [MCP client](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/mcp_client/client/client.py): `app/mcp_client/client/client.py`
- **MCP servers**
- [Web search](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/web_search/client.py): `app/web_search/client.py`

### Security and safety

- [Security classifier](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/security/service.py): `app/security/service.py`
- [Authentication](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/security/auth.py): `app/security/auth.py`
- [Guardrail engine](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/guardrails/engine.py): `app/guardrails/engine.py`
- [Guardrail audit](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/guardrails/audit.py): `app/guardrails/audit.py`
- [RBAC authorization](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/rbac/service.py): `app/rbac/service.py`

### Runtime support

- [Capability retrieval](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/capability_retrieval/service.py): `app/capability_retrieval/service.py`
- [Capability repository](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/capability_retrieval/repository.py): `app/capability_retrieval/repository.py`
- [Capability models](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/capability_retrieval/models.py): `app/capability_retrieval/models.py`
- [Conversation context](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/conversation/context.py): `app/conversation/context.py`
- [Request context](https://github.com/ai-setu-yn/ai-runtime/blob/main/app/middleware/request_context.py): `app/middleware/request_context.py`

### Other components

- **Chat caller**

## Connections

- Chat caller → Chat API: submits chat (evidence: `README.md`)
- Chat API → Chat service: routes request (evidence: `README.md`)
- Chat service → Workflow manager: starts workflow (evidence: `README.md`)
- Workflow manager → General agent: runs agent (evidence: `README.md`)
- General agent → Planner service: plans request (evidence: `README.md`)
- Planner service → Model gateway: requests plan (evidence: `README.md`)
- Planner service → Planner parser: parses plan (evidence: `app/planner/parser.py`)
- Planner parser → Plan models: produces plan models (evidence: `app/planner/parser.py`)
- General agent → Tool executor: executes plan (evidence: `README.md`)
- Tool executor → Tool registry: resolves tools (evidence: `app/tool_executor/service.py`)
- Tool executor → MCP client: invokes tools (evidence: `app/tool_executor/service.py`)
- MCP client → MCP servers: calls server (evidence: `README.md`)
- Tool executor → Web search: searches web (evidence: `app/tool_executor/service.py`)
- General agent → Agent observations: records observations (evidence: `README.md`)
- General agent → Agent decisions: chooses next step (evidence: `README.md`)
- General agent → Agent memory: uses memory
- General agent → Response generator: finalizes response (evidence: `README.md`)
- Response generator → Model gateway: generates response (evidence: `README.md`)
- Workflow manager → Runtime state: converts state (evidence: `README.md`)
- Chat service → Security classifier: classifies request (evidence: `app/services/chat_service.py`)
- Chat service → Guardrail engine: checks content (evidence: `app/services/chat_service.py`)
- Guardrail engine → Guardrail audit: records decisions (evidence: `app/guardrails/engine.py`)
- Chat API → Authentication: authenticates caller
- Tool executor → RBAC authorization: checks authorization
- Capability retrieval → Capability repository: reads and writes (evidence: `app/capability_retrieval/service.py`)
- Capability retrieval → Capability models: uses data models (evidence: `app/capability_retrieval/service.py`)
- Request context → Conversation context: sets request context (evidence: `app/middleware/request_context.py`)
