Setup wizard

The Setup Wizard is an agent-driven flow that walks you through linking every provider NVTrader can talk to — brokers, market-data sources, LLM endpoints — and runs a smoke connection test on each. It reads from skills/setup/*.md so the steps stay in sync with the operator playbooks.

What it is · how it works · why it matters

How to invoke it

1. From any page, click 🪄 Wizard in the embedded chat panel or
2. type get_setup_guide alpaca in chat (substitute the provider id), or
3. navigate to Account → API keys and click Configure next to a provider.

The wizard reads the matching markdown file from skills/setup/<category>/<provider>.md and reformats it as a step-by-step in-chat experience. Each step ends with a button that copies the right URL to your clipboard or pre-fills the right field.

Supported providers

What the wizard does

For every provider the steps are the same shape, so the flow is predictable:

1. Pre-flight — wizard tells you what kind of account you need and the rough cost (e.g. Alpaca paper is free; Finnhub free tier caps at 60 req/min; Tavily free credits drop after the first 1000 calls).
2. Get the key — link to the exact dashboard URL and the click path. For OAuth providers (Webull, IBKR) it walks the consent flow.
3. Paste & encrypt — paste the key into the in-chat form. NVTrader Fernet-encrypts at rest immediately; you cannot read it back, only the masked prefix/suffix.
4. Smoke test — the wizard fires test_provider_connection. For brokers that's a no-op call (e.g. get_account()); for data providers it pulls one bar/snapshot; for LLMs it sends a one-token "ping".
5. Activate — if the smoke test passes you can pick the provider as active right then (e.g. Active broker → Alpaca).

Adding a provider yourself

Drop a new markdown file into skills/setup/<category>/<id>.md using the existing playbooks as a template. The wizard picks it up automatically because it discovers via filesystem scan.

If the provider needs a custom adapter (rather than the generic OpenAI-compatible / REST shape), wire it under src/traderspace/broker/<id>.py or src/traderspace/data/<id>.py and import it from the relevant __init__.py. The BrokerAdapter and DataAdapter ABCs spell out the wire shape — keep new adapters drop-in compatible and the rest of the platform inherits broker switching, audit trails, and OTel spans for free.

Reading the wizard output

The wizard's final message includes a JSON block:

{
  "provider": "alpaca",
  "category": "broker",
  "linked": true,
  "test": {
    "endpoint": "https://paper-api.alpaca.markets",
    "ok": true,
    "elapsed_ms": 612,
    "account_status": "ACTIVE",
    "buying_power": 200000.00,
    "cash": 100000.00
  }
}

If linked: true but test.ok: false, the key was stored but the smoke call failed. Common causes: paper vs live mismatch (Alpaca), expired sandbox token (Webull), or wrong region (Polygon).

REST surface