Configuration

Configuration

Configuration is declarative and validated by Pydantic models in src/trading_system/config.py. All sections are required unless a default is shown.

Top-level structure

Key	Type	Required	Notes
base_ccy	string	✅	Reporting and portfolio currency (e.g., USD).
calendar	string	✅	Trading calendar code used to build business-day ranges (default NYSE).
data	DataConfig	✅	Raw data acquisition settings.
universe	UniverseConfig	✅	Symbols evaluated each run.
strategy	StrategyConfig	✅	Entry/exit expressions and rank metric for signals.
risk	RiskConfig	✅	Crash/drawdown thresholds and market filter.
rebalance	RebalanceConfig	✅	Cadence and portfolio construction limits.
notify	NotifyConfig	✅	Email/Slack coordinates. You can leave channels blank to disable them.
paths	PathsConfig	✅	Location of raw data, curated data, and reports. Paths are resolved relative to the config file.
preprocess	PreprocessConfig	optional	Overrides for forward-fill limits and peak windows.
backtest	BacktestConfig	optional	Defaults for ts backtest runs.

DataConfig

Field	Type	Required	Default	Description
provider	string	✅	—	Name of raw data provider (yahoo is implemented).
adjust	string	optional	null	Price adjustment policy (splits_dividends recommended).
lookback_days	integer	optional	null	Trading-day window downloaded on each run; defaults to the provider’s maximum if omitted.

UniverseConfig

Field	Type	Required	Description
tickers	list[string]	✅	Symbols pulled and evaluated. Order matters for ranking ties.

StrategyConfig

Field	Type	Required	Default	Description
type	string	✅	—	Free-form label for the strategy family.
entry	string	✅	—	Boolean expression evaluated by RuleEvaluator (e.g., close > sma_100).
exit	string	✅	—	Exit rule expression.
rank	string	optional	momentum_63d	Column or derived metric used to rank candidates.

RiskConfig

Field	Type	Required	Default	Description
crash_threshold_pct	float	✅	—	Max acceptable 1-day loss (e.g., -0.08).
drawdown_threshold_pct	float	✅	—	Max drawdown from the rolling peak.
market_filter	object	optional	null	See below.

market_filter uses MarketFilterConfig:

Field	Type	Required	Description
benchmark	string	✅	Symbol used as market filter (e.g., SPY).
rule	string	✅	Expression evaluated on curated benchmark data (e.g., close > sma_200).

RebalanceConfig

Field	Type	Required	Default	Description
cadence	string	✅	—	weekly, monthly, or custom cron-like label consumed by _is_rebalance_day.
max_positions	integer	✅	—	Cap on holdings after rebalance.
equal_weight	bool	optional	true	Equal-weight vs. rank-proportional weights.
min_weight	float	optional	null	Minimum target weight per holding.
cash_buffer	float	optional	null	Fraction of capital to keep in cash before sizing.
turnover_cap_pct	float	optional	null	Optional turnover cap applied after proposal construction.

NotifyConfig

Field	Type	Required	Description
email	string	optional	Recipient for daily email summaries.
slack_webhook	string	optional	Incoming webhook URL for Slack.

PathsConfig

Field	Type	Required	Description
data_raw	path	✅	Folder for raw parquet pulls (data/raw).
data_curated	path	✅	Folder for curated parquet outputs (data/curated).
reports	path	✅	Folder for rendered reports (reports).

PreprocessConfig

Field	Type	Default	Description
forward_fill_limit	integer	1	Max consecutive missing days to forward-fill.
rolling_peak_window	integer	252	Trading-day lookback for peak drawdown calculations.
calendar_frequency	string	B	Pandas frequency code for the trading calendar.

BacktestConfig

Field	Type	Default
initial_cash	float	100000.0
slippage_pct	float	0.001
commission_per_trade	float	0.0
annual_risk_free_rate	float	0.0
seed	int	7318009
include_chart	bool	True
trading_days_per_year	int	252

Optional section that seeds defaults for ts backtest when arguments are not supplied on the CLI.

Holdings schema

ts run and ts risk read holdings via load_holdings in src/trading_system/risk/__init__.py. Required structure:

{
  "as_of_date": "YYYY-MM-DD",
  "base_ccy": "USD",
  "cash": 10000.0,
  "positions": [
    { "symbol": "SPY", "qty": 50, "cost_basis": 420.0 }
  ]
}

• cost_basis is optional; set it to understand P&L columns in the report.
• Additional keys (e.g., sector, tags) are preserved but ignored by the current engines.

Minimal vs. full configs

Minimal (data/sample.yaml) – ships with the repo and is tuned for quick verification, single-ticker universe, and dry-run notifications.

base_ccy: USD
calendar: NYSE
data:
  provider: yahoo
  adjust: splits_dividends
  lookback_days: 420
universe:
  tickers: [SPY]
strategy:
  type: trend_follow
  entry: "close > sma_100"
  exit: "close < sma_100"
  rank: "momentum_63d"
risk:
  crash_threshold_pct: -0.08
  drawdown_threshold_pct: -0.20
  market_filter:
    benchmark: SPY
    rule: "close > sma_200"
rebalance:
  cadence: monthly
  max_positions: 8
  equal_weight: true
  min_weight: 0.05
  cash_buffer: 0.05
  turnover_cap_pct: 0.40
notify:
  email: null
  slack_webhook: null
paths:
  data_raw: ../data/raw
  data_curated: ../data/curated
  reports: ../reports
preprocess:
  forward_fill_limit: 1
  rolling_peak_window: 252

Full example (configs/sample-config.yml) – demonstrates multi-symbol universes, notification targets, and backtest defaults. Copy it when you need richer scenarios.

Validation and common errors

• Paths are resolved relative to the config file. If you relocate a config, update paths.* or you’ll end up writing under nested directories (e.g., data/data/raw).
• ts run refuses to overwrite curated artifacts unless --force is supplied; clean stale directories before re-running with the same as-of.
• load_config errors:
  • Configuration file must contain a mapping at the top level → ensure the root of the YAML is a dictionary.
  • Configuration missing 'paths' mapping → add a paths block with the three directories above.
  • Curated directory already populated ... Use --force → remove the directory or pass --force intentionally.
• load_holdings raises if positions is missing or malformed. Validate JSON with a linter and confirm symbol matches your universe case-insensitively.

See Troubleshooting for the most common stack traces and recovery tips.

Useful environment variables

Variable	Purpose
TS_CONFIG_PATH	Overrides the --config option for every CLI command.
TS_HOLDINGS_PATH	Default holdings snapshot for ts run, ts risk, and ts report.
TS_ASOF	Global default for as-of dates (ISO YYYY-MM-DD).
TS_DOCTOR_REQUIRED	Custom comma-separated tool list for ts doctor.