# sumitkrsah05/agent-test architecture

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

- Interactive diagram: https://gitdiagram.com/sumitkrsah05/agent-test
- Repository: https://github.com/sumitkrsah05/agent-test

## Overview

Swarn is an autonomous ML engineering platform with two complementary task paths: an interactive tool-using agent and a solution-tree search workflow for iterative model experiments. Users initiate work through the CLI; the agent path dispatches tools, while search drafts, runs, reviews, and improves candidate solutions under budgets and a validation contract. The wider platform includes data and ML capabilities, document intelligence, persistent learning, evaluation, and MCP/web interfaces. Some subsystems are represented from README claims and the source index rather than inspected implementations, so their internal links are limited to documented relationships.

Main entry points: [`agent/ml/search/runner.py`](https://github.com/sumitkrsah05/agent-test/blob/main/agent/ml/search/runner.py) (Tree search runner), [`agent/core/agent_loop.py`](https://github.com/sumitkrsah05/agent-test/blob/main/agent/core/agent_loop.py) (Agent loop), [`agent/cli.py`](https://github.com/sumitkrsah05/agent-test/blob/main/agent/cli.py) (CLI), [`agent/web/dashboard.py`](https://github.com/sumitkrsah05/agent-test/blob/main/agent/web/dashboard.py) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and orchestration"]
  node_cli["CLI<br/>[cli.py]"]
  node_agent_loop["Agent loop<br/>[agent_loop.py]"]
  node_orchestrator["Role orchestrator<br/>[orchestrator.py]"]
end

subgraph group_agent_runtime["Agent runtime"]
  node_tool_registry["Tool registry<br/>[tools.py]"]
  node_llm["LLM routing<br/>[router.py]"]
  node_execution["Sandbox execution<br/>[execution.py]"]
  node_correction["Self-correction<br/>[self_correction.py]"]
end

subgraph group_ml_search["ML engineering"]
  node_data_ingest["Data ingestion<br/>[pipeline.py]"]
  node_data_analysis["Data analysis<br/>[analysis.py]"]
  node_data_clean["Data cleaning<br/>[cleaner.py]"]
  node_feature_engineering["Feature engineering"]
  node_model_training["Model training<br/>[model_training.py]"]
  node_ml_evaluation["ML evaluation<br/>[evaluation.py]"]
  node_deployment["Model deployment<br/>[deployment.py]"]
  node_search_runner["Tree search runner<br/>[runner.py]"]
  node_search_policy["Search policy<br/>[agent.py]"]
  node_search_journal[("Run journal<br/>[journal.py]")]
  node_search_contract["Validation contract<br/>[contract.py]"]
  node_llm_eval["LLM evaluation<br/>[runner.py]"]
end

subgraph group_knowledge_docs["Knowledge and documents"]
  node_knowledge[("Cross-run learning<br/>[knowledge.py]")]
  node_repo_rag[("Repository RAG<br/>[context_engine.py]")]
  node_multimodal_rag["Multimodal RAG<br/>[multimodal_rag.py]"]
  node_doc_intelligence["Document intelligence"]
  node_doc_qa["Document Q&amp;A<br/>[doc_qa.py]"]
  node_doc_store[("Document store<br/>[doc_store.py]")]
end

subgraph group_platform["Platform services"]
  node_mcp["MCP interface<br/>[mcp_server.py]"]
  node_dashboard["Dashboard<br/>[dashboard.py]"]
  node_sessions[("Session memory<br/>[memory.py]")]
  node_observability["Observability<br/>[observability.py]"]
  node_data_api["Data API<br/>[data_api.py]"]
  node_evaluation_api["Evaluation API<br/>[eval_api.py]"]
end

node_user(("User"))

node_user -->|"submits task"| node_cli
node_cli -->|"starts agent"| node_agent_loop
node_cli -->|"starts team run"| node_orchestrator
node_agent_loop -->|"requests model"| node_llm
node_agent_loop -->|"dispatches tools"| node_tool_registry
node_agent_loop -->|"assesses results"| node_correction
node_tool_registry -->|"runs generated code"| node_execution
node_tool_registry -->|"loads datasets"| node_data_ingest
node_tool_registry -->|"invokes analysis"| node_data_analysis
node_tool_registry -->|"invokes engineering"| node_feature_engineering
node_orchestrator -->|"runs role agents"| node_agent_loop
node_data_ingest -->|"profiles datasets"| node_data_analysis
node_data_ingest -->|"provides datasets"| node_data_clean
node_data_ingest -->|"feeds features"| node_feature_engineering
node_feature_engineering -.->|"prepares training"| node_model_training
node_model_training -.->|"evaluates models"| node_ml_evaluation
node_ml_evaluation -.->|"supports deployment"| node_deployment
node_user -->|"requests solve"| node_search_runner
node_cli -->|"starts search"| node_search_runner
node_search_runner -->|"selects actions"| node_search_policy
node_search_runner -->|"executes candidates"| node_execution
node_search_runner -->|"checks candidates"| node_search_contract
node_search_runner -->|"records attempts"| node_search_journal
node_search_runner -.->|"requests drafts"| node_llm
node_search_runner -.->|"learns across runs"| node_knowledge
node_agent_loop -->|"queries code context"| node_repo_rag
node_multimodal_rag -->|"shares index"| node_repo_rag
node_doc_qa -->|"uses extraction"| node_doc_intelligence
node_doc_qa -->|"retrieves documents"| node_doc_store
node_doc_intelligence -->|"indexes documents"| node_multimodal_rag
node_cli -->|"serves MCP"| node_mcp
node_cli -->|"serves dashboard"| node_dashboard
node_dashboard -->|"reads search runs"| node_search_journal
node_dashboard -->|"reads playbook"| node_knowledge
node_dashboard -->|"reads sessions"| node_sessions
node_dashboard -->|"uses data API"| node_data_api
node_dashboard -->|"uses evaluation API"| node_evaluation_api
node_agent_loop -.->|"stores history"| node_sessions
node_orchestrator -->|"shares hooks"| node_observability
node_user -.->|"requests evaluation"| node_llm_eval

click node_cli "https://github.com/sumitkrsah05/agent-test/blob/main/agent/cli.py"
click node_agent_loop "https://github.com/sumitkrsah05/agent-test/blob/main/agent/core/agent_loop.py"
click node_orchestrator "https://github.com/sumitkrsah05/agent-test/blob/main/agent/core/orchestrator.py"
click node_tool_registry "https://github.com/sumitkrsah05/agent-test/blob/main/agent/runtime/tools.py"
click node_llm "https://github.com/sumitkrsah05/agent-test/blob/main/agent/llm/router.py"
click node_execution "https://github.com/sumitkrsah05/agent-test/blob/main/agent/runtime/execution.py"
click node_correction "https://github.com/sumitkrsah05/agent-test/blob/main/agent/core/self_correction.py"
click node_data_ingest "https://github.com/sumitkrsah05/agent-test/blob/main/agent/data/pipeline.py"
click node_data_analysis "https://github.com/sumitkrsah05/agent-test/blob/main/agent/data/analysis.py"
click node_data_clean "https://github.com/sumitkrsah05/agent-test/blob/main/agent/data/cleaner.py"
click node_feature_engineering "https://github.com/sumitkrsah05/agent-test/blob/main/agent/ml/feature_engineering.py"
click node_model_training "https://github.com/sumitkrsah05/agent-test/blob/main/agent/ml/model_training.py"
click node_ml_evaluation "https://github.com/sumitkrsah05/agent-test/blob/main/agent/ml/evaluation.py"
click node_deployment "https://github.com/sumitkrsah05/agent-test/blob/main/agent/ml/deployment.py"
click node_search_runner "https://github.com/sumitkrsah05/agent-test/blob/main/agent/ml/search/runner.py"
click node_search_policy "https://github.com/sumitkrsah05/agent-test/blob/main/agent/ml/search/agent.py"
click node_search_journal "https://github.com/sumitkrsah05/agent-test/blob/main/agent/ml/search/journal.py"
click node_search_contract "https://github.com/sumitkrsah05/agent-test/blob/main/agent/ml/search/contract.py"
click node_knowledge "https://github.com/sumitkrsah05/agent-test/blob/main/agent/memory/knowledge.py"
click node_repo_rag "https://github.com/sumitkrsah05/agent-test/blob/main/agent/memory/context_engine.py"
click node_multimodal_rag "https://github.com/sumitkrsah05/agent-test/blob/main/agent/memory/multimodal_rag.py"
click node_doc_intelligence "https://github.com/sumitkrsah05/agent-test/blob/main/swarn/capabilities/doc_intelligence.py"
click node_doc_qa "https://github.com/sumitkrsah05/agent-test/blob/main/swarn/capabilities/doc_qa.py"
click node_doc_store "https://github.com/sumitkrsah05/agent-test/blob/main/swarn/capabilities/doc_store.py"
click node_llm_eval "https://github.com/sumitkrsah05/agent-test/blob/main/swarn/capabilities/llm_eval/runner.py"
click node_mcp "https://github.com/sumitkrsah05/agent-test/blob/main/agent/integrations/mcp_server.py"
click node_dashboard "https://github.com/sumitkrsah05/agent-test/blob/main/agent/web/dashboard.py"
click node_sessions "https://github.com/sumitkrsah05/agent-test/blob/main/agent/memory/memory.py"
click node_observability "https://github.com/sumitkrsah05/agent-test/blob/main/agent/observability/observability.py"
click node_data_api "https://github.com/sumitkrsah05/agent-test/blob/main/agent/web/data_api.py"
click node_evaluation_api "https://github.com/sumitkrsah05/agent-test/blob/main/agent/web/eval_api.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_agent_loop,node_orchestrator,node_user toneBlue
class node_tool_registry,node_llm,node_execution,node_correction toneAmber
class node_data_ingest,node_data_analysis,node_data_clean,node_feature_engineering,node_model_training,node_ml_evaluation,node_deployment,node_search_runner,node_search_policy,node_search_journal,node_search_contract,node_llm_eval toneMint
class node_knowledge,node_repo_rag,node_multimodal_rag,node_doc_intelligence,node_doc_qa,node_doc_store toneRose
class node_mcp,node_dashboard,node_sessions,node_observability,node_data_api,node_evaluation_api toneIndigo
```

## Components

### Entry and orchestration

- [CLI](https://github.com/sumitkrsah05/agent-test/blob/main/agent/cli.py): `agent/cli.py`
- [Agent loop](https://github.com/sumitkrsah05/agent-test/blob/main/agent/core/agent_loop.py): `agent/core/agent_loop.py`
- [Role orchestrator](https://github.com/sumitkrsah05/agent-test/blob/main/agent/core/orchestrator.py): `agent/core/orchestrator.py`

### Agent runtime

- [Tool registry](https://github.com/sumitkrsah05/agent-test/blob/main/agent/runtime/tools.py): `agent/runtime/tools.py`
- [LLM routing](https://github.com/sumitkrsah05/agent-test/blob/main/agent/llm/router.py): `agent/llm/router.py`
- [Sandbox execution](https://github.com/sumitkrsah05/agent-test/blob/main/agent/runtime/execution.py): `agent/runtime/execution.py`
- [Self-correction](https://github.com/sumitkrsah05/agent-test/blob/main/agent/core/self_correction.py): `agent/core/self_correction.py`

### ML engineering

- [Data ingestion](https://github.com/sumitkrsah05/agent-test/blob/main/agent/data/pipeline.py): `agent/data/pipeline.py`
- [Data analysis](https://github.com/sumitkrsah05/agent-test/blob/main/agent/data/analysis.py): `agent/data/analysis.py`
- [Data cleaning](https://github.com/sumitkrsah05/agent-test/blob/main/agent/data/cleaner.py): `agent/data/cleaner.py`
- [Feature engineering](https://github.com/sumitkrsah05/agent-test/blob/main/agent/ml/feature_engineering.py): `agent/ml/feature_engineering.py`
- [Model training](https://github.com/sumitkrsah05/agent-test/blob/main/agent/ml/model_training.py): `agent/ml/model_training.py`
- [ML evaluation](https://github.com/sumitkrsah05/agent-test/blob/main/agent/ml/evaluation.py): `agent/ml/evaluation.py`
- [Model deployment](https://github.com/sumitkrsah05/agent-test/blob/main/agent/ml/deployment.py): `agent/ml/deployment.py`
- [Tree search runner](https://github.com/sumitkrsah05/agent-test/blob/main/agent/ml/search/runner.py): `agent/ml/search/runner.py`
- [Search policy](https://github.com/sumitkrsah05/agent-test/blob/main/agent/ml/search/agent.py): `agent/ml/search/agent.py`
- [Run journal](https://github.com/sumitkrsah05/agent-test/blob/main/agent/ml/search/journal.py): `agent/ml/search/journal.py`
- [Validation contract](https://github.com/sumitkrsah05/agent-test/blob/main/agent/ml/search/contract.py): `agent/ml/search/contract.py`
- [LLM evaluation](https://github.com/sumitkrsah05/agent-test/blob/main/swarn/capabilities/llm_eval/runner.py): `swarn/capabilities/llm_eval/runner.py`

### Knowledge and documents

- [Cross-run learning](https://github.com/sumitkrsah05/agent-test/blob/main/agent/memory/knowledge.py): `agent/memory/knowledge.py`
- [Repository RAG](https://github.com/sumitkrsah05/agent-test/blob/main/agent/memory/context_engine.py): `agent/memory/context_engine.py`
- [Multimodal RAG](https://github.com/sumitkrsah05/agent-test/blob/main/agent/memory/multimodal_rag.py): `agent/memory/multimodal_rag.py`
- [Document intelligence](https://github.com/sumitkrsah05/agent-test/blob/main/swarn/capabilities/doc_intelligence.py): `swarn/capabilities/doc_intelligence.py`
- [Document Q&A](https://github.com/sumitkrsah05/agent-test/blob/main/swarn/capabilities/doc_qa.py): `swarn/capabilities/doc_qa.py`
- [Document store](https://github.com/sumitkrsah05/agent-test/blob/main/swarn/capabilities/doc_store.py): `swarn/capabilities/doc_store.py`

### Platform services

- [MCP interface](https://github.com/sumitkrsah05/agent-test/blob/main/agent/integrations/mcp_server.py): `agent/integrations/mcp_server.py`
- [Dashboard](https://github.com/sumitkrsah05/agent-test/blob/main/agent/web/dashboard.py): `agent/web/dashboard.py`
- [Session memory](https://github.com/sumitkrsah05/agent-test/blob/main/agent/memory/memory.py): `agent/memory/memory.py`
- [Observability](https://github.com/sumitkrsah05/agent-test/blob/main/agent/observability/observability.py): `agent/observability/observability.py`
- [Data API](https://github.com/sumitkrsah05/agent-test/blob/main/agent/web/data_api.py): `agent/web/data_api.py`
- [Evaluation API](https://github.com/sumitkrsah05/agent-test/blob/main/agent/web/eval_api.py): `agent/web/eval_api.py`

### Other components

- **User**

## Connections

- User → CLI: submits task
- CLI → Agent loop: starts agent (evidence: `agent/cli.py`)
- CLI → Role orchestrator: starts team run (evidence: `agent/cli.py`)
- Agent loop → LLM routing: requests model (evidence: `agent/core/agent_loop.py`)
- Agent loop → Tool registry: dispatches tools (evidence: `agent/core/agent_loop.py`)
- Agent loop → Self-correction: assesses results (evidence: `agent/core/agent_loop.py`)
- Tool registry → Sandbox execution: runs generated code (evidence: `agent/runtime/tools.py`)
- Tool registry → Data ingestion: loads datasets (evidence: `agent/runtime/tools.py`)
- Tool registry → Data analysis: invokes analysis (evidence: `agent/runtime/tools.py`)
- Tool registry → Feature engineering: invokes engineering (evidence: `agent/runtime/tools.py`)
- Role orchestrator → Agent loop: runs role agents (evidence: `agent/core/orchestrator.py`)
- Data ingestion → Data analysis: profiles datasets (evidence: `agent/data/analysis.py`)
- Data ingestion → Data cleaning: provides datasets (evidence: `agent/data/cleaner.py`)
- Data ingestion → Feature engineering: feeds features (evidence: `agent/ml/feature_engineering.py`)
- Feature engineering → Model training: prepares training
- Model training → ML evaluation: evaluates models
- ML evaluation → Model deployment: supports deployment
- User → Tree search runner: requests solve
- CLI → Tree search runner: starts search
- Tree search runner → Search policy: selects actions
- Tree search runner → Sandbox execution: executes candidates
- Tree search runner → Validation contract: checks candidates
- Tree search runner → Run journal: records attempts
- Tree search runner → LLM routing: requests drafts
- Tree search runner → Cross-run learning: learns across runs
- Agent loop → Repository RAG: queries code context
- Multimodal RAG → Repository RAG: shares index (evidence: `agent/memory/multimodal_rag.py`)
- Document Q&A → Document intelligence: uses extraction (evidence: `swarn/capabilities/doc_qa.py`)
- Document Q&A → Document store: retrieves documents (evidence: `swarn/capabilities/doc_qa.py`)
- Document intelligence → Multimodal RAG: indexes documents (evidence: `swarn/capabilities/doc_intelligence.py`)
- CLI → MCP interface: serves MCP (evidence: `agent/cli.py`)
- CLI → Dashboard: serves dashboard
- Dashboard → Run journal: reads search runs (evidence: `agent/web/dashboard.py`)
- Dashboard → Cross-run learning: reads playbook (evidence: `agent/web/dashboard.py`)
- Dashboard → Session memory: reads sessions (evidence: `agent/web/dashboard.py`)
- Dashboard → Data API: uses data API (evidence: `agent/web/dashboard.py`)
- Dashboard → Evaluation API: uses evaluation API (evidence: `agent/web/dashboard.py`)
- Agent loop → Session memory: stores history (evidence: `agent/core/agent_loop.py`)
- Role orchestrator → Observability: shares hooks (evidence: `agent/core/orchestrator.py`)
- User → LLM evaluation: requests evaluation
