Configuration & Model Versioning¶

How strategy configurations and ML models are versioned, promoted, and managed across environments.

graph LR
    subgraph Config["Strategy Config"]
        C1["tradai.yaml"] --> C2["S3 Upload"]
        C2 --> C3["DRAFT"]
        C3 --> C4["ACTIVE"]
        C4 --> C5["DEPRECATED"]
    end

    subgraph Model["ML Model + Release"]
        M1["Training"] --> M2["MLflow Registry - (artifact/run store)"]
        M2 --> M3["register() - composes Release - (ENV#REL#...)"]
        M3 --> M4["ACTIVE pointer - (ENV#ACTIVE, epoch)"]
        M4 -->|promote / rollback| M4
    end

    C4 -.->|resolved into the Release| M3

Strategy Configuration¶

tradai.yaml¶

Every strategy has a tradai.yaml at its root that defines how TradAI services interact with it:

strategy:
  name: "MyStrategy"
  version: "1.0.0"
  entry_point: "mystrategy.strategy:MyStrategy"
  category: "momentum"
  timeframe: "1h"

strategy_service:
  source:
    KIND: Binance
  adapter:
    KIND: AWS
    bucket_name: tradai-data
    library: ohlcv
  defaults:
    timerange: "20240101-20241201"
    symbols:
      - "BTC/USDT:USDT"
      - "ETH/USDT:USDT"
    stake_amount: 1000
    max_open_trades: 3

mlflow:
  tracking_uri: ${MLFLOW_TRACKING_URI:-http://localhost:5001}
  experiment_name: "strategies/mystrategy"
  auto_log_params: true

optimization:
  defaults:
    epochs: 100
    loss_function: sharpe
    spaces: [buy, sell]
  presets:
    quick:
      epochs: 50
      spaces: [buy]
    standard:
      epochs: 200
      spaces: [buy, sell]
    production:
      epochs: 1000
      spaces: [buy, sell, roi, stoploss, trailing]
      walk_forward: true

deployment:
  ecs:
    cpu: 512
    memory: 1024

Config Storage¶

Configurations are stored in S3 and versioned in DynamoDB:

graph TD
    YAML["tradai.yaml"] -->|upload| S3["S3 Bucket - tradai-configs"]
    S3 -->|version| DDB["DynamoDB - config-versions"]
    DDB -->|ACTIVE version| ECS["ECS Task"]

    ENV[".env / Secrets Manager"] -->|merge| Merge["ConfigMergeService"]
    S3 -->|base config| Merge
    Merge --> ECS

Config Version Lifecycle¶

Each config version follows a strict lifecycle:

stateDiagram-v2
    [*] --> DRAFT : create_version()
    DRAFT --> ACTIVE : activate()
    ACTIVE --> DEPRECATED : new version activated
    DEPRECATED --> [*] : TTL auto-cleanup (90 days)

    note right of DRAFT : Not yet validated
    note right of ACTIVE : Currently deployed (one per strategy)
    note right of DEPRECATED : Superseded, auto-deleted after 90d

Key rules:

• Only one ACTIVE version per strategy at any time
• Activating a new version automatically deprecates the previous one
• Deprecated versions have a 90-day TTL for auto-cleanup in DynamoDB
• Versions are content-addressable (SHA256 hash) -- duplicate configs are detected

Config Version Entity¶

Each version is tracked with these fields:

Managing Config Versions¶

CLI¶

# Create a new config version (starts as DRAFT)
tradai config create MyStrategy --data '{"timeframe":"1h","stoploss":-0.03}'
tradai config create MyStrategy --file config.json

# List versions for a strategy
tradai config list MyStrategy
tradai config list MyStrategy --status active

# Show a specific version
tradai config show MyStrategy v00001-a3b2c1d4

# Activate a version (auto-deprecates previous ACTIVE)
tradai config activate MyStrategy v00001-a3b2c1d4

# Deprecate a version
tradai config deprecate MyStrategy v00001-a3b2c1d4

# Submit backtest with a config version
tradai backtest quick MyStrategy --config-version v00001-a3b2c1d4
tradai backtest quick MyStrategy --config-version ACTIVE

API¶

Python SDK¶

from tradai.common.config.service import ConfigVersionService

service = ConfigVersionService(table_name="tradai-config-versions-dev")

# Create a new version (starts as DRAFT)
version = service.create_version(
    strategy_name="MyStrategy",
    config_data={"timeframe": "1h", "symbols": ["BTC/USDT:USDT"]},
    description="Updated symbols list",
)

# Activate it (auto-deprecates previous ACTIVE version)
active = service.activate("MyStrategy", version.config_id)

# List all versions for a strategy
versions = service.list_versions("MyStrategy")

# Get the currently active version
current = service.get_active("MyStrategy")

Config Data Merge¶

When a backtest is submitted with config_version_id, the active config's config_data is merged as defaults into the backtest parameters. Explicit parameters always win:

config_data: {"stoploss": -0.03, "stake_amount": 150}
backtest request: {"stake_amount": 1000}
result: {"stoploss": -0.03, "stake_amount": 1000}  # explicit wins

Protected fields (strategy, task_definition) cannot be overridden by config_data.

Config Version Propagation¶

When a backtest runs with a config version, the config_version_id is tracked across 5 stores:

See Config Versioning Verification Guide for step-by-step verification commands.

Config Loading at Runtime¶

When a strategy container starts, configs are loaded and merged from multiple sources:

graph TD
    S3["S3 Config - (base)"] --> Loader["StrategyConfigLoader"]
    MLflow["MLflow Tags - (model params)"] --> Loader
    ENV["Environment Vars - (overrides)"] --> Loader
    Loader --> Merge["ConfigMergeService"]
    Merge --> Validate["Validation"]
    Validate -->|pass| Config["StrategyConfig - (runtime)"]
    Validate -->|fail| Error["Startup Error"]

Priority order (highest wins):

1. Environment variables
2. MLflow model tags
3. S3 stored config
4. tradai.yaml defaults

Model Versioning (MLflow)¶

v4: MLflow is the artifact/run store — it records model versions, params, metrics, and tags. It is no longer the deployment lifecycle. What trades is decided by the Release / ACTIVE-pointer plane (below + the v4 Cutover & Promotion Runbook), not by MLflow None/Staging/Production/Archived stages. The strategy-as-model alias plane was retired in v4 P6.

Deployment lifecycle (authoritative: Release / ACTIVE pointer)¶

stateDiagram-v2
    [*] --> Registered : register() composes a Release (ENV#REL#...)
    Registered --> Active : first ACTIVE pointer set (first write)
    Active --> Active : promote() — gate + epoch-guarded swap to a challenger Release
    Active --> Active : rollback() — repoint ACTIVE to a prior Release (no gate/cooldown)

    note right of Registered : Immutable Release: image digest + resolved-config hash + slot bindings + gate snapshot
    note right of Active : ACTIVE pointer (ENV#ACTIVE, epoch) names the one Release that trades per (strategy, env)

The MLflow ModelStage enum (None/Staging/Production/Archived) still exists as model- version metadata, but it no longer governs what trades and there is no stage-transition promotion path.

Model Registration¶

After a backtest or training run, models are automatically registered:

sequenceDiagram
    participant ECS as ECS Task - (Freqtrade)
    participant MLflow as MLflow - Registry
    participant DDB as DynamoDB - State

    ECS->>MLflow: Log metrics + params
    ECS->>MLflow: Log model artifacts
    ECS->>MLflow: Register model version
    MLflow-->>ECS: Version number
    ECS->>DDB: Update job status
    ECS->>MLflow: Tag with git_commit, strategy_name

The ModelRegistrar handles this automatically:

from tradai.common.entrypoint.training.model_registrar import ModelRegistrar

registrar = ModelRegistrar(mlflow_adapter=adapter)
result = registrar.register(config=training_config, result=training_result)
# result.model_version is now set

Promotion gate (v4)¶

v4: Promotion is no longer an MLflow stage transition (champion/staging/Production aliases are retired). A challenger is an immutable Release; promotion runs a gate and, on pass, performs an epoch-guarded swap of the single ACTIVE pointer. See v4 Cutover & Promotion Runbook.

graph TD
    Challenger["Challenger Release - (gate_snapshot)"] --> Gate["Promotion gate"]
    Baseline["Current ACTIVE Release - (baseline gate_snapshot)"] --> Gate
    Gate --> Decision{"Pass?"}
    Decision -->|"yes"| Swap["Epoch-guarded pointer swap - (+ atomic audit)"]
    Decision -->|"no"| Reject["Rejection audit - (ACTIVE unchanged)"]

The gate (PromotionPolicy) applies floors (absolute), regression vs the current ACTIVE (from the 2^nd release per (strategy, env)), and a cooldown. Every threshold is overridable via its TRADAI_GATE_* env var (see below). Signed-off launch defaults:

⚠ TRADAI_GATE_REQUIRE_OOS footgun: only the literal "false" disables the out-of-sample requirement. Any other value (e.g. "0", "no") still requires OOS.

v4 activation flags¶

CLI Commands¶

# Verify the ACTIVE pointer names a cutover-ready Release (gate before the runtime flip)
tradai strategy assert-cutover-ready MyStrategy --env dev

# Promote a challenger Release: gate + epoch-guarded swap (exit 2 + rejection audit on fail)
tradai strategy promote MyStrategy "DEV#REL#01ARZ..." --env dev

# Roll ACTIVE back to a prior Release (bypasses gate + cooldown; still audited)
tradai strategy rollback MyStrategy "DEV#REL#01PRIOR..." --env dev

# Audited manual repoint onto a cutover-ready Release (admin op)
tradai strategy repoint-active MyStrategy "DEV#REL#01ARZ..." --env dev

API Endpoints¶

The Backend exposes the pointer-plane promotion APIs:

Automated Retraining Pipeline¶

The retraining workflow is orchestrated by Step Functions:

graph TD
    Trigger["Trigger - Schedule / Drift / Manual"] --> Check["Check Retraining - Needed?"]
    Check -->|"yes"| Train["Train Model - (ECS + FreqAI)"]
    Check -->|"no"| Skip["Skip"]
    Train --> Register["Register Release - (compose + ACTIVE pointer)"]
    Register --> Promote["Promote - (gate + epoch-guarded swap)"]
    Promote --> Notify["Notify - (SNS + Slack)"]

v4: there is no compare-models/promote-model/model-rollback stage-transition path anymore; the challenger is registered as a Release and promoted via the gate. The drift-monitor and retraining-scheduler Lambdas remain (trigger side).

Environment-Specific Configuration¶

Settings Hierarchy¶

Each service uses Pydantic settings with environment variable prefixes:

Settings Mixins¶

Common settings are shared via mixins:

# MLflow settings (shared by Strategy Service and Backend)
class MLflowSettingsMixin:
    mlflow_tracking_uri: str   # MLFLOW_TRACKING_URI
    mlflow_username: str       # MLFLOW_USERNAME
    mlflow_password: str       # MLFLOW_PASSWORD

# ArcticDB settings (shared by Data Collection and Strategy Service)
class ArcticSettingsMixin:
    arctic_s3_bucket: str      # ARCTIC_S3_BUCKET
    arctic_library_name: str   # ARCTIC_LIBRARY_NAME (default: "ohlcv")
    arctic_s3_endpoint: str    # ARCTIC_S3_ENDPOINT

Per-Environment Differences¶

Traceability¶

Every operation is traceable across the entire system:

graph LR
    TraceID["trace_id"] --> Backend["Backend API"]
    TraceID --> SQS["SQS Message"]
    TraceID --> SF["Step Functions"]
    TraceID --> ECS["ECS Task"]
    TraceID --> MLflow["MLflow Run"]
    TraceID --> DDB["DynamoDB - job record"]

    JobID["job_id"] --> DDB
    JobID --> S3["S3 Results"]

    RunID["mlflow_run_id"] --> MLflow
    RunID --> DDB

    GitSHA["git_commit"] --> MLflow
    GitSHA --> DDB

Quick Reference¶

Config Version Commands¶

Release / promotion commands (v4)¶

Key Source Files¶

See Also¶

• Config Versioning Verification Guide -- step-by-step verification and reproduction
• Strategy Lifecycle -- full path from idea to production
• ML Lifecycle Architecture -- detailed ML pipeline design
• Configuration Management Architecture -- system-level config design
• State Machines -- all state machine definitions