Skip to content

Typed Data Interfaces Migration

This document describes how FinLab trading payloads move from implicit dict/list structures to formal typed interfaces, while preserving backward compatibility.

1. New public schemas

Import from finlab.schemas:

  • PositionEntry
  • OrderEntry
  • StrategyPositionData
  • PortfolioConfigData
  • PortfolioData

All dataclasses provide from_dict() / to_dict().

2. Position typed API

  • Position.from_entries(entries)
  • Position.to_entries()

Notes: - Legacy from_list() / to_list() are still supported. - Typed and dict APIs can coexist during migration.

3. OrderExecutor typed API

  • OrderExecutor.generate_orders(..., as_entries=False, quantity_type='decimal')
  • OrderExecutor.generate_order_entries(..., quantity_type='decimal')

quantity_type supports: - decimal (default) - float - string

Default behavior is unchanged: generate_orders() still returns list[dict].

4. PortfolioSyncManager typed API

  • get_data(typed=False)
  • set_data(data, typed=False)
  • get_data_typed()
  • set_data_typed(data)

Notes: - Internal storage (self.data) remains the same dict shape. - Typed conversion is done only at API boundaries, keeping to_path / to_local / to_cloud compatible.

5. symbol / stock_id compatibility policy

Current policy: - symbol is canonical. - stock_id remains a backward-compatible alias. - Conflicting values in both keys raise an error.

Recommendation: - Prefer symbol in new code. - Keep stock_id read compatibility in third-party integrations until a major-version removal plan is announced.

Planned direction (tentative): - 1.x: stock_id stays fully supported as alias - 2.x (not earlier than): re-evaluate warning-only mode or alias removal

6. Report Typed API

CloudReport provides typed access to strategy reports:

  • CloudReport.from_dict(report_dict, execution_dict) — construct from dicts
  • CloudReport.position_info2() — get position info
  • CloudReport.position_schedulers — schedulers and weights

ReportExecution wraps backtest execution config:

  • ReportExecution.from_dict(d) / .to_dict()
  • .weights — current position weights (pd.Series)
  • .next_weights — next-period position weights
  • .actions — stop-loss / take-profit actions
  • .config — backtest config (resample, stopLoss, takeProfit, etc.)
  • .current_rebalance_date / .next_rebalance_date — rebalance dates
  1. Move data models to finlab.schemas dataclasses.
  2. Switch to typed APIs incrementally (from_entries, generate_order_entries, get_data_typed).
  3. Keep dict fallback until UI/DB/scheduler layers finish migration.