Class Diagrams

Pair with alphaswarm_docs/erd.md (database schema) and alphaswarm_docs/architecture.md (system view). Doc map: alphaswarm_docs/index.md.

Hand-authored mermaid classDiagram blocks for the six hierarchies AI coders most often need to navigate. Every diagram cites the canonical file so you can jump from the diagram into the code in one click.

1. Symbol + core enums

The atom that flows through every data feed, strategy, and broker. Defined in alphaswarm/core/types.py.

Key invariants:

• Symbol is hashable + frozen. Round-trip via Symbol.parse(symbol.format()) is the identity.
• vt_symbol is always f"{ticker}.{exchange}" (vnpy convention).
• Concrete instrument shapes (option chains, future contracts) live alongside Symbol as additional fields, not separate classes.

2. LLM provider registry

The router from alphaswarm/llm/providers/router.py dispatches every LLM call through LiteLLM. Adding a provider is a single dict entry in alphaswarm/llm/providers/catalog.py.

Conventions:

• Always call via router_complete(provider=..., model=..., ...).
• Tier (deep/quick) routing happens via settings.provider_for_tier
  • provider.default_model(tier).
• The control plane in alphaswarm/runtime/control_plane.py can override ollama_host / vllm_base_url at runtime.

3. Strategy hierarchy

AlphaSwarm follows the Lean 5-stage pattern (Universe → Alpha → Portfolio → Risk → Execution). Concrete strategies are factory-instantiated from config via the class/module_path/kwargs registry pattern.

The interfaces are in alphaswarm/core/interfaces.py; concrete alphas in alphaswarm/strategies/ (one file per alpha). See alphaswarm_docs/factor-research.md for the authoring guide.

4. Backtest + paper + live (IBrokerage / IDataQueueHandler)

The same strategy runs unchanged across backtest, paper, and live — the engines differ in how they implement the broker + data-queue contract, not in how they call the strategy.

Walk-forward and Monte Carlo are function-based utilities (run_walk_forward in alphaswarm/backtest/walk_forward.py, run_monte_carlo in alphaswarm/backtest/monte_carlo.py), not BaseBacktestEngine subclasses. Paper trading is a session, not an engine subclass: see PaperTradingSession in alphaswarm/trading/session.py.

Files of interest:

• alphaswarm/backtest/base.py — BaseBacktestEngine
• alphaswarm/backtest/engine.py — EventDrivenBacktester
• alphaswarm/backtest/vectorbt_engine.py
• alphaswarm/backtest/broker_sim.py — SimulatedBrokerage, used by all non-live engines
• alphaswarm/trading/brokerages/ — concrete IBrokerage implementations for paper + live
• alphaswarm/trading/feeds/ — Kafka feed handler (KafkaDataFeed)

See alphaswarm_docs/backtest-engines.md for the full engine matrix, alphaswarm_docs/paper-trading.md for the session lifecycle.

5. Generic ingestion pipeline

Discovery → Director → Materialise → Verify → Annotate. The dataclasses below are the canonical contract between stages.

Files:

• alphaswarm/data/pipelines/discovery.py
• alphaswarm/data/pipelines/director.py
• alphaswarm/data/pipelines/materialize.py
• alphaswarm/data/pipelines/annotate.py
• alphaswarm/data/pipelines/runner.py
• alphaswarm/data/pipelines/extractors.py

Walkthrough lives in alphaswarm_docs/data-catalog.md.

6. Bot entity (TradingBot / ResearchBot)

The Bot Entity Refactor introduced a first-class deployable unit that aggregates universe + strategy + engine + ML + agents + RAG + metrics. The runtime never re-implements those primitives — it composes references and dispatches to the existing entry points.

Files (now in the standalone alphaswarm_bots repo — alphaswarm/bots/*.py is a thin compatibility shim re-exporting from alphaswarm_bots.*):

• alphaswarm_bots/spec.py
• alphaswarm_bots/base.py
• alphaswarm_bots/trading_bot.py
• alphaswarm_bots/research_bot.py
• alphaswarm_bots/runtime.py
• alphaswarm_bots/deploy.py
• alphaswarm_bots/registry.py
• alphaswarm_bots/cli.py

Walkthrough lives in alphaswarm_docs/bots.md.