Skip to content

trading-desk: add Company Profile analyst as 5th Phase 1 grounding agent (FIX-606) - #286

Merged
jhoffner merged 4 commits into
mainfrom
claude/fix-606-CJvXD
May 17, 2026
Merged

jhoffner merged 4 commits into
mainfrom
claude/fix-606-CJvXD

Conversation

@jhoffner

@jhoffner jhoffner commented May 17, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Adds a fifth Phase 1 analyst — Company Profile Analyst — to examples/trading-desk. It grounds the desk in what the underlying business actually is (name, sector, industry, business description, scale) using real provider data, so downstream phases reason from a data-derived profile rather than the model's training priors.

  • Renderer, not synthesizer. Fetches structured fields from Finnhub /stock/profile2 (preferred) + Yahoo quoteSummary (assetProfile + summaryDetail) and renders them. The prompt constrains the LLM to trace every body claim to a <data> field, with a "quote one figure verbatim" requirement as a structural defense against fabrication. The shared <grounding> clause from FIX-605 reinforces the boundary.
  • Honest unavailable handling. When both providers fail, the analyst emits a memo whose body explicitly states identity could not be resolved — never invents the company. Combines naturally with FIX-605's phase1AllErroredGuard.
  • No framework changes. All work scoped to examples/trading-desk/. Composes cleanly into the existing fan-out — downstream phases pick the memo up via the existing formatAnalystMemos flow.
  • Optional refactor taken. setupPhase1Memos now derives its memoStatus seed from PHASE_1_MEMO_KEYS so future analyst additions don't touch this file.

Implementation follows the attached spec (FIX-606: Company Profile Analyst — Implementation Spec) step-for-step.

Files

  • New: phase-1/tools/get_company_profile.ts, phase-1/tools/get_company_profile schema + empty payload, companyProfilePrompt, companyProfileGenerator + companyProfileAnalyst sub-sequencer.
  • New: services/finnhub.ts::fetchFinnhubCompanyProfile, services/yahoo.ts::fetchYahooCompanyProfile.
  • New: fixtures for NVDA, AAPL, JPM at 2026-05-06.
  • Wired into phase-1/index.ts .parallel (label updated to "5 analysts"), PHASE_GROUPS.p1, PHASE_1_MEMO_KEYS, PHASE_1_ANALYST_AGENTS (transcript), PUBLISH_ORDER (theses pane).
  • Docs: examples/trading-desk/README.md, apps/docs/guides/trading-desk-walkthrough.md, docs/internal/design/trading-desk.md, changelog.md.

Test plan

  • pnpm --filter @flow-state-dev/example-trading-desk typecheck — clean
  • pnpm --filter @flow-state-dev/example-trading-desk test — 91 passed (22 files)
  • pnpm typecheck (workspace) — clean
  • New test/get-company-profile.spec.ts covers fixture mode, missing-fixture error, Finnhub success, both-providers-unavailable, and schema-strictness of the empty payload.
  • test/setup.spec.ts updated to 5 pending memos.
  • test/session-resources-layout.spec.ts updated to expect 8 memo keys (was 7) and mock the new generator.
  • Manual fsdev run on NVDA fixture mode — not run in this environment; reviewer can verify locally per the spec's Step 12 verification list.

Fixes FIX-606.


Generated by Claude Code


Note

Medium Risk
Adds a new Phase 1 agent plus a new live/fixture data-fetch tool (Finnhub/Yahoo) and updates memo seeding/order, which could affect pipeline orchestration and run behavior despite being scoped to the example.

Overview
Adds a fifth Phase 1 analyst (companyProfileAnalyst) to the Trading Desk example that fetches and renders structured company identity/scale data into a new memos/p1/company-profile memo, and wires it into Phase 1 parallel fan-out, agent registries, and UI publish ordering.

Introduces a new get_company_profile tool with fixture support and a live fallback chain (Finnhub preferred, Yahoo fallback, then explicit unavailable payload) plus prompt constraints to keep the memo grounded in returned fields.

Updates fixtures, tests, and docs to reflect the extra analyst/memo, and refactors setupPhase1Memos to derive initial memoStatus keys from PHASE_1_MEMO_KEYS instead of hardcoding Phase 1 entries.

Reviewed by Cursor Bugbot for commit bda09df. Configure here.

Greptile Summary

Adds a fifth Phase 1 analyst (companyProfileAnalyst) to the Trading Desk example that fetches structured company identity/scale data from Finnhub and Yahoo, enriches it with homepage meta-description and web search snippets as fallbacks, and renders it into a new memos/p1/company-profile memo.

  • New get_company_profile tool runs Finnhub and Yahoo concurrently, merges fields with Finnhub preferred for identity/scale and Yahoo for sector/description, then falls back to web enrichment when both structured providers leave the description null; all three fallback steps fail-soft via Promise.allSettled.
  • setupPhase1Memos is refactored to derive its memoStatus seed from PHASE_1_MEMO_KEYS rather than a hardcoded list, so future analyst additions no longer require touching that file.
  • New companyProfileAnalyst is wired into the Phase 1 parallel fan-out, agent registry, and UI publish order; fixtures for NVDA/AAPL/JPM and a full test suite covering fixture, live, both-providers-fail, web-enrichment, and schema-validity paths are included.

Confidence Score: 5/5

Safe to merge — the new analyst composes cleanly into the existing fan-out pattern and all failure modes degrade gracefully.

The change is well-scoped to the trading-desk example. The provider fetch chain is wrapped in Promise.allSettled at every layer, so network failures or missing API keys never block the pipeline. The Yahoo name-field bug identified in a prior review is correctly resolved here. The setup refactor is a clean DRY improvement. Tests cover all key branches and use the correct testBlock API. No logic errors found in the merge, enrichment, or prompt wiring.

No files require special attention beyond the two minor comment corrections in services/web.ts.

Important Files Changed

Filename Overview
examples/trading-desk/src/flows/trading-desk/phase-1/tools/get_company_profile.ts New tool handler. Fixture/live branching, concurrent Finnhub+Yahoo fetch with field-level merge, and web-enrichment backstops — all wrapped in Promise.allSettled for fail-soft behavior. Logic is sound.
examples/trading-desk/src/flows/trading-desk/services/web.ts New file with homepage meta-description fetcher and web search helper. Two minor documentation inaccuracies (misleading JSDoc on searchCompanyWeb; misleading 'avoids buffering' comment) but functional behavior is correct.
examples/trading-desk/src/flows/trading-desk/services/finnhub.ts Adds fetchFinnhubCompanyProfile — fetches /stock/profile2, guards against missing name, and correctly converts marketCapitalization (USD millions) to absolute USD.
examples/trading-desk/src/flows/trading-desk/services/yahoo.ts Adds fetchYahooCompanyProfile with quoteType module for name/exchange, assetProfile for sector/industry/description, summaryDetail for marketCap. Correctly reads longName/shortName from qt (not profile).
examples/trading-desk/src/flows/trading-desk/phase-1/analysts.ts Adds companyProfileGenerator and companyProfileAnalyst sequencer following the same pattern as the four existing analysts.
examples/trading-desk/src/flows/trading-desk/phase-1/index.ts Wires companyProfileAnalyst into the Phase 1 parallel fan-out. maxConcurrency:4 with 5 branches was flagged in a prior review thread.
examples/trading-desk/src/flows/trading-desk/phase-1/setup.ts Refactors memoStatus seed to derive from PHASE_1_MEMO_KEYS — clean DRY improvement that prevents future additions from needing to touch this file.
examples/trading-desk/test/get-company-profile.spec.ts New test file. Uses testBlock throughout (AGENTS.md rule 4 compliant). Covers fixture mode, missing-fixture error, Finnhub live path, both-providers-fail path, meta-description enrichment, and empty-payload schema validity.
packages/tools/src/search/index.ts Re-exports resolveProvider from the internal resolver module, making it available to callers that need to run searches outside of the search() tool block.

Sequence Diagram

sequenceDiagram
    participant P1 as phase1Pipeline
    participant CP as companyProfileAnalyst
    participant Tool as get_company_profile
    participant FH as Finnhub /stock/profile2
    participant YH as Yahoo quoteSummary
    participant Web as fetchWebsiteMetaDescription
    participant Search as searchCompanyWeb
    participant Gen as companyProfileGenerator (LLM)
    participant Memo as memos/p1/company-profile

    P1->>CP: ".parallel({ companyProfile: companyProfileAnalyst })"
    CP->>Tool: execute(ticker, date)
    alt fixture mode
        Tool-->>CP: loadFixture("company-profile.json")
    else live mode
        Tool->>FH: fetchFinnhubCompanyProfile
        Tool->>YH: fetchYahooCompanyProfile
        Note over FH,YH: Promise.allSettled — both run concurrently
        FH-->>Tool: profile (or rejected)
        YH-->>Tool: profile (or rejected)
        alt both fail
            Tool-->>CP: emptyPayload (source: unavailable)
        else at least one succeeds
            Tool->>Tool: field-level merge (Finnhub preferred)
            Tool->>Web: fetchWebsiteMetaDescription(website)
            Tool->>Search: searchCompanyWeb(name)
            Note over Web,Search: Promise.allSettled — both fail-soft to null
            Web-->>Tool: "metaDescription | null"
            Search-->>Tool: "snippets[] | null"
            Tool-->>CP: enriched profile
        end
    end
    CP->>Gen: companyProfileGenerator(companyProfile)
    Gen-->>CP: thesis (title, body, rating, metrics)
    CP->>Memo: commitMemo(companyProfile)
Loading

Comments Outside Diff (1)

  1. changelog.md, line 75-81 (link)

    P2 Changelog bullet style: bold preamble labels

    AGENTS.md says "Lead each bullet with the fact, not bolded preamble. Bolded category labels at the start of every bullet are not [allowed]." All five new bullets open with a bold label (**Renderer, not synthesizer.**, **Provider chain reuses what's already wired:**, etc.). The older entries in the same file (e.g., 2026-04-11) lead directly with the fact as a plain sentence.

    Context Used: AGENTS.md (source)

    Fix in Cursor

Fix All in Cursor

Reviews (4): Last reviewed commit: "trading-desk: merge providers + web-enri..." | Re-trigger Greptile

…ent (FIX-606)

A renderer-style analyst that fetches structured business identity (name,
sector, industry, description, scale) from Finnhub /stock/profile2 +
Yahoo quoteSummary and renders it as a memo, so downstream phases reason
from data instead of training priors. The prompt constrains the LLM to
trace every claim to a `<data>` field and to quote one figure verbatim;
when no provider can resolve the ticker the memo explicitly says so
rather than inventing the company.

Runs in parallel with the existing four Phase 1 analysts; downstream
phases pick it up via the existing `formatAnalystMemos` flow (no
capability or formatter changes). `setupPhase1Memos` is refactored to
derive its memoStatus seed from `PHASE_1_MEMO_KEYS` so future analyst
additions don't have to touch this file.
@linear

linear Bot commented May 17, 2026

Copy link
Copy Markdown

FIX-606

@vercel

vercel Bot commented May 17, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
flow-state-dev-docs Ready Ready Preview, Comment May 17, 2026 7:39pm
flow-state-dev-kitchen-sink Ready Ready Preview, Comment May 17, 2026 7:39pm
flow-state-dev-ui Ready Ready Preview, Comment May 17, 2026 7:39pm

Request Review

technical: technicalAnalyst,
companyProfile: companyProfileAnalyst,
},
{ maxConcurrency: 4 },

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 maxConcurrency was not updated when the 5th analyst was added. With 5 branches and maxConcurrency: 4, the framework queues one analyst until another finishes — so they never all run simultaneously, directly contradicting the label "5 analysts dispatched in parallel."

Suggested change
{ maxConcurrency: 4 },
{ maxConcurrency: 5 },

Fix in Cursor

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit bda09df. Configure here.

sentiment: sentimentAnalyst,
news: newsAnalyst,
technical: technicalAnalyst,
companyProfile: companyProfileAnalyst,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maxConcurrency not updated for fifth parallel analyst

Medium Severity

maxConcurrency is still 4 but there are now 5 parallel analyst branches. The framework's mapWithConcurrency creates only min(limit, values.length) workers, so the fifth analyst (company profile) will be queued behind the first four instead of running concurrently. This contradicts the label on line 24 ("5 analysts dispatched in parallel") and adds unnecessary latency to every run, since the company profile fetch is the fastest of the five.

Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit bda09df. Configure here.

Replace `block.config.execute!` direct calls with `testBlock` from
`@flow-state-dev/testing` — the public test surface. The framework wraps
thrown `FixtureMissingError` in a `FlowError` whose message preserves
the original cause, so the missing-fixture assertion now checks message
content instead of the wrapped error class.

Copy link
Copy Markdown
Collaborator Author

Bot review triage:

maxConcurrency: 4 with 5 branches (Greptile P1, Cursor Bugbot): intentional per spec §3.7 — kept at 4 to stay under Finnhub free-tier headroom when each analyst internally fans out to ~3 provider calls (~15 concurrent at saturation). The spec calls it out: "One analyst waits briefly; total wall-clock impact is small. Changing to 5 is a one-line tweak that can be made later if profiling shows headroom." The container label "5 analysts dispatched in parallel" describes dispatch, not simultaneity — accurate but I can see how it reads as contradictory. Happy to tighten the label or bump the cap if you'd prefer; deferring to keep the spec's wording.

block.config.execute! in the new test (Greptile P2): valid AGENTS.md rule 4 violation — fixed in 5446a6e by switching to testBlock from @flow-state-dev/testing. The existing test/get-insider-transactions.spec.ts and test/finnhub-insider.spec.ts have the same pattern but pre-date this PR; out of scope to fix here.


Generated by Claude Code

sentiment: sentimentAnalyst,
news: newsAnalyst,
technical: technicalAnalyst,
companyProfile: companyProfileAnalyst,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maxConcurrency is set to 4 but there are 5 parallel analysts, causing one analyst to be queued instead of running in parallel as intended.

Fix on Vercel

`assetProfile` does not include `longName`/`shortName` — those live in
`quoteType`. As written the Yahoo fallback's name would always be null
and the function would always throw, silently making the fallback dead
code. Add `quoteType` to the modules list, read the name (and the
exchange, which `quoteType` does carry) from there. The spec's
mapping table was incorrect on this point.
Two changes that together solve "no business description" in live mode:

1. Provider merge. The chain was Finnhub-OR-Yahoo (whichever answered
   first). Finnhub almost always answers but doesn't carry sector or
   businessDescription — those fields stayed null even when Yahoo
   could have supplied them. Now both providers run via
   Promise.allSettled and we field-by-field merge: Finnhub wins where
   it has a value, Yahoo fills the gaps. Source tag reflects the
   primary identity contributor.

2. Web enrichment backstops. Two new schema fields populated in live
   mode after the provider merge:
     - websiteMetaDescription: the company's own homepage
       <meta name="description"> (or og:description, longer wins).
       Deterministic regex extraction, no LLM.
     - searchSnippets: top web-search results for the company name,
       via @flow-state-dev/tools/search's auto-detected provider
       (Tavily, Exa, Perplexity, Serper, Brave, Perplexity-Sonar).
   Both fail soft to null — missing search keys or an unreachable
   homepage never blocks the analyst.

The prompt is updated to teach the analyst about the new fields, the
inline source-attribution rule ("per the company's homepage", "per
Reuters", etc.), and that the verbatim-quote requirement can be
satisfied from any of the three description sources.

`resolveProvider` is now exported from `@flow-state-dev/tools/search`
so callers running a search inside another handler's execute don't
have to instantiate the search tool block (which would violate
AGENTS.md rule 4).

Fixtures gain the two new fields as null — the curated
businessDescription was already populated.

This branch was successfully deployed

3 active deployments
Preview – flow-state-dev-kitchen-sink — 26b9a0c0 Deployed May 17, 2026 by vercel[bot]
Preview – flow-state-dev-docs — 26b9a0c0 Deployed May 17, 2026 by vercel[bot]
Preview – flow-state-dev-ui — 26b9a0c0 Deployed May 17, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants