Skip to main content

Archived context note: this file captures a historical implementation prompt.
Canonical runbooks and governance now live in alphaswarm_docs/index.md, alphaswarm_docs/operations/*, and AGENTS.md. See alphaswarm_docs/archive/README.md.

🚀 Actionable Implementation Prompt: Institutional-Grade AlphaSwarm Refactor

Context: You are an expert quantitative developer tasked with enhancing the AlphaSwarm (AlphaSwarm). The project has already transitioned to a 5-stage framework (Universe -> Alpha -> Portfolio -> Risk -> Execution) and has defined core event types for an event-driven transition.

Objective: Complete the transition to a high-performance, deterministic, and agent-first trading laboratory.

Phase 1: Event-Driven Core Refactor (Action Item 2.1)​

  • Target File: alphaswarm/backtest/engine.py (specifically EventDrivenBacktester).
  • Task: Replace the current iterative bar processing with a central collections.deque event bus.
  • Implementation Details:
    • Use MarketEvent, SignalEvent, OrderEvent_Msg, and FillEvent_Msg from alphaswarm/core/types.py.
    • Refactor _run_impl to push initial MarketEvents into the queue and process them in a while queue: loop.
    • Ensure IAlphaModel outputs SignalEvents, which are then processed by the PortfolioConstructionModel.
  • D.O.D: A backtest can be fully reconstructed by replaying the event log stored in the BacktestResult.

Phase 2: Columnar Memory & Polars Integration (Action Item 1.1)​

  • Target Files: alphaswarm/data/iceberg_catalog.py, alphaswarm/backtest/engine.py.
  • Task: Migrate from pandas.DataFrame to polars.DataFrame and pyarrow.
  • Implementation Details:
    • Update IcebergCatalog.read_arrow and read_polars (add if missing) to be the primary data retrieval methods.
    • Implement a ZeroCopyManager in alphaswarm/core/memory.py to handle Arrow RecordBatches across process boundaries (Celery workers).
    • Refactor _MLBaseAlpha in alphaswarm/strategies/ml_alphas.py to use Polars lazy expressions for feature engineering.
  • D.O.D: All core data paths are free of pandas serialization overhead.

Phase 3: Advanced Risk & Interception (Action Item 1.3)​

  • Target Files: alphaswarm/strategies/risk_models.py, alphaswarm/backtest/engine.py.
  • Task: Implement institutional-grade risk management.
  • Implementation Details:
    • Create TrailingStopRiskManagementModel: Monitors unrealized PnL per symbol and liquidates if a peak-to-trough threshold is hit.
    • Create TVaRInterceptor: A decorator for the IRiskManagementModel that calculates Tail Value at Risk using the formula: TVaR = mu + sigma * (phi(InvPhi(alpha)) / (1-alpha)).
  • D.O.D: The risk layer can autonomously cancel signals generated by the Alpha layer if they violate tail-risk constraints.

Phase 4: Multi-Agent Orchestration & MCP (Action Item 3.1 & 3.2)​

  • Target Files: alphaswarm/agents/graph/, alphaswarm/agents/runtime.py.
  • Task: Implement a hierarchical consensus mechanism for spec-driven agents.
  • Implementation Details:
    • Define MCP tool definitions for get_historical_volatility, query_portfolio_margin, and simulate_insight_impact.
    • Refactor AgentRuntime to orchestrate a "Research Debate":
      1. Market Monitor: Detects regime shifts.
      2. Quant Generator: Drafts Alpha logic.
      3. Risk Simulator: Runs Monte Carlo stress tests.
    • Use langgraph to manage the state and consensus among these agents.
  • D.O.D: An agent run only progresses to a SignalEvent if the Risk Simulator agent approves the Monte Carlo outcome.

Phase 5: FinOps Governance Enforcement (Action Item 4.1)​

  • Target Files: alphaswarm/config.py, alphaswarm_platform/deploy/k8s/.
  • Task: Enforce mandatory tagging for all cloud resources.
  • Implementation Details:
    • Ensure every Celery task dispatch and Kubernetes pod creation injects labels: project, cost_center, owner, data_classification (sourced from alphaswarm.config.settings).
    • Add a FinOpsAuditTask that scans the current runtime and alerts on untagged resources.
  • D.O.D: Every dollar of cloud spend is attributable to a specific strategy_id or agent_run_id.

⚠️ Constraints & Guardrails​

  • Hard Rule: Never call litellm directly; use router_complete.
  • Hard Rule: All symbols must be Symbol instances; use Symbol.parse().
  • Hard Rule: No direct order execution from agents; must emit Signal objects to the 5-stage pipeline.