Repository orientation

AlphaSwarm is a monorepo organised by responsibility. The boundary between packages is enforced by the always-on Cursor rule repository-boundaries.mdc and by import guards in CI.

Top-level packages

• alphaswarm/ — the quant runtime. FastAPI gateway, Celery workers, strategy framework, backtest engines, agent control plane, RAG, Iceberg writers, persistence models.
• alphaswarm_controller/ — workload lifecycle / /manage/* API / Terraform driver / provider adapters. Never imports alphaswarm.*. See Concept: control plane topology.
• alphaswarm_core/ — shared value types, ABCs, auth filters, topology contracts. Dependency-light.
• alphaswarm_client/ — active Vite + React 19 + Tailwind 4 operator UI. Served at alpha-swarm.ai.
• alphaswarm_ui/ — cloud-hosted, customer-facing PaaS frontend (Next.js 14+). Served at alpha-swarm.ai. Dual Auth0 (B2C) + Entra (B2B) identity.
• alphaswarm_admin/ — internal admin (managed services + company accounts). Audit-first. Served at manage.alpha-swarm.ai.
• alphaswarm_rl/ — RL subsystem: hash-locked RLExperimentSpec + RLRuntime + Iceberg trajectory store. Legacy alphaswarm.rl.* is a deprecation shim.
• alphaswarm_models/ — custom model pulling, building, training, evaluating, serving (vLLM + Ollama). Legacy alphaswarm.ml.* is a deprecation shim.
• alphaswarm_bots/ — bot templates and bot runtime (TradingBot / ResearchBot).
• alphaswarm_ide/ — Theia 1.72-based IDE + AlphaSwarm extensions (alphaswarm, alphaswarm-shell, alphaswarm-mcp-bridge, alphaswarm-research-copilot, alphaswarm-notebook-quant, alphaswarm-quant).
• alphaswarm_cli/ — standalone operator CLI (alphaswarm-cli). HTTP-only; never imports alphaswarm.*. RFC 8628 device auth + OS keyring storage.
• alphaswarm_platform/ — hosted deployment + build + IaC + cluster setup. Manifests, Helm charts, Terraform modules, Docker base images. No Python runtime imports.
• alphaswarm_index/ — single source of truth for project orientation (this site links into it but never modifies it; sole-writer is the alphaswarm-index-curator subagent).
• alphaswarm_docs/ — this site.

Where to look for X

• API route: alphaswarm/api/routes/.
• Celery task: alphaswarm/tasks/.
• Strategy: alphaswarm/strategies/.
• Persistence model: alphaswarm/persistence/.
• Migration: alembic/versions/.
• Iceberg writer: alphaswarm/data/iceberg_catalog.py.
• LLM gateway: alphaswarm/llm/providers/router.py.
• Configuration: alphaswarm/config/settings.py.

Hard rules

The full agent-readable rule-set is in AGENTS.md. The cardinal subset:

1. Symbols: Symbol.parse(vt_symbol) — never split on ..
2. LLM calls: router_complete only — never litellm.completion or vendor SDKs.
3. Iceberg writes: iceberg_catalog.append_arrow only — never raw PyIceberg.
4. Celery progress: emit / emit_done / emit_error from alphaswarm/tasks/_progress.py — never publish to Redis from task code.
5. Configuration: from alphaswarm.config import settings — never construct a fresh Settings().
6. Registry: @register("Name", kind=...) for every new strategy / model / engine / alpha / portfolio / sink.
7. Migrations: immutable once committed.
8. Cross-task state: Postgres only; never pickle ORM objects.

The full set is 55 hard rules + a Don'ts section in AGENTS.md.

Conventions

See Conventions for documentation style and authoring rules.