Skip to content

AGENTS.md

Latest commit

 

History

History
103 lines (84 loc) · 4.59 KB

AGENTS.md

File metadata and controls

103 lines (84 loc) · 4.59 KB

System Agents & Personas

This document defines the autonomous and semi-autonomous "agents" within the Algo Trader system. These components act as logical actors with specific responsibilities, lifecycles, and interaction patterns.

Architecture Overview

The system operates on a Federalist Architecture where distinct agents handle specific domains (Data, Research, Execution) under the supervision of a central Control Plane.

graph TD
    User((User/Admin)) -->|Commands via CLI/Makefile| Orchestrator
    Orchestrator[The Orchestrator] -->|Triggers| Researcher[The Researcher]
    Orchestrator -->|Deploys| Trader[The Trader]
    Orchestrator -->|Queries| DataSteward[The Data Steward]
    
    Researcher -->|Publishes Models| Registry[(Model Registry)]
    Trader -->|Reads Models| Registry
    Trader -->|Executes Orders| Broker[Broker API]
    
    DataSteward -->|Ingests| RawData[(Raw Data)]
    DataSteward -->|Computes| Features[(Feature Store)]
Loading

1. The Orchestrator (Control Plane)

The centralized brain and state manager.

  • Role: System Coordinator, State Manager, Single Source of Truth.
  • Primary Code: src/algo_trader/control/orchestrator.py
  • Responsibilities:
    • Manage the application lifecycle (Start, Stop, Pause).
    • Maintain the global state (metrics, active models, trading status).
    • Dispatch commands to other agents.
    • Ensure audit logging of all critical events (events.jsonl).
  • Interaction: Users interact primarily with the Orchestrator via CLI/Make commands, which then delegates tasks.

2. The Researcher (AutoML Agent)

The autonomous scientist constantly seeking better models.

  • Role: Model Training, Hyperparameter Tuning, Model Validation.
  • Primary Code:
  • Responsibilities:
    • Automatically fetch the latest datasets.
    • Train Random Forest and Gradient Boosting models (and potentially Deep Learning models).
    • Evaluate performance against holdout data.
    • Publish successful models to the Artifact Registry.
  • Key Workflow: make train, make auto-train

3. The Trader (Execution Agent)

The rigorous operator executing the strategy.

  • Role: Live/Paper Trading Execution, Portfolio Management.
  • Primary Code:
  • Responsibilities:
    • Load the latest "Champion" model from the Registry.
    • Connect to the Broker (Alpaca/Paper).
    • Monitor specific symbols (e.g., BTC/USD) on a schedule.
    • Execute trades based on model signals [BUY, SELL, HOLD].
    • Enforce risk management rules (Stop Loss, Take Profit).
  • Key Workflow: make paper-run, make paper-once

4. The Data Steward (Data Pipeline)

The librarian ensuring clean, consistent information.

  • Role: Data Ingestion, Cleaning, Feature Engineering, Labeling.
  • Primary Code:
  • Responsibilities:
    • Ingest raw OHLCV data from external sources (CoinGecko, CSV).
    • Construct technical indicators (RSI, MACD, Rolling Means).
    • Prevent Lookahead Bias by strictly managing timestamp alignments.
    • Generate target labels (e.g., "Direction next 4 hours").
  • Key Workflow: make ingest, make features

5. The Forecaster (Deep Learning Specialist)

The specialized neural network expert.

  • Role: Time-series forecasting, Complex Pattern Recognition.
  • Primary Code:
  • Responsibilities:
    • Handle LSTM/Transformer architectures for sequence modeling.
    • Manage walk-forward validation for time-series.
    • Provide auxiliary signals to the Ensemble strategy.

6. The Backtester (Simulation Agent)

The skeptic verifying strategies before deployment.

  • Role: Historic simulation, Strategy validation.
  • Primary Code: src/algo_trader/backtest/engine.py
  • Responsibilities:
    • Replay historical data as if it were live.
    • Simulate broker latency, fees, and slippage.
    • Generate performance reports (Equity Curve, Drawdown, Sharpe Ratio).
    • Strictly prevent future data leakage.
  • Key Workflow: make backtest