# ashjha0/agentic-trader architecture

> Architecture diagram of the GitHub repository ashjha0/agentic-trader, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ashjha0/agentic-trader
- Repository: https://github.com/ashjha0/agentic-trader

## Overview

AgenticTrader is a research-and-education trading desk for equities and FX, not a broker-connected execution system. Its main workflow gathers market evidence, runs specialized agents to produce a sized and explained decision, then audits the result; the agentic harness validates plans, gates tool calls, and invokes a critic and reporter. Separate branches cover portfolio and quant research, backtesting and evaluation, and Python/C++ quant functionality. Several modules are represented from the tree and README rather than inspected source, so their internal call links are omitted where evidence is limited.

Main entry points: [`agentic_trader/agentic/harness.py`](https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/agentic/harness.py) (Desk harness), [`agentic_trader/quant`](https://github.com/ashjha0/agentic-trader/tree/main/agentic_trader/quant) (Quant core), [`agentic_trader/backtest.py`](https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/backtest.py) (Walk-forward backtest), [`agentic_trader/agents`](https://github.com/ashjha0/agentic-trader/tree/main/agentic_trader/agents) (Specialist agents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desk["Agentic desk"]
  node_harness["Desk harness<br/>[harness.py]"]
  node_agents["Specialist agents"]
  node_state["Decision state<br/>[state.py]"]
  node_llm["Model access<br/>[llm.py]"]
end

subgraph group_governance["Agentic controls"]
  node_tools["Tool registry<br/>[tools.py]"]
  node_policy["Tool policy<br/>[policy.py]"]
  node_evidence["Evidence records<br/>[evidence.py]"]
  node_critic["Decision critic<br/>[critic.py]"]
  node_reporter["Audited reports<br/>[reporter.py]"]
  node_planner["Plan validation<br/>[planner.py]"]
  node_api["HTTP and MCP"]
end

subgraph group_market["Market and research"]
  node_marketdata["Market providers<br/>[base.py]"]
  node_desktools["Desk capabilities<br/>[servers.py]"]
  node_knowledge["Runbook retrieval<br/>[rag.py]"]
end

subgraph group_quant["Quant and portfolio"]
  node_alphas["Alpha research<br/>[alpha.py]"]
  node_execution["Execution algorithms<br/>[algo.py]"]
  node_portfolio["Portfolio construction<br/>[portfolio.py]"]
  node_quantcore["Quant core"]
  node_cppcore["C++ engine<br/>[backtest.hpp]"]
end

subgraph group_evaluation["Backtest and evaluation"]
  node_backtest["Walk-forward backtest<br/>[backtest.py]"]
  node_stats["Backtest statistics<br/>[stats.py]"]
  node_evaluation["Evaluation protocol<br/>[evaluation.py]"]
end

node_user(("Research user"))

node_user -->|"requests decision"| node_harness
node_harness -->|"validates plan"| node_planner
node_harness -->|"dispatches tools"| node_tools
node_tools -->|"checks policy"| node_policy
node_tools -->|"records evidence"| node_evidence
node_harness -->|"runs team"| node_agents
node_agents -->|"writes decisions"| node_state
node_agents -->|"requests completions"| node_llm
node_harness -->|"checks result"| node_critic
node_harness -->|"builds audit report"| node_reporter
node_desktools -->|"reads market data"| node_marketdata
node_desktools -->|"retrieves guidance"| node_knowledge
node_harness -->|"configures capabilities"| node_desktools
node_api -.->|"serves desk runs"| node_harness
node_backtest -->|"runs simulation"| node_quantcore
node_backtest -->|"propagates graph"| node_agents
node_backtest -->|"loads prices"| node_marketdata
node_quantcore -->|"uses compiled backend"| node_cppcore
node_portfolio -->|"uses quant functions"| node_quantcore
node_execution -->|"uses quant functions"| node_quantcore
node_alphas -->|"uses quant functions"| node_quantcore
node_evaluation -->|"evaluates runs"| node_backtest
node_evaluation -->|"computes metrics"| node_stats

click node_harness "https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/agentic/harness.py"
click node_agents "https://github.com/ashjha0/agentic-trader/tree/main/agentic_trader/agents"
click node_state "https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/state.py"
click node_llm "https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/llm.py"
click node_tools "https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/agentic/tools.py"
click node_policy "https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/agentic/policy.py"
click node_evidence "https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/agentic/evidence.py"
click node_critic "https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/agentic/critic.py"
click node_reporter "https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/agentic/reporter.py"
click node_planner "https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/agentic/planner.py"
click node_marketdata "https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/data/base.py"
click node_desktools "https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/agentic/servers.py"
click node_knowledge "https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/agentic/rag.py"
click node_alphas "https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/alpha.py"
click node_execution "https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/algo.py"
click node_portfolio "https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/portfolio.py"
click node_quantcore "https://github.com/ashjha0/agentic-trader/tree/main/agentic_trader/quant"
click node_cppcore "https://github.com/ashjha0/agentic-trader/blob/main/cpp/include/at/backtest.hpp"
click node_backtest "https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/backtest.py"
click node_stats "https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/stats.py"
click node_evaluation "https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/evaluation.py"
click node_api "https://github.com/ashjha0/agentic-trader/tree/main/agentic_trader/agentic"

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_harness,node_agents,node_state,node_llm,node_user toneBlue
class node_tools,node_policy,node_evidence,node_critic,node_reporter,node_planner,node_api toneAmber
class node_marketdata,node_desktools,node_knowledge toneMint
class node_alphas,node_execution,node_portfolio,node_quantcore,node_cppcore toneRose
class node_backtest,node_stats,node_evaluation toneIndigo
```

## Components

### Agentic desk

- [Desk harness](https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/agentic/harness.py): `agentic_trader/agentic/harness.py`
- [Specialist agents](https://github.com/ashjha0/agentic-trader/tree/main/agentic_trader/agents): `agentic_trader/agents`
- [Decision state](https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/state.py): `agentic_trader/state.py`
- [Model access](https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/llm.py): `agentic_trader/llm.py`

### Agentic controls

- [Tool registry](https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/agentic/tools.py): `agentic_trader/agentic/tools.py`
- [Tool policy](https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/agentic/policy.py): `agentic_trader/agentic/policy.py`
- [Evidence records](https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/agentic/evidence.py): `agentic_trader/agentic/evidence.py`
- [Decision critic](https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/agentic/critic.py): `agentic_trader/agentic/critic.py`
- [Audited reports](https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/agentic/reporter.py): `agentic_trader/agentic/reporter.py`
- [Plan validation](https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/agentic/planner.py): `agentic_trader/agentic/planner.py`
- [HTTP and MCP](https://github.com/ashjha0/agentic-trader/tree/main/agentic_trader/agentic): `agentic_trader/agentic`

### Market and research

- [Market providers](https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/data/base.py): `agentic_trader/data/base.py`
- [Desk capabilities](https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/agentic/servers.py): `agentic_trader/agentic/servers.py`
- [Runbook retrieval](https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/agentic/rag.py): `agentic_trader/agentic/rag.py`

### Quant and portfolio

- [Alpha research](https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/alpha.py): `agentic_trader/alpha.py`
- [Execution algorithms](https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/algo.py): `agentic_trader/algo.py`
- [Portfolio construction](https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/portfolio.py): `agentic_trader/portfolio.py`
- [Quant core](https://github.com/ashjha0/agentic-trader/tree/main/agentic_trader/quant): `agentic_trader/quant`
- [C++ engine](https://github.com/ashjha0/agentic-trader/blob/main/cpp/include/at/backtest.hpp): `cpp/include/at/backtest.hpp`

### Backtest and evaluation

- [Walk-forward backtest](https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/backtest.py): `agentic_trader/backtest.py`
- [Backtest statistics](https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/stats.py): `agentic_trader/stats.py`
- [Evaluation protocol](https://github.com/ashjha0/agentic-trader/blob/main/agentic_trader/evaluation.py): `agentic_trader/evaluation.py`

### Other components

- **Research user**

## Connections

- Research user → Desk harness: requests decision (evidence: `README.md`)
- Desk harness → Plan validation: validates plan (evidence: `README.md`)
- Desk harness → Tool registry: dispatches tools (evidence: `agentic_trader/agentic/harness.py`)
- Tool registry → Tool policy: checks policy (evidence: `agentic_trader/agentic/tools.py`)
- Tool registry → Evidence records: records evidence (evidence: `agentic_trader/agentic/tools.py`)
- Desk harness → Specialist agents: runs team (evidence: `README.md`)
- Specialist agents → Decision state: writes decisions (evidence: `agentic_trader/agents/analysts.py`)
- Specialist agents → Model access: requests completions (evidence: `agentic_trader/agents/base.py`)
- Desk harness → Decision critic: checks result (evidence: `README.md`)
- Desk harness → Audited reports: builds audit report (evidence: `README.md`)
- Desk capabilities → Market providers: reads market data (evidence: `agentic_trader/agentic/servers.py`)
- Desk capabilities → Runbook retrieval: retrieves guidance (evidence: `agentic_trader/agentic/servers.py`)
- Desk harness → Desk capabilities: configures capabilities (evidence: `agentic_trader/agentic/harness.py`)
- HTTP and MCP → Desk harness: serves desk runs (evidence: `agentic_trader/agentic/harness.py`)
- Walk-forward backtest → Quant core: runs simulation (evidence: `agentic_trader/backtest.py`)
- Walk-forward backtest → Specialist agents: propagates graph (evidence: `agentic_trader/backtest.py`)
- Walk-forward backtest → Market providers: loads prices (evidence: `agentic_trader/backtest.py`)
- Quant core → C++ engine: uses compiled backend (evidence: `agentic_trader/quant/__init__.py`)
- Portfolio construction → Quant core: uses quant functions (evidence: `agentic_trader/portfolio.py`)
- Execution algorithms → Quant core: uses quant functions (evidence: `agentic_trader/algo.py`)
- Alpha research → Quant core: uses quant functions (evidence: `agentic_trader/alpha.py`)
- Evaluation protocol → Walk-forward backtest: evaluates runs (evidence: `agentic_trader/evaluation.py`)
- Evaluation protocol → Backtest statistics: computes metrics (evidence: `agentic_trader/evaluation.py`)