Repository Split

Status: migration guidance.

This document defines the AlphaSwarm monorepo boundaries while the platform is being split into future repositories. The current goal is isolation by responsibility without breaking imports, deployment manifests, or operator workflows.

Principles

• Use a strangler migration: create stable contracts first, then move implementations behind compatibility shims.
• Keep shared abstractions in alphaswarm_core; do not import from higher-level packages there.
• Keep alphaswarm_controller standalone. It may depend on alphaswarm_core, but it must not import alphaswarm.*.
• Keep rpi_kubernetes as cluster bootstrap and platform services only. AlphaSwarm workload controllers and operator features live in this repository.
• Prefer generated or typed API contracts between projects over direct imports across future repository boundaries.

Domain Map

Domain	Current path	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
Client	alphaswarm_client/	Operator UI, client docs, generated API contracts, local client behavior	Backend business logic, direct database writes
Snippets	alphaswarm_snippets/	Curated code knowledge, annotations, prompts, provenance indexes	Runtime imports or production package dependencies
Bots	alphaswarm_bots/, alphaswarm_bots/templates/	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)
Monolith runtime	alphaswarm/	Agents, analysis, backtests, data plane, persistence, tasks, API gateway, LLM gateway (router_complete, memory, cache, prompts, tokens), the central registry, the four spec runtimes' shared orchestration.	RL subsystem (extracted to alphaswarm_rl/); ML / model serving (extracted to alphaswarm_models/); new workload control-plane providers
Deployment	alphaswarm_platform/deployments/, alphaswarm_platform/terraform/, build/	Compose, Kubernetes, Terraform, image build contracts	Cluster bootstrap owned by rpi_kubernetes

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 stores templates and guidance until runtime interfaces are extracted from alphaswarm_bots.
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 (alphaswarm.rl.* → alphaswarm_rl.*, alphaswarm.ml.* → alphaswarm_models.*, alphaswarm.llm.{vllm_runner,ollama_client} → alphaswarm_models.serving.*) goes through deprecation-warning compatibility shims under alphaswarm/rl/, alphaswarm/ml/, and alphaswarm/llm/{vllm_runner,ollama_client}.py. New code imports from alphaswarm_rl.* / alphaswarm_models.* / alphaswarm_models.serving.* directly.

Migration Order

1. Stabilize alphaswarm_core package contracts and tests.
2. Finish alphaswarm_controller as the only home for workload lifecycle providers and /manage/* behavior.
3. Move curated references into alphaswarm_snippets with provenance and indexes.
4. Extract alphaswarm_client contracts around the existing Vite frontend and API gateway behavior before moving source paths.
5. Split alphaswarm_bots last, after bot persistence, task dispatch, backtest, paper trading, and agent runtime interfaces are explicit.
6. Extract alphaswarm_rl (May 2026) — RL subsystem moved out of alphaswarm/rl/, with matching Celery task / API route / YAML spec library / tests. Legacy alphaswarm.rl.* imports preserved through alphaswarm/rl/__init__.py deprecation shim.
7. Extract alphaswarm_models (May 2026) — custom-model boundary moved out of alphaswarm/ml/ plus the model-pulling / serving slice of alphaswarm/llm/ (vllm_runner.py, ollama_client.py). The central LLM gateway (router_complete, memory, cache, prompts, tokens) stays in the monolith at alphaswarm/llm/. Legacy alphaswarm.ml.* and alphaswarm.llm.{vllm_runner,ollama_client} imports preserved through compatibility shims.
8. Clean root-level build/deploy files only after the projects can be tested independently.

Future Repo Split Gate

A domain is ready to become its own repository when it has:

• README.md, AGENTS.md, and a validation command list.
• Independent packaging or build metadata.
• No forbidden imports across future repo boundaries.
• Versioned API or model contracts for consumers.
• CI checks that run without relying on the full monolith checkout, except for documented integration tests.