ten31-signal-engine/AGENTS.md

Ten31 Signal Engine — AGENTS.md

Inbox check: At session start, if ~/Projects/standards/INBOX.md exists, scan it for items tagged (ten31-signal-engine) and surface them before proposing next steps; triage with /triage.

A recurring pipeline that ingests a growing corpus of audio (podcasts, YouTube) and text (SEC filings, earnings calls, policy/lender/research docs), extracts structured propositions ("claims"), and surfaces signal over time through Ten31's investment thesis as a relevance lens — logging every surfaced signal as a falsifiable prediction scored against reality.

Source of truth (in order): ten31-signal-engine-handoff.md (the spec — wins on any conflict; §refs point into it) › DESIGN_v2.md (the living decision/falsification log — read before changing scoring) › this file's Current state. README.md is the user-facing intro.

The spine — NON-NEGOTIABLE guardrails (never violate)

1. Nominate-then-judge. Statistics & graph structure NOMINATE candidates; the frontier model only JUDGES / FANS OUT a pre-filtered shortlist. The frontier never nominates from the raw corpus.
2. Propositions, not vibes. Extract atomic claims; separate topic from stance.
3. Discount convergence by connectedness. Independence is earned, not counted — the EISC graph (source edges + voiceprints) downweights echo. Bitcoin is one capped cluster: within-cluster agreement can NOT masquerade as independent corroboration; cross-cluster earns the multiplier.
4. Thesis is a LENS, not a gate on truth. The engine must surface signals against Ten31's thesis, not just for it.
5. Dual-evaluation ledger from day one — precision AND recall; every signal is a logged prediction.
6. ~95% local compute via Spark Control. Call the gateway's HTTP endpoints; do NOT stand up your own vLLM / Whisper / Qdrant. Gemini is an explicit overflow lever for PUBLIC data only.
7. Sovereignty boundary (hard). Exposure/positioning/conviction data and the Strike/Battery investment memos NEVER go to the frontier. Route sensitive frontier calls through /scrub → frontier → /rehydrate (scrub identities, not substance). Read the memos LOCALLY only.

Two jobs: A — Discovery (emergent themes via independent cross-cluster convergence scored on acceleration; contrarian stances; their intersection). B — Conviction-action gap (fan held convictions to 2nd/3rd-order derivatives, catch early corroboration — the countermeasure to the 2023 "power is the binding constraint on AI/compute" miss: right on the root, late to the derivatives).

Architecture

signal_engine/ (Python package, run as python -m signal_engine <cmd>):

• config.py — env-driven Config (+ .env loader). spark/client.py — the SINGLE gateway chokepoint (no other module knows the gateway URL); scrub/rehydrate live here.
• ingest/ — edgar (SEC), earnings (FMP REST), feeds+podcasts (RSS), download, chunker, transcribe_worker (local Parakeet), gemini_transcribe (bulk overflow), docs (HTML/PDF/RSS text fetcher for policy/lender/research), identify, speaker_stitch.
• extract/ — claims+worker (proposition extraction), backends (LocalQwen | Gemini), prompt, html_text. embedstore/ — embedder + qdrant_store (hybrid dense+BM25).
• signals/ (the scoring brain) — independence (EISC), asof (look-ahead guard), windows, under_acted (Job B), bar (two-tier gate), two_sided (affirms−denies net-corroboration), llm_helpers (derivative_relevance), confusion (precision/recall), external (price/outcome fetcher), ledger_writer (§6.6 prediction ledger), resolver (stub), run.
• store/ — db (SQLite + idempotent migrations), schema.sql, seed, sources. backfill/queue.py (the job queue). ui/app.py (FastAPI corpus/eval UI). util.py.
• Data lands in data/ (gitignored): signal.db, transcripts/, docs/, audio-cache/.

Flow: seed sources/convictions/fanout → ingest (→ documents + transcribe/extract jobs) → run-transcribe / run-extract drain the queue → claims → embed-claims (Qdrant) → scorers (backtest, two-sided) read the proposition store as-of a date.

Build / run

• Setup: virtualenv at .venv (Python 3.14). .venv/bin/pip install -r requirements.txt.
• Invoke: .venv/bin/python -m signal_engine <cmd>. --help is authoritative; the rest is a map: init-db; seeding seed-sources/seed-convictions/seed-fanout/seed-edges/load-feeds; ingest ingest-edgar/ingest-earnings/ingest-podcast/ingest-doc/ingest-doc-manifest/ ingest-feed-text; queue drain run-transcribe/run-transcribe-gemini/run-extract; index embed-claims/search; score backtest/two-sided/confusion-matrix; inspect queue-status/ spark-status/feed-peek/provenance/db-tables; serve (UI).
• DB: python -m signal_engine init-db (idempotent — re-creates schema + runs additive migrations).
• Tests: ⚠️ no automated test suite yet (no tests/, no pytest). Verification is by running commands against the live gateway. Adding a test harness is on the ROADMAP.
• Lint/format: none configured. Match the surrounding style (dense, §-referenced docstrings).

Spark Control infra (SPARK_CONTROL_URL, self-signed TLS → SPARK_VERIFY_TLS=false)

One gateway fronts two DGX Sparks: vLLM RedHatAI/Qwen3.6-35B-A3B-NVFP4 on :103; Parakeet ASR + diarizer, bge-m3 embeddings, Qdrant on :87. The gateway is the only URL anything calls.

• AUDIO concurrency (learned 2026-06-09): single serial GPU shared with the operator's production meeting app. Cap 2 in-flight (ceiling 3), GLOBAL across both audio endpoints — a process-wide BoundedSemaphore (AUDIO_CONCURRENCY env, default 2). Going wider buys zero throughput. Transient 1–4s "busy blips" (broken-pipe/503/timeout) are NOT failures → short retry-backoff. The transcribe_worker runs a 2-wide chunk pool; the old size-1 lock was ~2.5× slower.

Key operational rules (learned this build — easy to get wrong)

• own_network quarantine is MATERIALITY-driven, not "any investment." Quarantine (drop in live scoring, keep in test) only for MATERIAL ties where the source is part of Ten31's voice: the partners' own shows (TFTC, Citadel Dispatch, Rabbit Hole Recap), the Battery partnership, material portfolio leads. Immaterial passive stakes → INDEPENDENT (River and Swan/Cafe Bitcoin were corrected to independent). Unconfirmed: Unchained, Debifi, Coinkite (held quarantined pending Grant's materiality call).
• Gemini quota is a rolling ~24h window (~291 hour-long episodes / ~51M tokens), not a calendar-day reset. Bulk transcription overflows there; expect 429 RESOURCE_EXHAUSTED past the window.
• Transcript chunking is recall-first and MUST cap every chunk. ASR transcripts have NO blank-line paragraphs (speaker turns joined by a single \n), so extract.claims.chunk_text falls through \n\n→\n→sentence→word→hard-slice; splitting only on \n\n (the old bug) sent whole 2–3 h episodes in ONE call → context-overflow 400s. Extraction defaults to full coverage at 12K chars/chunk (run-extract --chunk-chars/--max-chunks); bigger chunks risk lost-in-the-middle recall loss.
• Gemini extraction backend: disable thinking AND set a timeout. gemini-2.5-flash thinks by default and burns the output-token budget on reasoning → MAX_TOKENS → truncated JSON → 0 claims, so the backend sets thinking_budget=0 (mirrors local enable_thinking=False). It also sets an HTTP timeout (120 s) + 4 retries — a timeout-less call once hung the single-threaded worker ~50 min (transient 504/read-timeouts then self-heal). Gemini = overflow for PUBLIC data only; keep EXTRACTION_BACKEND=local in .env, flip it inline per-run when overflowing.
• Scoring-brain internals are scoped to a guide. Before editing signal_engine/signals/, read docs/guides/scoring-brain.md — the classifier invariants (REALIZED-ONLY, ROLE-MATCH, claim_type hard-evidence guard, max_tokens budget, claim_id bracket-strip), the EISC cluster-cap, and the Battery/Strike adversarial-test PASS criteria. Don't regress those invariants (they're what make Battery pass). Full decision log: DESIGN_v2.md.

Secrets / env

Real values live in .env (gitignored). .env.example lists the names. Keys used: SPARK_CONTROL_URL, SPARK_VERIFY_TLS, LOCAL_LLM_MODEL, EMBED_MODEL, TRANSCRIBE_MODEL, AUDIO_CONCURRENCY, EXTRACTION_BACKEND, GEMINI_API_KEY, GEMINI_MODEL, ANTHROPIC_API_KEY, FMP_API_KEY, EDGAR_USER_AGENT, DATA_DIR, UI_PORT, LOG_LEVEL. Never commit key values; the private LAN gateway IP appears only as an env-var default.

Current state (snapshot — overwrite each session; longer-term backlog → ROADMAP.md)

• Strike adversarial test: extraction ~complete — this is the gating step. Chunker 400 bug FIXED (old \n\n-only split sent whole 2–3 h episodes in one call → context overflow); extraction is now recall-first full coverage (12K chars). Drained the ~700-doc backlog via the Gemini backend (one-time PUBLIC overflow), hardened with thinking-off + 120 s timeout/4 retries after a timeout-less call hung the worker ~50 min. At session end ~68 docs left (the SEC/FMP filings tail); 52.7k claims in the DB, 0 failures, 3 transient timeouts. NEXT once extraction finishes: embed-claims → two-sided --conviction STRIKE2022 --modes live,test (PASS = quiet in live, fires in test).
• If extraction stopped early (session ended): resume with EXTRACTION_BACKEND=gemini run-extract --limit 800 (drop the env var for the local Qwen path). Pending claims still need embed-claims after.
• Battery test PASSES; §7.1 power-infra qualified YES (both unchanged).
• 3 commits local + backends.py uncommitted (Gemini timeout/retry) — ALL UNPUSHED. Push to main is blocked by the permission classifier; run git push origin main (your updated rule allows main).
• Corpus: bitcoin podcasts, SEC/FMP filings (+banks cluster), Battery corpus, River research; EISC edges seeded for the bitcoin cluster.