WRITEUP.md

# Amplegest — Product and Technical Write-up

Amplegest is a post-earnings decision memo for portfolio managers and senior equity analysts. It compresses filings, transcripts, structured financials, and public news into a fast first-pass review while preserving a route back to the evidence.

The product objective is not “summarise the quarter.” It is to answer four investment-process questions:

1. What changed relative to the prior thesis?
2. Which evidence confirms or challenges that thesis?
3. What is the swing factor for the next estimate revision?
4. Which observable metric, threshold, or event should be monitored next?

Amplegest does not issue a buy/sell recommendation or a price target.

---

## 1. Decision experience

The interface follows the order in which an experienced investor reviews a print.

### 1.1 PM Flash

PM Flash is the one-screen decision memo:

- **As-of and coverage** — company, ticker, filing date, and available source types.
- **PM read-through** — a concise synthesis labelled **AI · experimental**.
- **Thesis-confirming / thesis-challenging** — the highest-impact source-backed points on each side.
- **Swing factor** — the most material analytical tension or between-the-lines hypothesis, explicitly experimental and linked to the evidence layer.
- **What to watch** — the next catalysts, metrics, thresholds, or periods that can validate or invalidate the read.

The screen is deliberately sparse. Detailed cards, search, before/after text, and full evidence belong in Evidence & Deltas.

### 1.2 Evidence & Deltas

Evidence & Deltas is the audit surface. It combines source-backed claims, risk changes, management commentary, period comparisons, and experimental interpretations in one ranked feed.

The feed uses three distinct labels:

- **Source-backed fact** — traceable to a filing, transcript, or news excerpt.
- **Heuristic · validate** — a deterministic detector output whose underlying text or calculation must be reviewed.
- **AI · experimental** — a model-generated synthesis or interpretation that must be tested against cited evidence.

This separation prevents a language-shift detector or a plausible narrative from being mistaken for a reported financial fact.

### 1.3 Financials

Financials provides the historical depth behind the memo: KPI series, profitability, cash and capital allocation, balance-sheet trends, guidance history, and earnings history. It is the modelling support surface, not a second executive summary.

### 1.4 Ask Evidence

Ask Evidence is a secondary, grounded Q&A utility. It is useful after the investor has identified a question in PM Flash or Evidence & Deltas. It is intentionally outside the primary decision sequence so an open-ended chat does not replace systematic review.

---

## 2. Workflow

Amplegest separates ingestion from on-demand analysis.

### 2.1 Offline ingestion

Run after a new release:

    python ingest.py TICKER

- SEC EDGAR XBRL → SQLite structured metrics.
- 10-K/10-Q sections → chunking, embeddings, and Chroma filing storage.
- Earnings-call transcripts → a separate Chroma transcript collection.
- Period metadata travels with each record so retrieval can be scoped to the relevant filing or comparison period.

### 2.2 Runtime graph

The LangGraph flow is:

    agent → tools (bounded loop) → synthesis → post_synthesis → presentation policy

- The first round anchors the run in structured financial metrics and available analyst data.
- Filing and transcript retrieval are coverage requirements, with a one-time nudge if the agent attempts to stop before consulting both.
- Retrieval over-fetches Chroma candidates and reranks them with a cross-encoder.
- Synthesis is a separate model call that emits a validated **BriefOutput** object.
- Post-synthesis code applies deterministic reliability rules and adds rule-based period deltas.
- The presentation policy suppresses unaligned aggregate and market-derived outputs.

LangSmith records the graph nodes, tool calls, retrieved context, and model invocations for operational review.

---

## 3. Source and evidence hierarchy

The intended source ladder is:

1. **10-K / 10-Q** for reported financials, accounting disclosures, and official risk language.
2. **Transcript** for management framing, prepared remarks, and Q&A.
3. **News** for events occurring after the filing or call.

Every **SourcedFact** carries one source type and a short verbatim evidence excerpt. The factual claim may be composed during synthesis, but the excerpt gives the reviewer a direct verification path.

News cannot substitute for a primary filing when the primary document exists. If the evidence set is incomplete, the system should state the coverage gap rather than silently increase confidence.

---

## 4. Item-level reliability

Reliability is recomputed after synthesis; the model does not control the final label.

Default item-level grades:

- 10-K / 10-Q → HIGH;
- transcript → MEDIUM;
- news → LOW.

Deterministic adjustments include:

1. downgrade generic Risk Factors language;
2. downgrade stale news;
3. uplift a transcript or news claim when a sufficiently similar claim is corroborated by a different source;
4. flag lone-news claims without filing or transcript confirmation;
5. record reliability adjustments in evidence notes;
6. remove analytical tensions that merely duplicate existing thesis points.

These labels describe the strength and provenance of a specific evidence item. They are not a calibrated truth probability. Amplegest therefore keeps item-level source and reliability metadata but masks any global HIGH / MEDIUM / LOW roll-up or percentage.

---

## 5. Analytical layer

The analytical layer is useful only when its epistemic status is visible.

### Source-backed claims

**what_changed**, bull/bear points, risks, management commentary, and other **SourcedFact** fields are presented with their source and evidence excerpt.

### Heuristic deltas

**quarter_deltas** are computed by deterministic detectors over two periods. Examples include:

- added, removed, or reworded risk language;
- term-frequency changes;
- guidance-language shifts;
- dropped KPIs;
- repeated Q&A evasion patterns;
- management-tone or topic trajectories.

The before/after text and computed metric are inspectable. The classification and significance remain heuristic, so the UI labels them **Heuristic · validate**.

### Experimental AI hypotheses

The following are interpretations, not reported facts:

- **what_matters_most**;
- **non_obvious_takeaway**;
- **analytical_tensions**;
- **between_the_lines**;
- **earnings_quality_signals**.

Where displayed, they are labelled **AI · experimental**. PM Flash uses the most material tension or tell as a Swing Factor, not as a conclusion. The reviewer is directed to validate the hypothesis against Evidence & Deltas.

An empty tension set is valid and preferable to a manufactured insight.

---

## 6. Fail-closed market-data policy

Stored data and displayed data are different contracts. Amplegest may retain **sentiment** and **market_expectations** in the brief for later validation, but the PM-facing presentation does not show them unless alignment is explicit.

The following remain hidden by default:

- aggregate sentiment;
- aggregate HIGH / MEDIUM / LOW reliability distributions or percentages;
- D1 / D5 event returns;
- actual-versus-consensus comparisons.

Required preconditions before any future display:

| Output | Required alignment |
| --- | --- |
| Actual vs consensus | Same fiscal period, metric definition, accounting basis, units, and currency; estimate timestamp precedes the release. |
| D1 / D5 | Exact earnings-release timestamp, after-hours/pre-market status, exchange calendar, timezone, and unambiguous session anchors. |
| Aggregate sentiment | Documented section coverage, calibrated weights, stability tests, and a defined decision use. |
| Aggregate reliability | Documented aggregation method that does not turn source provenance into a false confidence score. |

The gate is fail-closed: a missing flag, ambiguous period, or uncertain timestamp means **do not render**. A plausible value is not sufficient.

---

## 7. What to improve next

### 7.1 Period identity and market alignment

- Key XBRL observations by accession, end date, duration, fiscal period, and form rather than accession alone.
- Align consensus explicitly to the reported fiscal quarter and metric basis.
- Anchor price reactions to the release timestamp and the correct market session.

### 7.2 Evidence locators

- Persist accession, filing section, document URL, transcript speaker, and chunk identifier with every claim.
- Make each evidence excerpt deep-linkable to its source context.

### 7.3 Financial-quality coverage

- Ingest financial statements and footnotes for working capital, stock-based compensation, tax normality, and GAAP/non-GAAP reconciliation.
- Add speaker diarisation to separate prepared remarks from Q&A and identify repeated non-answers.

### 7.4 PM workflow

- Structure watch items as metric + threshold + period + source.
- Add portfolio-level change monitoring and cross-name comparison.
- Schedule ingestion immediately after earnings and cache briefs by **(ticker, filing_date)**.

The priority order is data identity first, evidence navigation second, and additional analytical breadth third.