What (One-liner)

Canvas Bull Agent: two-step call → trader-select computes bull/bear weights from regime; dual-agent-simulate runs a monthly portfolio simulation with a bull basket (SPY+QQQ) and a bear basket (TLT+GLD). UI shows bull_weight + total_return + Sharpe.

How to use

macro_snapshot_v1 → bull_agent_v1  (regime=expansion, n_periods=12)
                                   → weight=0.65, total_return=8.2%, Sharpe=1.3

Typically paired with bear_agent_v1:

       ┌─ bull_agent_v1 (weight=0.65)
regime ┤
       └─ bear_agent_v1 (weight=0.35)

Core formulas

POST /casa/trader-select {regime, w?, cli?, cycle_phase?}
  → bull_weight, bear_weight (sum=1), strategy_bias, reasoning

POST /casa/dual-agent-simulate {regime, n_periods=12, initial_capital=1M}
  → simulate portfolio = bull_w × (SPY 40% + QQQ 60%) + bear_w × (TLT 60% + GLD 40%)
  → history (per month) + summary {final_value, total_return_pct, Sharpe, max_drawdown_pct}

bull_agent_v1 extracts: {weight: bull_weight, total_return, sharpe, max_drawdown, ...}
bear_agent_v1 extracts: {weight: bear_weight, ...}

Assumptions & applicability

Assumptions: monthly frequency + fixed bull/bear baskets (SPY+QQQ, TLT+GLD) + rule-based weights + fallback seed 42.

Applies to: cross-asset allocation scenarios on the Canvas, bull vs bear comparisons, regime-rotation demos.

Does not apply to: live trading, custom portfolios, non-US markets, leverage optimization.

Input / Output contract

{regime?, w_current?, cli_direction?, cycle_phase?, n_periods?=12} → {agent_type='bull', weight, strategy_bias, reasoning, regime, total_return, sharpe, max_drawdown}

Known limitations

1. Hard-coded tickers (SPY/QQQ/TLT/GLD)
2. Monthly frequency
3. Rule-based weights (not ML)
4. Fallback distribution differs from yfinance real
5. Fallback seed=42 hard-coded
6. No intra-portfolio rebalancing
7. Symmetric with bear_agent_v1 (shared 2-call backend; UI extracts different fields)

References

Faber (2007) Tactical Asset Allocation + Pangura Internal Rulebook. See frontmatter for full citations.

Golden Test

Two shared fixtures:

• tests/golden/fixtures/tier4/casa_trader_select/ — 16 rule branches + 6 contract tests
• tests/golden/fixtures/tier4/casa_dual_agent/ — 6 fallback-path scenarios + 5 contract tests

17 tests in total.

Changelog

• 1.0.0 (2026-04-21) — First Active (Tier 4 batch 1.2; sister operator bear_agent_v1)