The brain behind your trading desk.

Every trade suggestion is bespoke to your portfolio, your risk profile, your capital. This isn't a signal service — it's a personal trading intelligence system for income-first options traders.

pip install income-desk
income-desk --trader us       # See it in action immediately
income-desk --trader india    # India market version

The fastest way to understand income-desk. One command walks you through every API — with real broker data or seamless simulated fallback.

python -m income_desk.trader

+------------------------------------------------------------------+
|                         WORKFLOW HARNESS                         |
+------------------------------------------------------------------+
| Market: US                                                       |
| Broker: tastytrade (LIVE)                                        |
| Data:   Broker connected (market closed)                         |
| Tickers (16): AAPL, AMZN, DIA, GLD, GOOGL, IWM + 10 more       |
| Account: NLV USD 32,635  |  BP USD 30,555                       |
+------------------------------------------------------------------+

Exercises all 15 workflow APIs across 7 phases that mirror a real trading day. Each workflow prints:

• API signature with all Pydantic request fields and values
• CLI equivalent (analyzer-cli> rank SPY QQQ ...)
• Tabular results — regimes, ranked trades, gate scorecards, stress scenarios, Greeks

Pricing data is clearly flagged when simulated: ** SIMULATED QUOTES — not tradeable **

# Interactive — pick market, walk through each phase
python -m income_desk.trader

# Non-interactive — run all phases, get pass/fail summary
python -m income_desk.trader --all --market=US
python -m income_desk.trader --all --market=India

# Single phase
python -m income_desk.trader --phase=2 --market=US    # Scanning only
python -m income_desk.trader --phase=5 --market=India  # Portfolio Risk

# Verbose — show library warnings and tracebacks
python -m income_desk.trader --all --market=US --verbose

Phases feed into each other naturally:

• Phase 2 rank_opportunities produces trade proposals with real strikes
• Phase 3 validate_trade + size_position + price_trade use that top proposal
• Phase 4-6 use demo positions (since harness doesn't manage real positions)

After running all phases, the harness prints a summary:

  HARNESS SUMMARY
+-----------------+----------------------------+----------+
| Phase           | Workflow                   | Status   |
+-----------------+----------------------------+----------+
| 1-PreMarket     | check_portfolio_health     | OK       |
| 1-PreMarket     | generate_daily_plan        | OK       |
| ...             | ...                        | ...      |
| 7-Reporting     | generate_daily_report      | OK       |
+-----------------+----------------------------+----------+
  Total: 15  |  Passed: 15  |  Failed: 0

Define your entire trading strategy in markdown. No Python needed.

income-desk v2 introduces trader_md — a declarative trading platform where .workflow.md files ARE the strategy, .risk.md files ARE the risk rules, and .universe.md files ARE the ticker lists. The Python engine runs underneath, but you never touch it.

# Validate your workflow
python -m income_desk.trader_md validate workflows/daily_us.workflow.md

# See what would execute (no API calls)
python -m income_desk.trader_md dry-run workflows/daily_us.workflow.md

# Execute the full trading workflow
python -m income_desk.trader_md run workflows/daily_us.workflow.md

# Interactive mode — pause between steps
python -m income_desk.trader_md run workflows/daily_us.workflow.md --interactive

Your entire trading platform is a set of markdown files:

trader_md/
  workflows/
    daily_us.workflow.md          <- your strategy
    daily_india.workflow.md
  broker_profiles/
    tastytrade_live.broker.md     <- broker config (no secrets)
    dhan_live.broker.md
    simulated.broker.md
  universes/
    us_large_cap.universe.md      <- ticker lists
    india_fno.universe.md
  risk_profiles/
    conservative.risk.md          <- risk rules
    moderate.risk.md
    aggressive.risk.md
  scenarios/
    black_monday.scenario.md      <- 18 stress test scenarios
    ...
  .env.trading                    <- credentials (gitignored)

---
name: daily_us_income
broker: tastytrade_live
universe: us_large_cap
risk_profile: moderate
---

## Phase 1: Market Assessment

### Step: Market Pulse
workflow: check_portfolio_health
inputs:
  tickers: $universe
  capital: $capital
outputs:
  pulse: $result.sentinel_signal
gate:
  - pulse != "RED"
on_fail: HALT "Market pulse {pulse} -- trading halted"

### Step: Rank Opportunities
workflow: rank_opportunities
inputs:
  tickers: $universe
  capital: $capital
  min_pop: $risk.min_pop
gate:
  - len(proposals) > 0
on_fail: SKIP "No opportunities"

• A portfolio manager edits min_pop: 0.50 to min_pop: 0.60 in the risk file. Behavior changes. No Python.
• A new developer reads the workflow file and understands the entire trading pipeline in 5 minutes.
• An auditor gets the .workflow.md file — it IS the complete trading logic. Every gate, every threshold.
• Git diff shows exactly what changed in a strategy. PR review catches "you removed the overnight risk gate."
• AI generates strategies — describe in English, Claude produces the .workflow.md.

# v1: Python path (interactive harness)
python -m income_desk.trader --all --market=US          # 15/15 workflows

# v2: MD path (declarative workflows)
python -m income_desk.trader_md run daily_us.workflow.md  # same engine, defined in markdown

Both call the same 15 workflow APIs. Choose your style.

Trading doesn't start with placing an order. It starts with setting up your desk.

income-desk supports the complete lifecycle — from portfolio construction to AI/ML learning. Each step below shows what the library provides and what you can build on top.

Define your starting capital and risk tolerance. The library models your account and recommends how to structure it.

income-desk --demo           # Creates $100K simulated portfolio
> desk 100000 --risk moderate

Split capital across trading desks, each with its own mandate. Desks are the organizational unit — income desk, 0DTE desk, wheel desk, directional desk.

> portfolio    # View all desks with capital allocation

Each desk has a strategy whitelist, DTE range, and instrument type. The 0DTE desk only takes same-day expiries. The income desk only takes 21-60 DTE defined-risk structures.

Choose how much of your capital can be in undefined-risk positions. This controls what structures the system will suggest.

> margin_buffer SPY    # Margin impact preview
> margin SPY 35000     # Full margin analysis

Pick what you trade. Built-in presets get you started. Broker watchlists sync automatically.

> scan_universe income
> watchlist --list          # Show broker watchlists

Filter your universe down to actionable candidates. Multiple screen types catch different setups.

> screen SPY QQQ IWM GLD TLT
> screen --watchlist income_etfs

Rank surviving candidates by composite score: regime alignment, phase, IV rank, income bias. Every score is explainable.

> rank SPY QQQ IWM GLD TLT --debug
> rank --watchlist income_etfs --account 35000

Read raw price bars like a day trader. 19 classical candlestick patterns detected from OHLCV data, scored by context (trend, volume, support/resistance proximity). Timeframe-agnostic — works on daily bars or intraday.

> candles SPY                    # Scored patterns (daily, last 10 bars)
> candles SPY --lookback 20      # Scan last 20 bars
> candles SPY --raw              # All detections, no conviction filter

CANDLESTICK PATTERNS: SPY (daily, last 10 bars)
──────────────────────────────────────────────────
  2026-03-28  BULLISH_ENGULFING  bullish  conviction: 78
              bullish_engulfing: after bearish trend, volume 1.8x avg, near key level

  Strongest: BULLISH_ENGULFING (78) — bullish
  Summary: 1 bullish, 0 bearish

Composable API — use at any level:

from income_desk.features.patterns.candles import (
    detect_candlestick_patterns,    # Layer 1: raw geometric detection
    score_candlestick_patterns,     # Layer 2: context scoring (0-100)
    compute_candlestick_patterns,   # Convenience: detect + score + summarize
)

# Raw detection (for backtesting)
patterns = detect_candlestick_patterns(ohlcv_df, lookback_bars=10)

# Scored (for live decisions)
scored = score_candlestick_patterns(ohlcv_df, patterns)

# All-in-one
summary = compute_candlestick_patterns(ohlcv_df)
summary.strongest   # highest conviction pattern
summary.bullish_count, summary.bearish_count

Auto-included in TechnicalSnapshot — patterns appear alongside RSI, MACD, VCP, Smart Money:

snap = ma.technicals.snapshot("SPY")
snap.candlestick_patterns.strongest.pattern   # CandlePatternType.BULLISH_ENGULFING
snap.candlestick_patterns.strongest.conviction  # 78

Conviction scoring (0-100): Trend alignment (30), body conviction (20), volume confirmation (20), S/R proximity (20), pattern complexity (10). All thresholds configurable via candle_* settings.

Generate trade structures for top candidates. These are proposals — not yet validated against your portfolio.

> opportunity SPY
> opportunity IWM --debug    # Full commentary trace

This is where income-desk's validation engine kicks in. The scenario trade gets tested against your portfolio, risk limits, and real market data.

> validate SPY              # 10-check profitability gate
> audit SPY 35000           # 4-level decision audit
> kelly SPY 35000           # Position sizing
> sentinel                  # Crash sentinel status

The validated trade becomes a real position. TradeSpec carries everything the broker needs — legs, strikes, expiration, order type, chase limit.

> trade SPY                 # Place trade in demo portfolio
> close_trade abc123        # Close position and record P&L

Ongoing position monitoring with actionable signals. Every check returns a concrete action — hold, close, or adjust — with a closing TradeSpec when needed.

> health SPY                           # Position health check
> monitor SPY                          # Exit condition scan
> exit_intelligence SPY 10 0.30        # Exit analysis with DTE and P&L
> assignment_risk SPY                  # Assignment risk assessment

When a position is tested, income-desk returns a deterministic adjustment decision — not a menu of options. Roll, convert, or close, with the exact TradeSpec to execute.

> adjust SPY                           # Get adjustment recommendation
> assignment SPY 570 put               # Handle assignment scenario
> csp IWM 240 2.50                     # Cash-secured put analysis
> covered_call IWM 240                 # Covered call after assignment

Close the loop. Every trade outcome flows back into the system. Ranking weights calibrate, gate thresholds tune, and the system gets sharper over time.

> performance                          # Performance report
> sharpe                               # Sharpe ratio analysis
> drift                                # Portfolio drift detection

pip install income-desk

# Full US trading simulation
income-desk --trader us

# Full India trading simulation
income-desk --trader india

# Interactive demo with $100K portfolio
income-desk --demo

# Offline (weekends/after hours)
income-desk --sim income      # Ideal income day (elevated IV, R1)
income-desk --sim recovery    # Post-crash rich premiums (R2, IV rank 80%+)
income-desk --sim crash       # Test crash playbook

Note: thinkorswim is Schwab's trading platform. The Schwab broker integration covers both — connecting via the Schwab API gives you access to thinkorswim accounts. No separate integration needed.

income-desk --setup    # Connect your broker

Works without any broker (yfinance free data). Connect a broker for real-time quotes, Greeks, and HIGH trust analysis.

Many traders have accounts across multiple brokers — TastyTrade for options, Schwab for equities, Fidelity for retirement. income-desk treats ALL your accounts as one portfolio.

Example: You have 3 accounts:

• TastyTrade: 2 iron condors (API connected)
• Schwab IRA: 5 equity positions (API connected)
• Fidelity 401K: index funds (CSV import)

income-desk sees all 10 positions as ONE portfolio. Kelly sizing accounts for the Fidelity positions. Correlation checks catch SPY IC + SPY index fund overlap. The crash sentinel monitors everything.

CSV import for non-API brokers:

> import_trades ~/Downloads/fidelity_trades.csv
Detected: fidelity | Imported: 12 positions | Skipped: 2

Supported formats: thinkorswim, TastyTrade, Schwab, IBKR, Fidelity, Webull, generic.

Every output tells you how much to trust it:

TRUST: 85% HIGH
  Data: 90% HIGH (broker_live) | Context: 85% HIGH (full mode)
  Fit for: ALL purposes including live execution

No broker? Trust = LOW — fit for research only. Full trust framework docs

income-desk has no backtesting engine. Deliberately.

Start with 1 contract. Validation gates protect your capital. System learns from YOUR real outcomes. Kelly scales up as edge is proven.

1 contract → validation gates protect → record outcome →
calibrate_weights() learns → Kelly scales up → repeat

15 high-level operations — one function call per trading action. All rate limiting, caching, and orchestration handled internally. Trades only propose strikes verified liquid in the broker's option chain.

from income_desk.workflow import generate_daily_plan, DailyPlanRequest

plan = generate_daily_plan(
    DailyPlanRequest(tickers=["NIFTY", "BANKNIFTY", "RELIANCE", "TCS"], capital=5_000_000, market="India"),
    ma,
)
# plan.proposed_trades[0].short_put = 2300 (verified OI=305,000)

Every workflow: Pydantic request in, Pydantic response out, WorkflowMeta with timestamp and warnings.

Full pipeline works without broker, internet, or market hours. Swap one line to go from live to simulated.

from income_desk.adapters.simulated import create_india_trading, create_ideal_income, SimulatedMetrics

# India: 22 tickers (5 indices + 17 F&O stocks, correct strike intervals & lot sizes)
sim = create_india_trading()

# US: 16 tickers (SPY/QQQ/IWM + AAPL/MSFT/NVDA/TSLA + sector ETFs)
sim = create_ideal_income()

# Create analyzer — all 15 workflows work identically
ma = MarketAnalyzer(data_service=DataService(), market_data=sim, market_metrics=SimulatedMetrics(sim))

# Discovery: what tickers does this simulation support?
sim.supported_tickers()   # ["NIFTY", "BANKNIFTY", "RELIANCE", ...]
sim.has_ticker("NIFTY")   # True
sim.ticker_info()         # {"NIFTY": {"price": 23000, "iv": 0.18, ...}}

Available presets: create_calm_market, create_volatile_market, create_crash_scenario, create_post_crash_recovery, create_wheel_opportunity, create_india_market, create_india_trading, create_ideal_income.

Run all 18 macro scenarios against your portfolio in one call. Factor model with correlations, IV leverage effect, and Monte Carlo confidence intervals.

from income_desk.workflow import stress_test_portfolio, StressTestRequest

result = stress_test_portfolio(
    StressTestRequest(positions=my_positions, capital=5_000_000, market="India"),
    ma,
)
# result.risk_score = "safe"
# result.worst_scenario = "black_monday" (INR -8,814 loss)
# result.scenarios_breaching_limit = []

18 scenarios: S&P corrections (-5/-10/-20%), Black Monday, NIFTY crash, FII sell-off, RBI rate hike, commodity meltup, gold crash, rate shock, inflation/deflation, tech rotation, geopolitical shock, correlation spike.

Scenario engine (income_desk/scenarios/) also available standalone for stress-testing market data:

from income_desk.scenarios import apply_scenario
stressed_sim, result = apply_scenario(baseline, "nifty_down_10")
# stressed_sim is a new SimulatedMarketData — use with any workflow

Run every market day to verify the pipeline is production-ready:

.venv_312/Scripts/python.exe scripts/daily_profitability_test.py          # live Dhan
.venv_312/Scripts/python.exe scripts/daily_profitability_test.py --sim    # simulated

Produces a GO / CAUTION / NO-GO verdict based on: broker connectivity, option chain quality, regime detection, trade recommendation quality, validation gate pass rate, and position sizing sanity. Reports saved to ~/.income_desk/profitability_reports/.

• Architecture — system design
• Integration Guide — APIs, contracts, boundaries
• Roadmap — delivery tracker
• Vision — mission and philosophy
• Trust Framework — 3-dimensional data reliability scoring
• Crash Playbook — systematic crash response protocol

Workflows:  daily_plan, snapshot, portfolio_greeks, profitability, presets, expiry_check, scenario, stress_portfolio
Trading:    validate, rank, screen, opportunity, entry_analysis, kelly, audit, sentinel
Monitoring: health, monitor, exit_intelligence, adjust, assignment_risk
Portfolio:  desk, portfolio, trade, close_trade, rebalance
Sizing:     kelly, size, margin, margin_buffer, csp, covered_call
Research:   regime, technicals, candles, vol, levels, research, stress, rate_risk
Account:    balance, quotes, watchlist, wizard

Run help in the CLI for the full list.

See CONTRIBUTING.md. Adding a broker = ~170 lines of field mapping, zero core changes.

MIT — see LICENSE.