FastAPI + Next.js climate risk briefings with live SSE progress, citation-aware narratives, and resumable deliverables.
Transition Risk Scout delivers automated transition climate risk briefings by pairing a FastAPI research pipeline with a Next.js dashboard, letting portfolio teams request company-level reports and monitor progress in real time. The platform forms a retrieval-augmented generation loop that grounds every recommendation in sourced evidence, serving sustainability analysts who need auditable deliverables. Each assessment is timestamped and indexed under company slugs so teams can instantly rehydrate the latest report, and transparency stays front and center with live stage updates, evidence browsing, and citation-aware narratives built for governance-heavy workflows.
run_assessment orchestrates the full workflow end to end: LLM prompt generation, Tavily search, document ranking, markdown conversion, evidence extraction, and OpenAI report synthesis, emitting artifacts at every step. Search queries intentionally split between identity validation and transition themes to ground the analysis before deeper risk scoring. Parallel Tavily calls respect QPS limits and retry logic, flattening results into typed SearchResult objects for downstream scoring. URL-to-markdown conversion relies on a custom web crawler with PDF table extraction and polite throttling, reporting determinate progress for SSE consumers. Evidence routing maps markdown snippets into transition-specific buckets such as targets, capex alignment, and policy, reducing hallucinations while preserving source excerpts. Final deliverables include structured JSON, raw model output, consolidated evidence, and annotated search appendices written per run directory.
The home page manages the full lifecycle: validating inputs, kicking off SSE streams, caching previous results, and reloading the latest artifacts after each run for a seamless analyst flow. ProgressPanel distills the BuzzObserver feed into a four-stage stepper, determinate document conversion bar, and live ticker for rapid stakeholder updates. ReportCards renders model JSON into decision-ready cards with risk badges, program status chips, and citation jump links wired through SourceAwareText. Users can toggle between narrative, raw JSON, and markdown evidence tabs with guarded download controls for structured outputs. Local storage remembers the last company queried so analysts can resume or refresh reports without retyping context, while robust error handling restores prior results on stream failures and surfaces descriptive toasts for recoverable and fatal issues.
Prompting enforces ISSB/TCFD-aligned schema with anti-hallucination rules, mandatory citations, and explicit data-gap reporting. SourceAwareText parses [n] citations and links them to the sources table, making inline claims navigable and audit-friendly. Evidence extraction throttles per-field top-k snippets and trims excerpts to 650 characters, balancing richness with readability. Search appendices document every hit, including score, media type, and snippets, giving reviewers traceability into the discovery layer.
BuzzObserver standardizes progress events across stage, metric, ticker, artifact, and error so the same pipeline can serve CLI logs or SSE streams without branching logic. The SSE endpoint runs the assessment in a worker thread, heartbeats idle connections, and auto-terminates if the client disconnects. Latest-report endpoints expose report JSON and evidence markdown for any company slug, enabling the frontend's "Load latest" flow and external integrations. The custom web crawler cycles user agents, retries anti-bot codes, and gracefully falls back when HTML tooling is unavailable, keeping fetches stable across sources. Markdown fetchers and Tavily clients support configurable worker pools, timeouts, and politeness delays via environment variables for deployment tuning.
Transition Risk Scout now produces citation-rich transition risk assessments with live transparency, giving recruiters and stakeholders a polished story about shipping complex, trustworthy AI products. Natural follow-ups include exposing downloadable evidence and report artifacts once backend paths are secured, expanding input parameters (for example revenue context) to personalize prompts, and adding smoke tests around search and markdown stages to catch API regressions early.