ARCHITECTURE.md

Amplegest — Architecture

Render the diagram in VS Code with Mermaid support or paste it into mermaid.live.

Amplegest separates data collection, retrieval, synthesis, deterministic controls, and presentation. The target user is a portfolio manager or senior equity analyst reviewing a post-earnings change in thesis.

---
title: Amplegest — Post-Earnings Decision Architecture
---
flowchart TB
    classDef ext   fill:#f3e8ff,stroke:#9333ea,color:#581c87
    classDef store fill:#dcfce7,stroke:#16a34a,color:#14532d
    classDef warm  fill:#fed7aa,stroke:#ea580c,color:#7c2d12
    classDef proc  fill:#fef9c3,stroke:#ca8a04,color:#78350f
    classDef state fill:#fde68a,stroke:#b45309,color:#78350f
    classDef rag   fill:#e9d5ff,stroke:#7c3aed,color:#3b0764
    classDef io    fill:#fce7f3,stroke:#db2777,color:#831843
    classDef gate  fill:#fee2e2,stroke:#dc2626,color:#7f1d1d

    USER([PM / senior equity analyst]):::io --> UI["Streamlit research stack<br/>Company Overview · PM Flash · Evidence & Deltas · Financials · Ask AI"]:::io
    UI --> PE

    subgraph LG ["LangGraph · short-term state"]
        direction LR
        PE["profile_evidence<br/>deterministic evidence.v1 retrieval"]:::state
        AG["agent<br/>Claude Haiku 4.5"]:::state
        TN["tools<br/>parallel execution"]:::state
        ND["coverage nudge · once<br/>if filing + transcript<br/>were not both searched"]:::state
        SY["synthesis<br/>validated BriefOutput"]:::state
        PS["post_synthesis<br/>item reliability + deltas"]:::state
        PE --> AG
        AG == "tool calls · bounded rounds" ==> TN
        TN == "ToolMessage" ==> AG
        AG -. "coverage floor" .-> ND -.-> AG
        AG -- "done or cap" --> SY --> PS
    end

    PS --> GATE["Presentation policy<br/>alignment required<br/>missing or uncertain = hidden"]:::gate
    GATE --> UI
    LSM{{LangSmith}}:::ext -. "trace" .- LG

    TN <--> TOOLS

    subgraph TOOLS ["Runtime tools · RAG + SQL + public data"]
        direction TB
        T1["get_financial_metrics"]:::proc
        T2["search_filing"]:::proc
        T3["search_transcript"]:::proc
        T4["search_news"]:::proc
        T5["get_analyst_expectations"]:::proc

        subgraph RAG ["Filing and transcript retrieval"]
            direction LR
            QE["embed query<br/>MiniLM-L6-v2"]:::rag
            VS["Chroma similarity<br/>5× over-fetch"]:::rag
            RR["cross-encoder reranker<br/>bge-reranker-base"]:::rag
            QE --> VS --> RR
        end

        T2 --> QE
        T3 --> QE
    end

    subgraph WARM ["Warm tier · 24-hour TTL"]
        AVC[(av_cache · SQLite)]:::warm
    end

    AVL{{Alpha Vantage}}:::ext --> AVC
    YF{{yfinance}}:::ext --> AVC
    AVC --> T5

    subgraph LTM ["Long-term stores · offline ingestion"]
        direction LR
        EDG{{SEC EDGAR}}:::ext
        AVT{{Earnings-call transcript source}}:::ext
        EX["XBRL extractor<br/>structured metrics"]:::rag
        CK["chunker<br/>500 words · 50 overlap"]:::rag
        EM["embedder<br/>MiniLM-L6-v2"]:::rag
        MD["metadata<br/>ticker · period · section<br/>source · date · context"]:::rag
        DB[(SQLite metrics)]:::store
        CHF[(Chroma · filings)]:::store
        CHT[(Chroma · transcripts)]:::store

        EDG --> EX --> DB
        EDG --> CK
        AVT --> CK
        CK --> EM --> MD --> CHF
        MD --> CHT
    end

    DB  -- "filing data" --> T1
    CHF -- "10-K / 10-Q evidence" --> VS
    CHT -- "transcript evidence" --> VS
    TAV{{Tavily news}}:::ext -- "post-filing context" --> T4

search_filing and search_transcript over-fetch Chroma candidates, optionally filter by period, rerank the candidates, and return the best matches. News search is separate and does not inherit filing-level confidence.

Decision surfaces

Surface	Primary payload
Company Overview	Stable sourced company profile plus independently refreshed price context and public news. Business model, geographic exposure, three-year trends, attention themes, associated price events, and monitoring variables remain concise and inspectable.
PM Flash	As-of and coverage; experimental PM read-through; thesis-confirming/challenging sourced points; experimental Swing Factor; watch items.
Evidence & Deltas	Source-backed facts, verbatim evidence, deterministic detector outputs labelled heuristic, risks, commentary, and experimental AI hypotheses.
Financials	Structured historical metrics, trends, guidance history, earnings history, and exports.
Ask AI	Cross-cutting grounded Q&A over the available evidence.

The navigation order is intentional: company onboarding → decision memo → evidence audit → model depth → cross-cutting AI tool.

Company Overview

Company Overview is produced inside the same streaming synthesis call as the rest of the brief. Before the agent loop, a deterministic node retrieves the stable profile evidence set—10-K Business, segments/geography, strategic evolution, and transcripts—and injects each evidence.v1 envelope as a raw human message. Those messages do not satisfy the brief's tool-coverage gate, so the agent must still retrieve the current-quarter evidence required for the decision memo. After synthesis, the overview section is validated separately, passed through the unchanged deterministic evidence verifier, stripped of every non-verified fact, and saved under its source fingerprint. A profile failure is isolated and cannot fail the brief.

The former standalone call existed for three practical reasons: its source fingerprint made the profile stable between earnings; its evidence set was broader and more structural than the latest-quarter brief; and a separate response kept the main synthesis output smaller. The merged design deliberately accepts those trade-offs. Profile evidence is now injected deterministically before the agent loop, which adds only marginal context; the synthesis output limit is raised to 16,384 tokens; and fingerprint-based cache lookup remains in the UI, while a new overview is generated only with a new brief run. This means “Generate Brief” regenerates the overview each time, an acceptable marginal output-token cost in exchange for one billed synthesis call and one coherent evidence-grounded result.

Output taxonomy

Payload or derived field	Epistemic class	Presentation
what_changed	Source-backed factual claims	Evidence & Deltas
bull_points, bear_points	Source-backed factual claims	PM Flash as thesis-confirming/challenging; full evidence in Evidence & Deltas
risks_categorized, management_commentary	Source-backed factual claims	Evidence & Deltas
quarter_deltas	Deterministic detector output; significance is heuristic	Evidence & Deltas with Heuristic · validate
what_matters_most	Experimental AI synthesis	PM Flash with AI · experimental
analytical_tensions	Experimental two-sided hypothesis	PM Flash Swing Factor and Evidence & Deltas
between_the_lines	Experimental interpretation	Evidence & Deltas; may provide Swing Factor fallback
earnings_quality_signals	Experimental assessment	Evidence & Deltas
non_obvious_takeaway	Experimental interpretation	Retained in payload; never presented as a sourced fact
what_to_watch	Monitoring prompts	PM Flash
sentiment	Stored analytical payload	Hidden from PM-facing UI until calibrated
market_expectations	Stored market-data payload	Actual/consensus and D1/D5 hidden until aligned

Reliability contract

Every SourcedFact carries:

• one source in {10-K, 10-Q, transcript, news};
• an item-level reliability label;
• a short verbatim evidence_snippet.

Post-synthesis code rewrites item-level reliability using deterministic defaults and corroboration rules. This metadata helps the analyst decide what to verify first. It is not a calibrated probability and must not be aggregated into a global conviction indicator.

Consequently:

• item-level source and reliability stay visible;
• aggregate HIGH / MEDIUM / LOW distributions, percentages, or headline badges stay hidden.

Fail-closed alignment gate

The presentation layer treats every market-derived or aggregate field as unavailable until its prerequisites are proven.

Candidate output	Gate condition
Actual vs consensus	Same issuer, fiscal period, metric definition, accounting basis, units, currency, and pre-release estimate timestamp
D1 / D5 return	Exact release timestamp, timezone, market-session classification, exchange calendar, and deterministic price anchors
Aggregate sentiment	Sufficient section coverage, calibrated weights, stability testing, and a documented use
Aggregate HIGH / MEDIUM / LOW	A validated aggregation methodology that does not misrepresent source provenance as truth probability

The default is false. Missing metadata, an ambiguous period, or an uncertain event time prevents rendering. Raw values may remain in storage for validation; storage presence is never display permission.

The same rule applies to evidence coverage: Verified requires total > 0, verified == total, and the deterministic status VERIFIED. Older briefs without this summary are labelled Legacy / unverified, regardless of their source tags.

Known alignment priorities

1. XBRL observations must be selected by accession and period identity, including end date and duration.
2. Analyst estimates must be mapped to the same reported fiscal period and metric basis.
3. Event returns must account for after-hours and pre-market releases.
4. Evidence should carry a stable source locator: accession, section, URL, transcript speaker, and chunk identifier.

These controls precede portfolio-level scoring, comparative ranking, or additional AI interpretation.