TradAI State Machines¶

Version: 1.0.0 | Date: 2026-03-28 | Status: CURRENT

1. TL;DR¶

TradAI has five state machines governing different lifecycle concerns:

All state enums are str, Enum subclasses defined in libs/tradai-common/src/tradai/common/entities/. Transitions are enforced through can_transition_to() guards, is_terminal properties, and with_status() immutable-update methods.

2. Backtest Job Lifecycle¶

Source: tradai.common.entities.aws.JobStatus Orchestrator: BacktestOrchestrationService (backend)

States¶

Transition Diagram¶

stateDiagram-v2
    [*] --> PENDING : submit_backtest()
    PENDING --> RUNNING : Executor starts task
    PENDING --> FAILED : Submission error
    PENDING --> CANCELLED : cancel_backtest()
    RUNNING --> COMPLETED : Backtest finishes OK
    RUNNING --> FAILED : Runtime error / timeout
    RUNNING --> CANCELLED : cancel_backtest() + ExecutionStopper
    COMPLETED --> [*]
    FAILED --> [*]
    CANCELLED --> [*]

Valid Transitions (from _VALID_TRANSITIONS)¶

PENDING  -> {RUNNING, FAILED, CANCELLED}
RUNNING  -> {COMPLETED, FAILED, CANCELLED}

Same-state transitions are allowed for idempotency. Terminal states reject all outbound transitions.

Transition Triggers¶

3. Trading Session Lifecycle¶

Source: tradai.common.entities.trading_state.TradingStatus Handler: TradingHandler (common entrypoint)

States¶

Transition Diagram¶

stateDiagram-v2
    [*] --> INITIALIZING : Container starts
    INITIALIZING --> WARMUP : Config + credentials loaded
    WARMUP --> RUNNING : Historical data loaded
    RUNNING --> PAUSED : Manual pause (C9)
    PAUSED --> RUNNING : Manual resume (C9)
    RUNNING --> STOPPED : Graceful shutdown (SIGTERM)
    RUNNING --> ERROR : Unhandled exception
    INITIALIZING --> ERROR : Config/credential failure
    WARMUP --> ERROR : Warmup failure
    PAUSED --> STOPPED : Shutdown while paused
    PAUSED --> ERROR : Error while paused
    ERROR --> [*]
    STOPPED --> [*]

Lifecycle Phases in TradingHandler.run()¶

Phase 1: INITIALIZING
  - _initialize_state_management()     -> DynamoDB TradingStateRepository
  - _load_strategy_config()            -> MLflow/S3 config (LIVE fails on error)
  - _load_exchange_credentials()       -> AWS Secrets Manager

Phase 2: WARMUP
  - _warmup_historical_data()          -> ArcticDB candle data

Phase 3: RUNNING
  - _create_trader()                   -> FreqtradeTrader instance
  - _start_health_reporter()           -> Heartbeats + MetricsCollector + RiskMonitor
  - _execute_trading_loop()            -> Freqtrade subprocess

Phase 4: STOPPED (or ERROR on exception)
  - _cleanup()                         -> Stop health reporter, clear refs

4. Strategy Promotion¶

Source: tradai.common.entities.mlflow.ModelStage Service: ModelPromotionService (strategy-service)

States¶

Transition Diagram¶

stateDiagram-v2
    [*] --> NONE : Model registered in MLflow
    NONE --> STAGING : stage()
    STAGING --> PRODUCTION : promote_to_production()
    PRODUCTION --> ARCHIVED : Auto-archive when new version promoted
    ARCHIVED --> PRODUCTION : rollback()
    STAGING --> PRODUCTION : promote_to_production(skip_validation=True)
    NONE --> PRODUCTION : promote_to_production(skip_validation=True)
    ARCHIVED --> STAGING : stage() (re-stage for re-validation)

Promotion Workflow¶

1. Stage: service.stage(model_name, version) -- moves to Staging
2. Validate: service.validate_for_production(model_name, version) -- checks:
3. Version exists and is in READY status
4. Version is in Staging stage
5. Required tags present (strategy_name, strategy_version)
6. Optional: validation backtest (7-day window)
7. Promote: service.promote_to_production(model_name, version) -- atomic operation:
8. Archives all existing Production versions (via archive_existing_versions=True)
9. Promotes target version to Production
10. Rollback: service.rollback(model_name, target_version) -- promotes an Archived/Staging/None version back to Production

5. ML Retraining Pipeline¶

Source: tradai.common.entities.retraining.RetrainingStatus Orchestrator: Step Functions retraining workflow (MO005)

States¶

Transition Diagram¶

stateDiagram-v2
    [*] --> PENDING : Trigger received
    PENDING --> CHECKING : Workflow starts
    CHECKING --> SKIPPED : No retraining needed
    CHECKING --> TRAINING : Retraining needed
    TRAINING --> VALIDATING : Training complete (handler-level)
    TRAINING --> FAILED : Training error
    VALIDATING --> COMPARING : Validation backtest done
    VALIDATING --> FAILED : Validation error
    COMPARING --> PROMOTING : Challenger wins
    COMPARING --> COMPLETED : Champion wins (no promotion)
    COMPARING --> FAILED : Comparison error
    PROMOTING --> COMPLETED : Model promoted
    PROMOTING --> FAILED : Promotion error
    SKIPPED --> [*]
    COMPLETED --> [*]
    FAILED --> [*]

Triggers (RetrainingTrigger)¶

Check Decision (RetrainingDecision)¶

6. Config Version Lifecycle¶

Source: tradai.common.entities.config_version.ConfigVersionStatus Service: ConfigVersionService (common)

States¶

Transition Diagram¶

stateDiagram-v2
    [*] --> DRAFT : Config version created
    DRAFT --> ACTIVE : Validated and deployed
    ACTIVE --> DEPRECATED : Superseded by new ACTIVE version
    DEPRECATED --> [*] : DynamoDB TTL auto-deletes (90 days)

Key Behaviors¶

• Content-addressable: Each version has a SHA256 config_hash for deduplication.
• Single active: Only one ACTIVE config version per strategy at any time.
• Immutable updates: with_status(ACTIVE) sets deployed_at; with_status(DEPRECATED) sets deprecated_at and ttl.
• Auto-cleanup: Deprecated versions have a 90-day TTL (_TTL_DAYS = 90) after which DynamoDB auto-deletes them.

7. DynamoDB State Tables¶

All tables use the naming pattern tradai-{purpose}-{environment}.

Strategy Promotion uses MLflow Model Registry (not DynamoDB) for stage tracking.

Serialization¶

All DynamoDB-persisted state entities extend DynamoDBSerializableMixin, which provides:

• to_dynamodb_item() -- serialize to DynamoDB-compatible dict
• from_dynamodb_item() -- deserialize from DynamoDB item

Combined with frozen=True and with_status() methods, this ensures all state mutations produce new immutable instances that are safely persisted.

Cross-Reference: Trace Context¶

Every backtest/training execution carries a unified trace context:

Changelog¶

Dependencies¶