PM Agent chat (Nemotron 3 Super + 39 tools)

The PM Agent — always-on chat surface routed through Nemotron 3 Super by default (Kimi K2.6 fallback). 39 tools registered, grouped into eight situational-awareness surfaces: sleeve build, rebalance workflow, compliance-gated execution, broker state, research, observability, cuOpt skills, and the advanced HybridRAG + Regimes overlays. Drive everything by typing.

What it is · how it works · why it matters

Overview

The PM Agent panel anchors the top of the Dashboard (col-span-8, with the Rebalance card seated above it) and is collapsible on every other page. Conversation state is per-session in the browser via sessionStore; chat history persists to data/audit/chat_log.jsonl. New session and Clear history buttons reset both the in-memory message buffer and the session-scoped store.

The PM Agent has full situational awareness: positions, pending orders + fills, recent bus events, rebalance plan + compliance verdict, audit decisions, backtest history, sleeve configs, HybridRAG retrieval, and active regimes are all reachable as tool calls. The system prompt enforces "if the user asks anything about live state and you didn't call a tool, you're guessing — call the tool."

Models & routing

CHAT_MODELS env var defines the ordered fallback chain. Default:

CHAT_MODELS=nvidia/nemotron-3-super-120b-a12b,moonshotai/kimi-k2.6

For every turn, NVTrader tries the first model. If it errors, rate-limits, or the response trips the _looks_degenerate() heuristic (token-loop repeats ≥15, single-char repeats ≥40, URL-fragment storms, mixed-script babble, leaked Kimi <|tool_call tokens), the loop transparently falls through to the next model with conversation state intact.

Sampling defaults: temperature=0.4, top_p=0.95, frequency_penalty=0.4, presence_penalty=0.1, max_tokens=2048, chat_max_hops_per_model=10. If the hop cap fires before a final answer, the loop coerces a final synthesis from the same model with tool_choice="none" instead of bouncing to the fallback empty-handed.

The 39 tools

Grouped by surface — same registry as scripts/chat.py, exposed both in the dashboard PM Agent panel and the standalone Chat page.

[ state awareness — read-only ]

[ rebalance workflow ]

The dashboard rebalance card lets the PM pin individual names with an × button on each order row — semantically “hold this position, don't trade it.” cuFOLIO still solves the full universe; the pinned rows are forced to delta_shares=0 after the solve. See Compliance → PM pin for the full mechanic.

[ compliance-gated execution ]

[ sleeve build + backtest ]

[ research ]

[ setup + provider linking ]

[ cuOpt skills — AI Planner ]

[ HybridRAG + Regimes — advanced overlays ]

Two-stage safety contract

Two of the 39 tools mutate live state: place_order and approve_rebalance. Both implement the same two-stage gate so a hypothetical question — "what if I buy 100 NVDA?" — can never submit an order.

1. Stage 1 — preview (always). Tool is called with confirmed=false. ComplianceAgent.check() always runs. Hard vetos (restricted list, PDT, buying-power, concentration cap) refuse the action and return {blocked_by_compliance: true, vetos: [...]}. Otherwise the tool returns a PREVIEW with the proposed weights, notional, and compliance status.
2. Stage 2 — execute (only on direct user confirmation). The model may set confirmed=true only when the user has issued an imperative this turn ("yes, execute", "submit", "go ahead"). Questions never trigger this. Hypothetical phrasing ("should I", "could I", "is it a good time") never triggers this.

The same compliance re-check happens server-side at /api/rebalance/decide — if the plan's compliance.violations contains a hard veto, the endpoint sets action_taken="blocked_by_compliance" and never reaches the broker. Defense in depth.

Example prompts

• what's the current rebalance plan? → explain_rebalance
• backtest momentum-only vs my Hybrid over the last 18 months → list_sleeves → compare_strategies(lookback_days=540)
• show me today's fills and any pending orders → get_recent_orders
• what just happened on the bus? → get_bus_events
• plan a portfolio that caps every name at 12% and targets long-only AI exposure → cuopt_plan → cuopt_explain
• scan my Hybrid sleeve across every regime → regime_scan(sleeve_id)
• what did NVDA's last 10-K say about supply constraints? → hybridrag_query
• approve the rebalance → approve_rebalance(confirmed=false) → user replies yes → approve_rebalance(confirmed=true)
• buy 2 NVDA at market → place_order(confirmed=false) → user replies execute → place_order(confirmed=true)

Reading the response

Most replies include both prose and a tabular block — the tabular block is the tool result rendered. The model is instructed to quote the tool result fields verbatim, so the broker column says sim or alpaca based on what actually fired, not what the model guessed.

Compliance vetos are surfaced as a callout: the rule name (e.g. max_position_pct), the proposed weight, and the cap. The model is told never to retry or suggest a workaround when blocked.

Adding a tool

Open src/traderspace/api/chat_server.py. Define a callable in _make_tool_registry(); add the JSON-schema entry to TOOL_SPECS. The PM Agent picks it up on the next turn. For mutating tools, follow the two-stage confirmed=false / confirmed=true pattern from place_order.

REST surface