This page is the engineering reference: every component of HeliQuant — the LLM org and the LLM-gated floor — described as a clean In → Process → Out triplet with its file and function. It's deliberately terse; the narrative lives in Architecture, The Desks, and The Firm Machinery.

One honest frame for the whole page. The PM sign-off merge makes the LLM genuinely drive trades — but it creates no profit edge. The directional book is ~breakeven, and no edge has been validated on NEAR (the registry is empty).

How the two engines connect

---

The LLM Org (organization.py)

Steward

run_operations · organization.py · STEWARD_SYS

• In: deterministic whale-watchlist health report (wm.evaluate(wm.load())).
• Process: one LLM call judges the numbers → MIGRATE or KEEP; on migrate, wm.migrate() re-scans GeckoTerminal. Falls back to a deterministic rule if the LLM is down. (Decides watchlist health only — the cycle's asset is chosen by rotation in app.py, not here.)
• Out: {action, confidence, reason} + before/after health + migration result.

The 10 LLM desks

build_desks · organization.py — each desk = (a real tool output) + (one LLM interpretation via run_analysts, ANALYST_SYS). On NEAR AI Cloud every desk runs on Qwen/Qwen3.8-27B.

Each desk's per-stance step:

• In: the tool output JSON + the desk's domain string.
• Process: one ANALYST_SYS LLM call — interprets, never invents numbers.
• Out: {stance, confidence, key_point}.

Debate (Bull / Bear)

run_debate · organization.py · BULL_SYS / BEAR_SYS / *_REBUT_SYS

• In: all desk tool outputs + all desk stances.
• Process: 2 rounds (opening + rebuttal), 4 deep-model LLM calls — surfaces dissent before the PM.
• Out: {bull, bear, bull_rebuttal, bear_rebuttal}.

Portfolio Manager

run_pm · organization.py · PM_SYS

• In: desk stances ranked by learned reliability (_ranked_desk_view) + the debate + regime status + advisory briefs (memory, carry, flow-intel, whale, NEAR fundamentals — all additive, never altering the gates).
• Process: one deep LLM call. Rule: a pure trend thesis → ABSTAIN; the one ENTER exception is a validated, actionable OI-Contrarian edge; a hard rugpull veto forces ABSTAIN.
• Out: {decision, direction, confidence, reasoning, desk_consensus, self_management}.

finalize_decision

organization.py

• In: the PM decision + desks + real structure (entry/ATR/swings via _state, _swings).
• Process: on ENTER, builds a gated trade_ticket; if it fails the R:R gate, re-prompts the PM up to 2× (MAX_TICKET_REPAIR), then overrides to a disciplined ABSTAIN. Never repairs up to a trade.
• Out: the decision with trade_ticket + ticket_note attached (or ABSTAIN).

trade_ticket

trade_ticket.py — build_trade_ticket → build_levels + size_position + validate_ticket

• In: direction + conviction (from the PM) + real ATR/swing structure + optional edge profile.
• Process: price math for entry zone / structural stop / TP ladder / R:R; size_position picks SAFE (conviction band 0.5–1.5%) or AGGRESSIVE (fractional Kelly — kelly_fraction_star is its output field), clamped to ≤ 3% risk / ≤ 5× leverage with a 20% drawdown breaker; crowding sizes down only. Then the Layer-3 gate validates R:R ≥ 2, consistent levels, caps, allowlist.
• Out: a {valid, problems, entry_range, stop_loss, take_profit[], mode, risk_pct, notional_usd, kelly_fraction_star, …} ticket.

Deterministic / real-source tools

The numbers the desks interpret are computed here (no LLM):

Non-desk roles

---

The Floor (now LLM-gated) (campaign.py)

A continuous paper trader at live prices (real Bitget Demo fills only when BITGET_EXECUTE=1).

Signals (the floor's own conviction — no LLM)

desk_votes · campaign.py — sums a directional vote:

• flow-intel stance (flow_intel.synthesize) + z-score positioning extremes (OI/funding/flow/momentum) from data/<asset>_positioning.csv (fed through POST /ingest);
• Hyperliquid whale read, double-weighted when high-conviction (hl_whales.whale_read);
• NEAR-TVL lean for NEAR-ecosystem assets (_near_lean, DeFiLlama), gated by price confluence.
• In: the positioning CSV (used only when ≤ 12h old) + live whale/TVL. Out: (net_votes, reasons[]).

Live tools (cheap, deterministic)

The entry-gate pipeline

step · campaign.py. An ordered, per-asset stack (each is a plain skip — abstaining one asset never stalls the basket). The live list is on /campaign as entry_gates:

1. macro event-risk de-risk (macro_calendar) · 2. deep-cold bench · 3. cold-cadence throttle ·
2. mid-range chop · 5. clear-trend required (flat → abstain) · 6. don't-fight-trend flip (contrarian → trend-follow) · 7. TV 1h-vs-1D counter-daily · 8. smart-money whale veto · 9. over-extension ·
3. fee-breakeven near-TP guard (exit-side) — then the new final gate:

PM sign-off (the merge — final gate)

pm_signoff.signoff · pm_signoff.py · called from campaign.py · step

• In: the floor's candidate (asset, direction, top reasons) + live signals {trend_1h, stretch_atr, tv_vs_1d, range_pos, whale, size_usd, sl_pct, tp_pct} — fresh, not the org's CSVs.
• Process: one LLM call (SIGNOFF_SYS; z-ai/glm-5.3-flash on NEAR AI Cloud, Groq when HQ_PROVIDER is not nearai) → APPROVE / VETO. Fails open (approve) on any error (pm_signoff.py) so a 429/outage never freezes the floor. Toggle PM_SIGNOFF (default on).
• Out: {approve, reason, model} — recorded on the position as p["pm"] (campaign.py); a VETO logs a shadow for later scoring.

Sizing

Inline in step (campaign.py):

• In: vote tier (STRONG ≥2 votes → $100, else LEAN → $50), heat, per-asset record.
• Process: anti-martingale heat concurrency (_heat_slots); warm/cold ladder (_asset_perf → cold = ½ size + 1-of-3 cadence; warm = ×1.3, strong = ×1.6, capped below the ×2 reserved for a validated edge); cond_record learned fade (½ on a proven-losing condition@regime).
• Out: the dollar size_usd for the position.

Stops & exits

• Calibrated TP/SL (_tp_sl_mult) — per-asset ATR multipliers measured from realized excursions (MFE/MAE; the fixed 2.5× TP was reached only 0–21% of the time). Fallback 2.5×/1.8× ATR.
• Trailing (campaign.py) — trend-follow/edge trades ratchet a chandelier stop toward price.
• near-TP fee-guard (NEARTP, campaign.py) — locks an ≥80%-to-TP gain only if it clears the round-trip cost (a sub-fee "win" is never booked).
• STALL (campaign.py) — a non-edge trade not following through (gross < 0.3%) by 2h is cut.
• TIME (campaign.py) — the dynamic horizon cap (_dynamic_horizon): 3h fade / 4h trend / 24h validated edge.
• In: live mark + the position. Out: an exit reason ∈ {TP, SL, TRAIL, NEARTP, STALL, TIME} + net PnL (net of 20 bps round-trip).

Execution

_exec_open / _exec_close · campaign.py

• In: an approved position + the BITGET_EXECUTE flag.
• Process: LONG / SHORT on Bitget demo futures (BITGET_EXECUTE=1, bitget_adapter.py, API v3). Orders go to the Bitget Demo account: bitget_adapter sends the paptrading header while BITGET_DEMO=1 (the default). Paper is the source of truth; demo fills are proof-of-execution.
• Out: venue + exec_qty on the position (or paper-only if geo-blocked / disabled).

Learning (floor side)

• cond_record (campaign.py) — every close updates a (condition@regime) record that steers future sizing; a losing round benches its conditions with a TTL (failed_conditions).
• _asset_perf (campaign.py) — per-asset realized record drives the warm/cold ladder + bench.
• shadow-score (campaign.py) — each abstained setup is logged and judged at its horizon against real price: was the gate right (would-be loss) or wrong (would-be win)? Surfaced as shadow_learning.
• tp_sl_calibration (tp_calibration.py, data/tp_sl_calibration.json) — re-measures reachable TP/SL from accumulated trades.

---

See also

• Architecture — the 3-phase loop + the entry-quality pipeline visualised.
• The Firm Machinery — the merge and the non-desk roles in prose.
• The Desks — each desk's own deep-dive page.
• API Reference — where each component's output surfaces as an endpoint.