The Firm Machinery

The ten desks only produce reads. Turning those reads into a disciplined, recorded, self-improving decision is the job of a whole machinery of non-desk roles — the parts of HeliQuant that act like the rest of a real trading firm: a steward who keeps the data healthy, researchers who argue, a PM who decides, a floor that trades, a risk officer who sizes, and a back office that records and learns.

The merge — the floor proposes, the LLM PM disposes

HeliQuant has two engines: the slow LLM org (the full desks then debate then PM cycle, analyse-only) and the fast no-LLM floor (campaign.py, a continuous paper trader).

The PM sign-off merge (firm/pm_signoff.py + the gate in campaign.py, search PM SIGN-OFF (THE MERGE)) couples them at the decision: the floor still proposes a trade from its quantitative gates, but the LLM Portfolio Manager now signs off — APPROVE or VETO — on every candidate as the final gate before a position opens. It is fed the live floor signals (trend, stretch, TV 1h-vs-1D, range-position, whale stance, size, SL/TP) — fresh, not the org's stale feature CSVs — and it is one LLM call (z-ai/glm-5.3-flash on NEAR AI Cloud, Groq when HQ_PROVIDER is not nearai), not the full org cycle.

Crucially it fails open (approve) on any 429 / outage (pm_signoff.py) — the algorithmic gates already vetted the setup, so an LLM hiccup never freezes the floor. The verdict is recorded on the position (p["pm"], campaign.py) and surfaced on /campaign. Toggle with PM_SIGNOFF (default on, pm_signoff.py).

The floor proposes; the LLM disposes. This is what makes the LLM genuinely drive trades — not just narrate them. It does not manufacture a profit edge: the directional book is still ~breakeven, and no edge has been validated on NEAR (the registry is empty).

The full machinery

The roles

Steward — keeps the watchlist healthy

organization.py · run_operations / STEWARD_SYS. The steward reads a deterministic whale-watchlist health report (how many wallets still qualify, data age, losers) and decides one thing: MIGRATE (re-scan fresh Rhea pool activity via GeckoTerminal and replace under-performers) or KEEP. It does not pick which assets to analyze — the cycle's asset is chosen in app.py by simple rotation (ASSETS[cycles % len(ASSETS)], app.py). The steward's job is purely data hygiene: never mirror stale or loss-making wallets.

• In: wm.evaluate(wm.load()) health report (deterministic).
• Process: one LLM call judges the numbers (STEWARD_SYS); on migrate, wm.migrate() re-scans GeckoTerminal. Fails to a deterministic rule if the LLM is unavailable.
• Out: {action, confidence, reason} + before/after health.

Researchers — the bull and the bear

organization.py · run_debate. Two researchers argue over the desk outputs in two rounds (opening + rebuttal) on z-ai/glm-5.3-flash (NEAR AI Cloud, reasoning on; Groq gpt-oss-120b as fallback). This surfaces dissent before the PM sees it, so a one-sided desk consensus gets stress-tested instead of rubber-stamped.

• In: desk tool outputs + the LLM desk stances.
• Process: BULL_SYS / BEAR_SYS open, then *_REBUT_SYS rebut (4 LLM calls total).
• Out: {bull, bear, bull_rebuttal, bear_rebuttal}.

Portfolio Manager — the decision

organization.py · run_pm / PM_SYS. The PM weighs the desks ranked by learned reliability (_ranked_desk_view), reads the debate, and outputs ENTER (only when a validated edge fires) or ABSTAIN. finalize_decision then attaches a gated trade ticket; if the ticket can't clear the R:R gate it re-prompts the PM up to twice, then overrides to a disciplined ABSTAIN — never up to a trade.

• In: ranked desk stances + debate + regime status + advisory briefs (memory, carry, flow, whale, NEAR fundamentals).
• Process: one deep LLM call; then build_trade_ticket gates the result (repair loop, max 2).
• Out: {decision, direction, confidence, reasoning, desk_consensus, trade_ticket, ticket_note}.

The trading floor

• Campaign (campaign.py · step) — a continuous paper floor at live prices. It computes its own deterministic desk votes (desk_votes — flow-intel, z-score positioning extremes and the Hyperliquid whale read; no LLM), then every candidate must clear an ordered entry-quality pipeline — macro de-risk, deep-cold bench, cold-cadence, mid-range chop, clear-trend, don't-fight-trend flip, TV 1h-vs-1D, smart-money whale veto, over-extension, and finally the LLM PM sign-off (the merge, above). Approved trades are sized on a warm/cold ladder with per-asset calibrated stops. It runs even when the org abstains, so there's always a live, honest track record (metrics at /performance).
• Exploration (exploration.py) — when the org ABSTAINs, a small paper-hunt budget opens exploratory positions on flow consensus, resolves them at 24h, and feeds the outcome to the learning loop. Abstaining doesn't mean idle — it means hunting carefully.

Risk sizing — the trade ticket

trade_ticket.py · size_position. Every ENTER is sized by size_position, whose notional = risk$ × (entry / stop-distance) mirrors the backtested engine. It picks SAFE (the bounded conviction band, 0.5–1.5% risk) or AGGRESSIVE (fractional Kelly — the kelly_fraction_star output field) and clamps with hard caps: ≤ 3% risk, ≤ 5× leverage, plus a 20% drawdown breaker that forces SAFE. AGGRESSIVE is unlocked only when an OOS-validated edge's live signal fires with ≥ 20 samples; crowding only ever sizes down.

The learning loop

desk_performance (reliability weights, 0.6–1.4, ≥ 15 samples) · edge_lab (validates candidate edges OOS with walk-forward + outlier-robustness + Benjamini–Hochberg FDR) · cond_record (regime-aware tactical memory on the floor) · edge_evolver (offline search for variants when an edge decays). Together they make the firm self-improving — desks that call it right gain weight, edges that decay lose validation. This is its own subsystem; see Self-learning for the full treatment.

The back office — recording & persistence

• On-chain recorders (onchain_recorder, agent_onchain) — seal each desk's output and the decision hash on NEAR every cycle (see On-chain).
• State & memory (state_store, memory_store) — persist the firm's state, decisions, campaign book, and ledger to Supabase (hq_state / decisions_hq) so nothing is lost across Railway redeploys.
• Strategy lifecycle (strategy_lifecycle) — offline research tooling that promotes/demotes whole strategies by status as their evidence strengthens or decays. It is imported by offline scripts, not by the live organization.py loop — so it documents the lifecycle, it doesn't run inside a cycle.

A decision's journey