How the system actually works, and the choices behind it.

Each adapter implements the same Protocol — applies_to(slug, data_dir) and load(slug, data_dir) → (Contribution[], IngestionRecord) — and contributes typed leaves into the merge layer. Crunchbase first because it’s the densest, then LinkedIn (Bright Data API), Dealroom, Tavily news search, Owler, Greenhouse / Lever / Workable for hiring, Trustpilot, and a Firecrawl adapter for arbitrary marketing pages.

The adapters never write to the Profile directly: they emit Contribution objects with a field_path (dotted, e.g. funding.rounds[]) and a Cited[T] payload. The merge layer is responsible for picking conflicts apart — adapters stay dumb.

Every leaf in the Profile Pydantic model is one of three shapes:

• Cited[T] — a single observation with value, source, confidence, and an optional note.
• Conflict[T] — two or more sources disagree on the same fact. The conflict is preserved with both candidates and both sources, not silently resolved.
• None — the fact was never observed. The downstream specialist sees this as a gap, not a zero.

Pydantic 2’s PEP 695 generics (type aliases) give us this without a wrapper hierarchy: the JSON shape of every leaf is self-describing.

Before the specialists run, an LLM inspects the assembled profile and emits a GapFillPlan — a ranked list of URLs to scrape, each tagged with a gap_name (team / competitors / revenue / funding / customers / news / hiring / market / product / tech / other).

Firecrawl fetches each target, the GapFillAdapter surfaces the markdown as sentiment.signals tagged with [gap:<name>], and a small routing map decides which specialist sees which note: team → team, competitors → market + competitive, revenue / funding → financial + traction, and so on. The same enrichment notes also go to the devil’s advocate, unrouted, so the bear case has the full set to mine.

Each specialist — team, market, product, traction, competitive, financial — receives a sliced view of the profile plus its routed enrichment notes, and returns an AgentResult with score (1–5), confidence, reasoning, evidence citations, and risks.

LangGraph fan-out runs all six in parallel. Each agent is wrapped in @observe_or_noop so the trace tree shows six sibling spans, each containing the underlying chat-completion generation. Specialists never see one another — disagreement is allowed and gets preserved through to synthesis.

The overall score is Σ weight_i × score_i across the six specialists, with weights tuned for a growth fund (traction and team count more than tech). The recommendation banding is a pure switch over that score plus a confidence floor — no LLM picks the verdict.

The LLM is only invoked to draft the bull thesis proseafter the score is already decided. Two systems, two responsibilities: deterministic math gets the number, the model gets the words.

The final stage takes the bull thesis, the six specialist verdicts, and the full set of enrichment notes, and argues the strongest case for the deal failing — heroic assumptions, weakest dimensions, red flags pulled from data conspicuously not in the specialist outputs, and an adjusted recommendation. It can lower the verdict (interested → watchlist) or refuse to judge (insufficient_data) where the bull was speculating.

Without enrichment notes the bear had nothing concrete to mine — every bear case devolved into “there’s no recent funding info.” Wiring all_enrichments(profile) into the prompt sharpened it visibly: the Mews bear now cites specific layoff articles, the Hugging Face bear points at concrete acquihires, etc.

Each company analysis produces one trace with the following tree, all under session_id = <slug> so a click on “mews” in the Langfuse UI shows the whole pipeline plus any chat-bar follow-ups against the same session:

Generations under each LLM-calling span are populated automatically by langfuse.openai.OpenAI, which we swap in for the standard OpenAI client when Langfuse is enabled. That single line of glue gives us model name, prompt / completion text, usage tokens, latency, and temperature — all per generation, all in the same trace as the surrounding span.

After run_analysis_graph invokes the LangGraph state, we read back synthesis_result and devils_advocate_result and attach to the trace:

• tags = ["bull:watchlist", "bear:pass", "confidence:medium"]
• metadata = { overall_score, bull_recommendation, bear_recommendation, bear_red_flag_count, slug }
• session_id = the company slug

Once those are attached the Langfuse UI becomes browsable: filter by bear=insufficient_data to find every company where the bear refused to commit, or by confidence:low to find the thinnest cases. The trace name (analysis:<slug>) makes the trace list scannable.

After the trace finishes, the precompute script calls fetch_trace_stats(trace_id): it flushes Langfuse, retries the public API with a short backoff (the SDK ingests asynchronously), and aggregates the observations into a small dict — generation count, prompt + completion tokens, total cost, wall-clock latency, models used. That dict is stored alongside the analysis in Supabase, so the home page can render a stats banner without making any runtime call to Langfuse.

The retry matters: a fresh trace is typically queryable within 1–3 seconds, but if you query too eagerly you get a 404. Three retries at 2-second intervals turned out to be generous enough for every slug in the dataset.

The chat-bar on each analysis page is server-rendered via /api/chat — a Next.js Route Handler. That endpoint wraps the LLM call in a Langfuse trace (chat:<slug> under the same session_id) and returns the trace_id alongside the answer. Two buttons under each answer (👍 / 👎) post to /api/feedback, which calls langfuse.score(name="user_feedback", value=…) against that exact trace.

Inside run_analysis_graph we capture client.get_current_trace_id() immediately after invoking LangGraph, compose the public URL ($LANGFUSE_HOST/trace/$ID), and persist both into the cached payload. The analysis page renders a discreet link in the sticky verdict bar — so an interviewer can click any company and see the full trace tree behind it without leaving the browser tab they started in.