Repository Split

Status: executed. Historical in-tree paths such as alphaswarm_rl/ inside the monolith now resolve to the sibling repository ../alphaswarm_rl.

This document is the operator-facing domain map for those sibling repos. It does not invent new product surfaces — it records the boundaries that already ship. The file-by-file path contract is alphaswarm-monorepo-paths.

Current deployment version: 0.1.0-alpha.1.

Principles

• Shared abstractions live in alphaswarm_core; that package must not import from higher-level packages.
• alphaswarm_controller is standalone. It may depend on alphaswarm_core, but it must not import alphaswarm.*.
• AlphaSwarm is cluster-agnostic. Workload controllers and operator features live in AlphaSwarm repos; rpi_kubernetes is not an inbound dependency.
• Prefer generated or typed API contracts between projects over direct imports across repository boundaries.
• New code imports extracted packages directly (alphaswarm_agents.*, alphaswarm_rl.*, alphaswarm_models.*). Do not re-introduce removed monolith shims.

Domain Map

Paths below are sibling repositories checked out next to alphaswarm/, not subdirectories of the monolith.

Domain	Sibling repo	Owns	Does not own
Control plane	alphaswarm_controller/	/manage/*, workload lifecycle, provider adapters, session/control API	Quant runtimes, Celery business tasks, strategy logic
Platform core	alphaswarm_core/	Shared value types, ABCs, auth/resource filters, topology, stable wire models	FastAPI routes, ORM models, concrete cloud SDK workflows
Identity	alphaswarm_auth/	Unified IAM hub, device registration, mTLS CA, WebAuthn	Quant runtimes, broker order routing
Client	alphaswarm_client/	Operator UI, client docs, generated API contracts, local client behavior	Backend business logic, direct database writes
Bots	alphaswarm_bots/	Bot runtime, templates, examples, sample specs	Direct bypass of BotRuntime or immutable versioning
RL	alphaswarm_rl/	RL subsystem: hash-locked RLExperimentSpec + RLRuntime + RLComponent metaclass + advantage estimators + policy backbones + weight-centric portfolio pipeline + Iceberg trajectory store + matching Celery task / API route / YAML spec library / tests	LLM gateway (router_complete stays in monolith); central registry (alphaswarm.core.registry.register stays in monolith)
Models	alphaswarm_models/	Custom model pulling, building, training, fine-tuning, evaluating, testing — qlib-style ML framework + Predictor Hub + AlphaBacktestExperiment + walk-forward + finetune trainers + every model implementation + custom model serving (vLLM + Ollama) + matching Celery tasks / API routes / YAML spec library / tests	LLM gateway (router_complete stays in monolith); central registry (alphaswarm.core.registry.register stays in monolith)
Execution layer	alphaswarm_worker/	nodes/ cluster daemons (Ray/Dask/Spark/Kafka/Redpanda/Flink) + execution/ typed WorkRequest -> Executor -> WorkResult contract (Local/Ray/Dask/Spark/Native subtypes, plane-separated money-plane risk gate, idempotency, retries/DLQ, checkpoint + spot-resilience) + the Celery task adapter for the heavy queues. Consolidates the alphaswarm-executor heavy-compute role.	LLM gateway, Iceberg writes, progress bus (all delegated to the monolith via guarded imports); infra provisioning (WorkloadRuntime / TerraformRuntime)
Agents	alphaswarm_agents/	Standalone AgentRuntime + AgentSpec + registry, plus trader/research/selection/analysis crews. Hard cutover — no deprecation shim.	LLM gateway (stays in monolith)
Knowledge Base	alphaswarm_kb/, alphaswarm_kb_federation/	Cognitive-memory layer + marketplace federation.	Direct Graph store bypass
Ingest	alphaswarm_ingest/	Ingestion connectors, controller, marketplace seed catalog	SEC companyfacts ownership expansion (frozen until a maintainer assigns one canonical owner)
Knowledge Graph	alphaswarm_graph/	SOKG implementation (Neo4j + LangGraph expansion).	Entity reference data (external)
Learning	alphaswarm_learning/	GraphRAG + agentic learning service	Cross-surface activity memory (alphaswarm_memory is still a seed)
FinOps	alphaswarm_finops/	Multi-cloud and SaaS billing monitoring (FOCUS 1.3).	Deployment IaC
Platform Context	alphaswarm_mcp/, alphaswarm_assistant/	Agent context MCP server + Cline seeder/customization.	Operational Data MCP
Visualization	alphaswarm_viz/	Python-native dashboards (Panel/HoloViz).	SPA client (React)
Docs	alphaswarm_docs/	Public Docusaurus site (this site)	Marketing website (alphaswarm_website)
Monolith runtime	alphaswarm/	Analysis, backtests, data plane, persistence, tasks, API gateway, LLM gateway (router_complete, memory, cache, prompts, tokens), the central registry	Extracted RL / ML / agents / bots / worker / KB stacks
Deployment	alphaswarm_platform/	Compose, Kubernetes, Terraform, image build contracts	Cluster bootstrap owned outside AlphaSwarm

Allowed Dependencies

Hard dependency rules:

1. alphaswarm_core must not import alphaswarm, alphaswarm_controller, FastAPI, SQLAlchemy, Celery, or heavy optional SDKs.
2. alphaswarm_controller must not import alphaswarm.*; use alphaswarm_core contracts or HTTP APIs.
3. alphaswarm_client must call backend APIs through generated clients or local API wrappers. It must not duplicate authorization, tenancy, or kill-switch semantics.
4. alphaswarm_snippets is read-only knowledge for runtime code. Production modules must not import from it.
5. alphaswarm_bots owns BotRuntime and templates. Do not bypass the runtime or mutate hash-locked bot_versions rows.
6. alphaswarm_rl and alphaswarm_models may depend on alphaswarm.* for the shared runtime primitives that have not yet been extracted (iceberg_catalog.append_arrow, router_complete, LedgerWriter, RequestContext, ORM models, _progress.emit, MetadataCache, RiskLimits, TargetWeightsRebalancer, alphaswarm.core.registry.register). The reverse direction is a hard cutover: callers must import alphaswarm_rl.* / alphaswarm_models.* directly. Only alphaswarm.llm.{vllm_runner,ollama_client} → alphaswarm_models.serving.* still goes through a deprecation-warning compatibility shim. New code imports from alphaswarm_models.serving.* directly.

Completed extractions (historical)

These steps already landed. They stay here so older links and runbooks do not look like unfinished work:

1. Stabilize alphaswarm_core package contracts and tests.
2. Finish alphaswarm_controller as the home for workload lifecycle providers and /manage/* behavior.
3. Move curated references into alphaswarm_snippets (now retired as a runtime dependency).
4. Extract alphaswarm_client as the Vite operator UI.
5. Extract alphaswarm_bots (BotRuntime + templates).
6. Extract alphaswarm_rl (May 2026) — RL subsystem moved out of alphaswarm/rl/. The deprecation shim has been removed.
7. Extract alphaswarm_models (May 2026) — custom-model boundary moved out of alphaswarm/ml/. The alphaswarm.ml.* shim has been removed.
8. Extract alphaswarm_agents — hard cutover, no shim.
9. Extract alphaswarm_platform build/deploy/IaC from the monolith root.

Remaining seed / freeze notes

A domain that is still a seed is not a shipped product surface:

• alphaswarm_memory — proposed activity/context memory. Charter is Proposed, not Accepted.
• alphaswarm_research — README-only placeholder.
• SEC EDGAR companyfacts ingestion / graph / marketplace expansion remains frozen until a maintainer assigns one canonical owner. Do not extend the in-flight monolith, alphaswarm_data, and alphaswarm_ingest paths in parallel.