Skip to main content

Repository orientation

The repository split has been executed. AlphaSwarm is a workspace of sibling alphaswarm_* repos checked out side by side (for example ../alphaswarm_core next to ../alphaswarm), organised by responsibility. Historical in-tree paths such as alphaswarm_rl/ inside the monolith resolve to the sibling repo ../alphaswarm_rl. The boundary is enforced by repository-boundaries.mdc and by import guards in CI.

Current deployment version: 0.1.0-alpha.1. See Release notes.

Top-level repos​

  • alphaswarm/ — the quant runtime. FastAPI gateway, Celery workers, strategy framework, backtest engines, RAG, Iceberg writers, persistence models. Import alphaswarm_agents.*, alphaswarm_rl.*, and alphaswarm_models.* directly — the old alphaswarm/agents/, alphaswarm/rl/, and alphaswarm/ml/ trees are gone.
  • 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_auth/ — unified IAM hub. Prefer central auth introspection over re-deriving scopes in each service.
  • 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_agents/ — spec-driven agent stack (AgentRuntime, AgentSpec, crews, graph). Hard cutover from alphaswarm/agents/.
  • alphaswarm_rl/ — RL subsystem: hash-locked RLExperimentSpec + RLRuntime + Iceberg trajectory store. The monolith alphaswarm/rl/ shim has been removed.
  • alphaswarm_models/ — custom model pulling, building, training, evaluating, serving (vLLM + Ollama). The monolith alphaswarm/ml/ shim has been removed; only alphaswarm.llm.{vllm_runner,ollama_client} still re-export serving helpers.
  • alphaswarm_bots/ — bot templates and bot runtime (TradingBot / ResearchBot).
  • alphaswarm_kb/ / alphaswarm_kb_federation/ — knowledge-base runtime and cross-silo recall gateway.
  • alphaswarm_graph/ — self-organizing knowledge graph.
  • alphaswarm_ingest/ — ingestion connectors, controller, and marketplace seed catalog.
  • alphaswarm_worker/ — execution layer (WorkRequest → Executor → WorkResult) plus cluster daemons.
  • alphaswarm_ide/ — Theia 1.72-based IDE + AlphaSwarm extensions.
  • 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_learning/ — GraphRAG + agentic learning service (not a placeholder).
  • 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.

alphaswarm_memory and alphaswarm_research are seed placeholders — confirm scope with a maintainer before adding code. The full path contract is alphaswarm-monorepo-paths.

Where to look for X​

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 66 hard rules (rule 65 is the 0.1.0-alpha.1 deployment-version contract) plus a Don'ts section in AGENTS.md.

Conventions​

See Conventions for documentation style and authoring rules.