# AI Benchmark Provenance & Leak-Rating Registry

## PURPOSE
A SQLAlchemy + httpx service that stores AI hardware performance claims together with the
two things the video insists on tracking: **provenance** (is a number a vendor claim, a
measurement with a published method, or someone's math from a spec sheet?) and a
**source rating** (confirmed, credible, possible, or single source — the exact labels the
presenter applies to Medusa Halo leaks). It ingests claims from configured sources over
httpx, normalizes them, and exposes them with their trust metadata attached.

## WHY THIS MATTERS
The transcript repeatedly warns that numbers without provenance mislead: AMD shows a 34x
ComfyUI chart against an M5 Pro that could not run some tests; Micro Center is the only
seller of the box it benchmarked; the GMK Evo X5 Pro was forecast near $2,500 and lists at
$6,799. A registry that forces every figure to carry "where did this come from" is the
engineering answer to that editorial warning.

## HOW TO BUILD
Define two SQLAlchemy models — `Source` (name, kind, reliability) and `Claim` (metric,
value, unit, provenance, source_id, captured_at) — then an httpx async fetcher that pulls
raw source pages and a normalizer that tags each extracted figure. Key relationship:

```python
class Claim(Base):
    __tablename__ = "claims"
    id = Column(Integer, primary_key=True)
    metric = Column(String, nullable=False)          # e.g. "gen_tps"
    value = Column(Float, nullable=False)
    provenance = Column(String, nullable=False)      # vendor|measurement|calculation
    source_id = Column(ForeignKey("sources.id"))
    source = relationship("Source", back_populates="claims")
```

Expose create/query endpoints and a `GET /claims?provenance=measurement` filter.

## WHEN TO USE IN PRODUCTION
Use it whenever an org publishes or consumes hardware benchmarks: an internal leaderboard,
a procurement review, or a research tracker that must not repeat a vendor's cherry-picked
rival. Use the source-rating field to quarantine single-source rumors until corroborated.
Do NOT use it as a benchmark runner — it stores and labels claims, it does not measure.
Do NOT ingest third-party pages without respecting their terms and rate limits.

## HOW IT HELPS STUDENTS
Students learn ORM modelling, foreign keys and provenance as first-class schema, async HTTP
fetching with httpx, and the discipline of never storing a number without its source.

## STARTER CODE
See `starter/main.py`: SQLAlchemy models, an httpx async fetcher with a deterministic stub,
an ingest function, and query helpers, plus `# TODO` markers for parsers and auth.
