Task Payload Contracts

This page captures the expected output payload shapes for the finance-flow task registry.

First-Wave Outputs

build_universe

Output: list[UniverseMember]

Representative element:

{
  "as_of_date": "2025-01-02",
  "symbol": "AAPL",
  "exchange": "XNYS",
  "instrument_id": "XNYS:AAPL",
  "close": 184.95,
  "currency": "USD"
}

calculate_signals

Output: list[SignalRecord]

Representative element:

{
  "as_of_date": "2025-01-02",
  "instrument_id": "XNYS:AAPL",
  "signal_name": "alpha",
  "horizon_days": 1,
  "value": 0.37
}

optimize_portfolio

Output: list[OptimizerAllocation]

Representative element:

{
  "as_of_date": "2025-01-02",
  "instrument_id": "XNYS:AAPL",
  "weight": 0.12,
  "score": 0.37
}

construct_target_positions

Output: list[TargetPositionRecord]

Representative element:

{
  "as_of_date": "2025-01-02",
  "instrument_id": "XNYS:AAPL",
  "target_weight": 0.12,
  "target_notional": 120000.0,
  "target_quantity": 600.0,
  "currency": "USD"
}

Second-Wave Outputs

backtest_portfolio

Output: list[BacktestResultRecord]

Representative element:

{
  "strategy_id": "default-strategy",
  "as_of_date": "2025-01-02",
  "return_pct": 0.001,
  "turnover": 0.5,
  "drawdown": -0.00025
}

evaluate_real_portfolio

Output: summary dictionary

Representative payload:

{
  "as_of_date": "2025-01-02",
  "tolerance_bps": 25.0,
  "mismatch_count": 1
}

build_alpha_report

Output: dictionary with report and top_signals

Representative payload:

{
  "report": {
    "report_id": "alpha-2025-01-02",
    "report_type": "alpha",
    "as_of_date": "2025-01-02",
    "generated_at": "2026-05-31T12:00:00Z",
    "schema_metadata": {
      "schema_name": "alpha-report",
      "schema_version": 1,
      "generated_at": "2026-05-31T12:00:00Z"
    }
  },
  "top_signals": [
    {
      "as_of_date": "2025-01-02",
      "instrument_id": "XNYS:AAPL",
      "signal_name": "alpha",
      "horizon_days": 1,
      "value": 0.37
    }
  ]
}

build_risk_report

Output: dictionary with report and risk_summary

Representative payload:

{
  "report": {
    "report_id": "risk-2025-01-02",
    "report_type": "risk",
    "as_of_date": "2025-01-02",
    "generated_at": "2026-05-31T12:00:00Z",
    "schema_metadata": {
      "schema_name": "risk-report",
      "schema_version": 1,
      "generated_at": "2026-05-31T12:00:00Z"
    }
  },
  "risk_summary": {
    "gross_exposure": 1.0,
    "net_exposure": 0.2
  }
}