# the-swarm-corporation/autohedge architecture

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

- Interactive diagram: https://gitdiagram.com/the-swarm-corporation/autohedge
- Repository: https://github.com/the-swarm-corporation/autohedge

## Overview

1. **Overall shape**
   AutoHedge is a Python package centered on an autonomous trading pipeline. The runtime entrypoints are `autohedge/__main__.py`, `autohedge/cli.py`, and `autohedge/main.py`, which likely bootstrap the system, load configuration, assemble agents, and start the trading loop.

2. **Core trading pipeline**
   The README describes the main architecture as a staged agent flow: **Director Agent → Quant Agent → Risk Management Agent → Execution Agent**. This is the primary control path for turning market context into trade decisions and then into executable orders.

3. **Agent responsibilities**
   The system is intentionally split by function:
   - **Director**: generates the strategy / thesis
   - **Quant**: performs technical and statistical analysis
   - **Risk**: sizes positions and applies constraints
   - **Execution**: converts approved decisions into orders and sends them to the venue  
   This separation is the main architectural boundary and is important for any diagram.

4. **Market/data access layer**
   `autohedge/tools/` contains provider-specific connectors used by the agents:
   - `jupiter_price.py`, `jupiter_search.py` for Solana/Jupiter-related data and discovery
   - `polygon_api.py` and `yahoo_api.py` for market data
   - `exa_search_tool.py` for external search
   - `ultra_tools.py` and `tools_registry.py` for composing and exposing tools to agents  
   This layer isolates external APIs from the decision logic.

5. **Tool registry boundary**
   `tools_registry.py` suggests a central place where agent-usable tools are registered and selected. Architecturally, this is the control point between “what the agents can do” and “how external services are called.”

6. **Configuration and secrets**
   `autohedge/env_loader.py` plus `.env.example` define the config boundary. The repository expects environment variables such as `JUPITER_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `WORKSPACE_DIR`, and `WALLET_PRIVATE_KEY`. This means runtime behavior is driven by external configuration rather than hard-coded credentials.

7. **Execution and venue support**
   The README says **full autonomous trading on Solana** is supported, with Coinbase and other exchanges planned. In architecture terms, Solana is the current execution venue boundary, and wallet/private-key handling is part of the execution subsystem.

8. **Prompting and agent behavior**
   `autohedge/prompts.py` likely contains the system prompts / instructions that shape agent behavior. In an architecture diagram, this sits alongside the orchestration layer as a policy/behavior input rather than a data source.

9. **Workers and concurrency**
   `autohedge/workers.py` implies background workers or task execution helpers for running analysis, polling markets, or coordinating agent steps. This is the most likely place where the sequential agent pipeline becomes asynchronous or scheduled work.

10. **Logging and audit trail**
   The `logs/` directory contains trade CSV files, showing that the system produces persistent execution records. This is an important operational boundary: decisions are not just made, they are recorded for audit, debugging, and performance review.

11. **Experimental sandbox**
   `experimental/` contains `btc_agent.py`, `crypto_agent_wrapper.py`, and `market_making.py`. These appear to be prototypes or alternate strategies outside the main production path, so they should be drawn as a separate experimentation lane rather than part of the core execution flow.

12. **Packaging, quality, and delivery**
   The repo is a standard Python distributable with `pyproject.toml`, `requirements.txt`, and GitHub Actions workflows for linting, testing, docs, and publishing. These are supporting infrastructure, not part of the trading runtime, but they show the project has CI/CD and release automation around the core package.

Main entry points: [`autohedge/tools/tools_registry.py`](https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/tools/tools_registry.py) (Tool registry), [`autohedge/main.py`](https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/main.py) (App core), [`autohedge/cli.py`](https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/cli.py) (CLI), [`autohedge/__main__.py`](https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/__main__.py) (Main entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main_entry["Main entry<br/>entrypoint<br/>[__main__.py]"]
  node_cli["CLI<br/>command layer<br/>[cli.py]"]
  node_main_app["App core<br/>orchestrator<br/>[main.py]"]
  node_workers["Workers<br/>async helpers<br/>[workers.py]"]
end

subgraph group_agents["Agents"]
  node_director{{"Director<br/>strategy agent"}}
  node_quant{{"Quant<br/>analysis agent"}}
  node_risk{{"Risk<br/>controls agent"}}
  node_execution{{"Execution<br/>order agent"}}
  node_prompts["Prompts<br/>policy text<br/>[prompts.py]"]
end

subgraph group_tools["Tools"]
  node_tool_registry["Tool registry<br/>tool control<br/>[tools_registry.py]"]
  node_jupiter_price["Jupiter price<br/>market data<br/>[jupiter_price.py]"]
  node_jupiter_search["Jupiter search<br/>discovery tool<br/>[jupiter_search.py]"]
  node_polygon_api["Polygon API<br/>market data<br/>[polygon_api.py]"]
  node_yahoo_api["Yahoo API<br/>market data<br/>[yahoo_api.py]"]
  node_exa_search["Exa search<br/>external search<br/>[exa_search_tool.py]"]
  node_ultra_tools["Ultra tools<br/>tool bundle<br/>[ultra_tools.py]"]
end

subgraph group_ops["Ops"]
  node_env_loader["Env loader<br/>config boundary<br/>[env_loader.py]"]
  node_logs[("Trade logs<br/>audit trail")]
  node_experimental["Experiments<br/>sandbox<br/>[market_making.py]"]
  node_ci_cd["CI/CD<br/>delivery<br/>[test.yml]"]
end

node_main_entry -->|"launches"| node_cli
node_cli -->|"bootstraps"| node_main_app
node_main_app -->|"loads config"| node_env_loader
node_main_app -->|"applies"| node_prompts
node_main_app -->|"delegates"| node_workers
node_main_app -->|"runs"| node_director
node_director -->|"hands off"| node_quant
node_quant -->|"submits"| node_risk
node_risk -->|"approves"| node_execution
node_execution -->|"uses"| node_tool_registry
node_director -->|"uses"| node_tool_registry
node_quant -->|"uses"| node_tool_registry
node_tool_registry -->|"exposes"| node_jupiter_price
node_tool_registry -->|"exposes"| node_jupiter_search
node_tool_registry -->|"exposes"| node_polygon_api
node_tool_registry -->|"exposes"| node_yahoo_api
node_tool_registry -->|"exposes"| node_exa_search
node_tool_registry -->|"composes"| node_ultra_tools
node_execution -->|"records"| node_logs
node_main_app -.->|"separates"| node_experimental
node_main_app -.->|"shipped by"| node_ci_cd

click node_main_entry "https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/__main__.py"
click node_cli "https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/cli.py"
click node_main_app "https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/main.py"
click node_workers "https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/workers.py"
click node_prompts "https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/prompts.py"
click node_tool_registry "https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/tools/tools_registry.py"
click node_jupiter_price "https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/tools/jupiter_price.py"
click node_jupiter_search "https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/tools/jupiter_search.py"
click node_polygon_api "https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/tools/polygon_api.py"
click node_yahoo_api "https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/tools/yahoo_api.py"
click node_exa_search "https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/tools/exa_search_tool.py"
click node_ultra_tools "https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/tools/ultra_tools.py"
click node_env_loader "https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/env_loader.py"
click node_logs "https://github.com/the-swarm-corporation/autohedge/blob/main/logs/trades_20250305_193100.csv"
click node_experimental "https://github.com/the-swarm-corporation/autohedge/blob/main/experimental/market_making.py"
click node_ci_cd "https://github.com/the-swarm-corporation/autohedge/blob/main/.github/workflows/test.yml"

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_main_entry,node_cli,node_main_app,node_workers toneBlue
class node_director,node_quant,node_risk,node_execution,node_prompts toneAmber
class node_tool_registry,node_jupiter_price,node_jupiter_search,node_polygon_api,node_yahoo_api,node_exa_search,node_ultra_tools toneMint
class node_env_loader,node_logs,node_experimental,node_ci_cd toneRose
```

## Components

### Runtime

Package entrypoints and orchestration

- [Main entry](https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/__main__.py): entrypoint · Package and CLI startup paths for the application · `autohedge/__main__.py`
- [CLI](https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/cli.py): command layer · Command-line interface for launching and controlling runs · `autohedge/cli.py`
- [App core](https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/main.py): orchestrator · Bootstraps configuration, agents, and the trading loop · `autohedge/main.py`
- [Workers](https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/workers.py): async helpers · Background task and coordination helpers for agent work · `autohedge/workers.py`

### Agents

Core autonomous trading pipeline

- **Director**: strategy agent · Creates the trading thesis and high-level intent
- **Quant**: analysis agent · Performs technical and statistical market analysis
- **Risk**: controls agent · Applies sizing, constraints, and approval logic
- **Execution**: order agent · Converts approved decisions into venue orders
- [Prompts](https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/prompts.py): policy text · System instructions that shape agent behavior · `autohedge/prompts.py`

### Tools

External data and execution connectors

- [Tool registry](https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/tools/tools_registry.py): tool control · Registers and exposes tools available to agents · `autohedge/tools/tools_registry.py`
- [Jupiter price](https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/tools/jupiter_price.py): market data · Solana/Jupiter price and routing data access · `autohedge/tools/jupiter_price.py`
- [Jupiter search](https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/tools/jupiter_search.py): discovery tool · Jupiter-related search and discovery helper · `autohedge/tools/jupiter_search.py`
- [Polygon API](https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/tools/polygon_api.py): market data · Equity/market data connector · `autohedge/tools/polygon_api.py`
- [Yahoo API](https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/tools/yahoo_api.py): market data · Market data and lookup connector · `autohedge/tools/yahoo_api.py`
- [Exa search](https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/tools/exa_search_tool.py): external search · Web/external research connector · `autohedge/tools/exa_search_tool.py`
- [Ultra tools](https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/tools/ultra_tools.py): tool bundle · Higher-level composition of agent-facing tools · `autohedge/tools/ultra_tools.py`

### Ops

Configuration, logging, and delivery

- [Env loader](https://github.com/the-swarm-corporation/autohedge/blob/main/autohedge/env_loader.py): config boundary · Loads runtime settings and secrets from environment variables · `autohedge/env_loader.py`
- [Trade logs](https://github.com/the-swarm-corporation/autohedge/blob/main/logs/trades_20250305_193100.csv): audit trail · Persistent CSV records of executed trades · `logs/trades_20250305_193100.csv`
- [Experiments](https://github.com/the-swarm-corporation/autohedge/blob/main/experimental/market_making.py): sandbox · Prototype and alternate strategy implementations · `experimental/market_making.py`
- [CI/CD](https://github.com/the-swarm-corporation/autohedge/blob/main/.github/workflows/test.yml): delivery · Automation for linting, testing, documentation, and publishing · `.github/workflows/test.yml`

## Connections

- Main entry → CLI: launches · Startup flows into command handling
- CLI → App core: bootstraps · CLI hands off to application orchestration
- App core → Env loader: loads config · Runtime settings and secrets are loaded before execution
- App core → Prompts: applies · Agent behavior is shaped by prompt policy
- App core → Workers: delegates · Long-running or scheduled work is coordinated through workers
- App core → Director: runs · Trading loop begins with strategy generation
- Director → Quant: hands off · Strategy is refined by market analysis
- Quant → Risk: submits · Analytical output is constrained by risk logic
- Risk → Execution: approves · Approved decisions move into order generation
- Execution → Tool registry: uses · Execution and analysis access tools through the registry boundary
- Director → Tool registry: uses · Strategy generation can query external tools
- Quant → Tool registry: uses · Quant analysis pulls market and search data via tools
- Tool registry → Jupiter price: exposes · Registry makes Jupiter price data available
- Tool registry → Jupiter search: exposes · Registry makes Jupiter discovery tools available
- Tool registry → Polygon API: exposes · Registry makes Polygon data available
- Tool registry → Yahoo API: exposes · Registry makes Yahoo data available
- Tool registry → Exa search: exposes · Registry makes external search available
- Tool registry → Ultra tools: composes · Bundled tool surface is assembled here
- Execution → Trade logs: records · Executed trades are written to persistent CSV logs
- App core → Experiments: separates · Prototype strategies are kept outside the main production path
- App core → CI/CD: shipped by · Package delivery is supported by workflow automation
