README.md

---
title: Amplegest
emoji: 📊
colorFrom: green
colorTo: gray
sdk: streamlit
sdk_version: 1.49.1
app_file: app.py
pinned: false
---

# Amplegest — Post-Earnings Decision Intelligence

Amplegest turns public-company disclosures into a compact, evidence-linked decision memo for portfolio managers and senior equity analysts.

The product is designed for the first review after an earnings release: what changed, what confirms or challenges the thesis, which variable can swing the next estimate revision, and what must be monitored next. It does not issue a buy/sell recommendation or a price target.

## Decision stack

| Surface | Role in the workflow |
| --- | --- |
| **Company Overview** | Concise company onboarding: business model, revenue engines, geographic exposure, three-year evolution, investor-attention themes, relative price events, recent news, and the variables to watch. |
| **PM Flash** | One-screen decision memo: filing date and source coverage, experimental AI read-through, thesis-confirming and thesis-challenging evidence, the swing factor, and the next items to watch. |
| **Evidence & Deltas** | Audit layer: source-backed claims, before/after evidence, heuristic period deltas, risks, management commentary, and experimental AI hypotheses. |
| **Financials** | Historical KPI trends, guidance history, earnings history, and exportable structured data. |
| **Ask AI** | Cross-cutting utility for grounded follow-up questions. It supports the review; it is not the investment conclusion. |

## Evidence contract

Amplegest deliberately separates three different output classes:

| Output class | Meaning | UI treatment |
| --- | --- | --- |
| **Source-backed fact** | A factual claim tied to a 10-K, 10-Q, transcript, or news excerpt. | Source, period, item-level reliability, and evidence remain inspectable. |
| **Heuristic delta** | A deterministic before/after computation produced by a rule-based detector, such as a new risk phrase, dropped KPI, or language shift. The inputs are evidence; the detector's significance is a heuristic. | Labelled **Heuristic · validate** and shown with the underlying comparison. |
| **Experimental AI hypothesis** | A synthesis or interpretation, including the PM read-through, analytical tensions, between-the-lines reads, and earnings-quality assessments. | Labelled **AI · experimental** and presented as a question to validate against cited evidence. |

Item-level reliability metadata describes source provenance and corroboration. The UI renders it as plain-language confidence, not as a HIGH / MEDIUM / LOW portfolio score, and never promotes it into a conviction indicator.

## Fail-closed presentation policy

Amplegest does not display a market-derived output merely because a payload contains a value. The presentation layer hides the following by default:

- aggregate sentiment;
- any aggregate HIGH / MEDIUM / LOW reliability roll-up or percentage;
- D1 / D5 post-earnings returns;
- actual-versus-consensus comparisons.

These outputs remain hidden until their required alignment is explicit and testable: the same fiscal period and metric definition for actuals and consensus, the exact release timestamp and trading session for event returns, and a documented calibration methodology for aggregate scores. Missing or uncertain alignment means **do not render**.

This policy does not remove item-level source tags, evidence excerpts, or reliability labels from source-backed claims.
Legacy briefs without a deterministic `evidence_coverage` result are shown as **Legacy / unverified**; the presence of a 10-K, 10-Q, or transcript tag alone never upgrades them to verified.

## Architecture

- **Offline ingestion** — SEC EDGAR XBRL into SQLite; 10-K/10-Q Business, Segments/Geography, MD&A, Risk Factors, and earnings-call transcripts into the evidence stores.
- **Company Overview** — deterministic filing/call retrieval is injected before the agent loop; the source-fingerprinted English overview is emitted and verified within the brief's single synthesis call, while prices and public news refresh independently at display time.
- **Runtime agent** — a LangGraph tool loop retrieves structured financials, filings, transcripts, public news, and analyst data before one synthesis call produces the validated Pydantic brief and Company Overview.
- **Retrieval** — vector search over-fetches candidates and reranks them with a cross-encoder.
- **Post-synthesis controls** — deterministic source-reliability rules, corroboration checks, and heuristic period-delta detectors run after model synthesis.
- **Decision UI** — Company Overview onboards; PM Flash frames the decision; Evidence & Deltas provides auditability; Financials provides depth; Ask AI is the final cross-cutting tool.

See [WRITEUP.md](WRITEUP.md) for product and methodology detail and [ARCHITECTURE.md](ARCHITECTURE.md) for data lineage and presentation controls.

## Run locally

```bash
pip install -r requirements.txt
cp .env.example .env
python ingest.py AAPL --full
streamlit run app.py
```

Set the required API keys in `.env` first. A full re-ingestion is required for
databases created before the evidence-lineage upgrade: legacy vector chunks and
metrics without verified period context are intentionally hidden rather than
silently upgraded.

For an already lineage-compatible database, `python ingest.py AAPL` is enough
to backfill the Company Overview’s 10-K Business and Segments/Geography sections;
the delta path reuses any transcript already stored.

### Deploy to the Hugging Face Space

The Space serves the committed `data/` snapshot through Git LFS. After any local
ingestion, commit `data/`, then run `python deploy_check.py`; only run
`git push hf main:main` when the preflight passes. Space runtime storage is
ephemeral, so runtime-written caches and saved briefs do not survive a restart.

## Intended use

Amplegest is a research accelerator based on public information. It helps an experienced investor review evidence faster, challenge a thesis, and identify the next falsifiable datapoint. The analyst or portfolio manager retains responsibility for source verification, modelling, valuation, and the investment decision.