pea-audit 0.1.0__tar.gz

pea_audit-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+# Secrets — ne jamais committer
+.env
+
+# Caches d'audit (verdicts + PDFs téléchargés)
+cache/
+
+# Eval PDFs téléchargés (re-téléchargeables depuis les URLs des cases)
+evals/data/
+
+# Artefacts de test
+*.pdf
+!samples/*.pdf
+*.png
+
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Build artifacts
+dist/
+build/
+
+# macOS
+.DS_Store
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Playwright traces
+.playwright-mcp/
+
+# User's real portfolio (template lives in positions.csv.example)
+positions.csv

pea_audit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrey Kanmegne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pea_audit-0.1.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: pea-audit
+Version: 0.1.0
+Summary: Audit PEA-eligibility of ETF KID documents with a vision LLM. French PEA (Plan d'Épargne en Actions) rules built in.
+Project-URL: Homepage, https://github.com/AndreLiar/pea-audit
+Project-URL: Repository, https://github.com/AndreLiar/pea-audit
+Project-URL: Issues, https://github.com/AndreLiar/pea-audit/issues
+Project-URL: Changelog, https://github.com/AndreLiar/pea-audit/blob/main/CHANGELOG.md
+Author: Andrey Kanmegne
+License: MIT License
+        
+        Copyright (c) 2026 Andrey Kanmegne
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: audit,etf,finance,gemma,kid,llm,ollama,pea,priips
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: French
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: ollama>=0.4.0
+Requires-Dist: pypdfium2>=4.30.0
+Requires-Dist: requests>=2.30
+Requires-Dist: tenacity>=9.0
+Provides-Extra: dev
+Requires-Dist: langfuse>=4.0; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Provides-Extra: evals
+Requires-Dist: pyyaml>=6.0; extra == 'evals'
+Provides-Extra: observability
+Requires-Dist: langfuse>=4.0; extra == 'observability'
+Description-Content-Type: text/markdown
+
+# pea-audit
+
+[![PyPI](https://img.shields.io/pypi/v/pea-audit.svg)](https://pypi.org/project/pea-audit/)
+[![Python](https://img.shields.io/pypi/pyversions/pea-audit.svg)](https://pypi.org/project/pea-audit/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Audit French **PEA** (Plan d'Épargne en Actions) eligibility of ETFs by reading their **KID** (Key Information Document) with a vision LLM. Tells you whether a fund is actually eligible for a French PEA account — with verbatim citations from the document.
+
+```
+$ python audit_cli.py samples/amundi_pea_monde_kid.pdf
+📄 Audit de : samples/amundi_pea_monde_kid.pdf
+
+  ✅ ÉLIGIBLE PEA    (confiance : high)
+
+  Émetteur     : Amundi
+  ISIN         : FR001400U5Q4
+  Indice       : MSCI World Index EUR
+  Réplication  : synthetic_swap
+
+  Le fonds est éligible au PEA car il utilise une réplication synthétique
+  via swap (IFT) avec un panier d'actions européennes ≥75%.
+
+  Preuves :
+    p.1 — « Le Fonds est éligible au Plan d'Épargne en Actions français (PEA) ... »
+    p.1 — « La performance sera échangée contre celle de l'Indice de Référence ... »
+```
+
+## Why
+
+PEA eligibility is opaque and *changes silently* — issuers re-domicile, swap counterparties, switch to ESG-screened variants, and rename funds (e.g. Amundi PEA Nasdaq-100 silently became "Amundi PEA US Tech Screened" under the same ticker). Brokers don't always flag this. `pea-audit` reads each fund's KID directly and tells you what the document actually says, with quotes you can verify.
+
+## Install
+
+```bash
+pip install pea-audit
+```
+
+Optional extras:
+
+```bash
+pip install 'pea-audit[observability]'  # adds Langfuse for LLM tracing
+pip install 'pea-audit[evals]'           # adds pyyaml for the eval suite
+pip install 'pea-audit[dev]'             # everything above + python-dotenv
+```
+
+## Quickstart
+
+```python
+from pathlib import Path
+from pea_audit import audit_pdf, VerdictCache
+from pea_audit.llm import OllamaCloudClient
+
+# Default backend: Ollama Cloud running Gemma 4 31b
+llm = OllamaCloudClient(api_key="sk-...")  # from https://ollama.com/settings/keys
+
+# Cache is opt-in. Library never writes to disk unless you supply one.
+cache = VerdictCache(Path("./cache"))
+
+verdict = audit_pdf("path/to/kid.pdf", llm=llm, cache=cache)
+
+print(verdict.eligible)        # "yes" | "no" | "uncertain"
+print(verdict.replication)     # "physical" | "synthetic_swap" | "unknown"
+print(verdict.isin)            # deterministic — extracted from PDF text + Luhn-validated
+for c in verdict.evidence:
+    print(f"  p.{c.page}: « {c.quote} »")
+```
+
+### Audit by ticker (built-in URL registry)
+
+```python
+from pea_audit import audit_ticker, VerdictCache
+from pea_audit.llm import OllamaCloudClient
+
+llm = OllamaCloudClient(api_key="sk-...")
+cache = VerdictCache(Path("./cache"))
+
+result = audit_ticker("EWLD.PA", llm=llm, kid_dir=Path("./kids"), cache=cache)
+print(result.verdict.eligible)  # "yes"
+```
+
+Built-ins ship for the most common French ETFs (Amundi PEA range, BNP Paribas Easy). Add more:
+
+```python
+from pea_audit.sources import register_source, KIDSource
+
+register_source(KIDSource(
+    ticker="LYX.PA",
+    isin="FR0010411884",
+    url="https://www.lyxoretf.fr/.../kid.pdf",
+    issuer="Lyxor",
+))
+```
+
+## Architecture
+
+Two protocols make this library extensible without forking:
+
+### `VisionLLM` — swap the model
+
+```python
+from typing import Any, Protocol
+
+class VisionLLM(Protocol):
+    def analyze_images(
+        self,
+        images: list[bytes],
+        prompt: str,
+        schema: dict[str, Any],
+        system: str | None = None,
+    ) -> dict[str, Any]: ...
+```
+
+The default `OllamaCloudClient` wraps Gemma 4 via Ollama Cloud with `tenacity` retries on transient errors and optional Langfuse tracing. Anyone can implement this protocol to plug in Claude vision, GPT-4o, Gemini, a local Ollama instance, etc.
+
+### `KIDSource` — add issuers
+
+```python
+from pea_audit.sources import register_source, KIDSource, get_source, all_sources
+```
+
+A registry of ticker → KID URL mappings. Ships builtins for Amundi (URL pattern), BNP Paribas (per-fund UUIDs); URL helpers for BlackRock/iShares + Vanguard are importable but don't auto-register (most of their funds are PEA-ineligible — they're for testing the negative path).
+
+## Eval baseline
+
+The repo ships **13 regression cases** under `evals/cases/*.yaml` — 7 PEA-eligible synthetic-swap, 6 ineligible physical non-EEA — covering Amundi, BNP, BlackRock/iShares, Vanguard. Current baseline on Gemma 4 31b-cloud: **13/13 (100%)**. Run before any prompt or model change:
+
+```bash
+python evals/run.py
+```
+
+## Production niceties
+
+- **Retries on transient errors** — `tenacity` with exponential backoff (1s → 4s → 16s), only on network/timeout/5xx (not on 4xx or schema errors that won't self-resolve)
+- **Optional observability** — Langfuse traces per LLM call (model, input/output, tokens, latency). Activates when `LANGFUSE_PUBLIC_KEY`/`LANGFUSE_SECRET_KEY` are set, silent no-op otherwise
+- **Deterministic ISINs** — vision misreads of the 12-char ISIN string are corrected by regex-extracting candidates from the PDF text layer and validating with the Luhn check digit
+- **Versioned prompts** — `pea_audit/prompts/audit_v{N}.md` files, selected via `prompt_version=` parameter; rollback is a config change, not a code edit
+- **Hard vs soft fields in diffs** — `compare_verdicts()` defaults to comparing only categorical fields (`eligible`, `replication`, `isin`) so monthly re-audit doesn't false-fire on LLM rephrasing of free-text issuer/index names
+
+## Reference app: ETFTracker
+
+The repo also ships a personal-tool app that consumes the library: a French ETF portfolio tracker with a Streamlit dashboard, monthly re-audit cron, FastAPI service, and Docker compose deployment. See `ETFTracker.md` (French) for that side.
+
+To run it: `cp positions.csv.example positions.csv`, edit with your own holdings, `cp .env.example .env` with your Ollama key, then `docker compose up -d web` or `streamlit run dashboard.py`.
+
+## Publishing checklist (maintainer)
+
+PyPI publication uses [trusted publishers](https://docs.pypi.org/trusted-publishers/) (OIDC) — no API token secret needed in CI.
+
+One-time setup:
+
+1. Create the project on https://pypi.org (or first on https://test.pypi.org for a dry-run)
+2. Add a Trusted Publisher pointing to `release.yml` in this repo, environment `pypi`
+3. In GitHub repo settings, create the `pypi` environment (no secrets needed)
+
+Per-release:
+
+```bash
+# 1. Update version in pyproject.toml + add entry to CHANGELOG.md
+# 2. Verify it builds + tests pass
+python -m build
+pytest tests/
+
+# 3. Tag and push — CI takes over
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The `release.yml` workflow builds the wheel + sdist and publishes to PyPI automatically on tag push.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE).
+
+## Disclaimer
+
+This is a personal-finance tool. The LLM-judged eligibility verdict is informational, not regulatory advice — always cross-check against the actual DIC/KID before buying.

pea_audit-0.1.0/README.md

@@ -0,0 +1,180 @@
+# pea-audit
+
+[![PyPI](https://img.shields.io/pypi/v/pea-audit.svg)](https://pypi.org/project/pea-audit/)
+[![Python](https://img.shields.io/pypi/pyversions/pea-audit.svg)](https://pypi.org/project/pea-audit/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Audit French **PEA** (Plan d'Épargne en Actions) eligibility of ETFs by reading their **KID** (Key Information Document) with a vision LLM. Tells you whether a fund is actually eligible for a French PEA account — with verbatim citations from the document.
+
+```
+$ python audit_cli.py samples/amundi_pea_monde_kid.pdf
+📄 Audit de : samples/amundi_pea_monde_kid.pdf
+
+  ✅ ÉLIGIBLE PEA    (confiance : high)
+
+  Émetteur     : Amundi
+  ISIN         : FR001400U5Q4
+  Indice       : MSCI World Index EUR
+  Réplication  : synthetic_swap
+
+  Le fonds est éligible au PEA car il utilise une réplication synthétique
+  via swap (IFT) avec un panier d'actions européennes ≥75%.
+
+  Preuves :
+    p.1 — « Le Fonds est éligible au Plan d'Épargne en Actions français (PEA) ... »
+    p.1 — « La performance sera échangée contre celle de l'Indice de Référence ... »
+```
+
+## Why
+
+PEA eligibility is opaque and *changes silently* — issuers re-domicile, swap counterparties, switch to ESG-screened variants, and rename funds (e.g. Amundi PEA Nasdaq-100 silently became "Amundi PEA US Tech Screened" under the same ticker). Brokers don't always flag this. `pea-audit` reads each fund's KID directly and tells you what the document actually says, with quotes you can verify.
+
+## Install
+
+```bash
+pip install pea-audit
+```
+
+Optional extras:
+
+```bash
+pip install 'pea-audit[observability]'  # adds Langfuse for LLM tracing
+pip install 'pea-audit[evals]'           # adds pyyaml for the eval suite
+pip install 'pea-audit[dev]'             # everything above + python-dotenv
+```
+
+## Quickstart
+
+```python
+from pathlib import Path
+from pea_audit import audit_pdf, VerdictCache
+from pea_audit.llm import OllamaCloudClient
+
+# Default backend: Ollama Cloud running Gemma 4 31b
+llm = OllamaCloudClient(api_key="sk-...")  # from https://ollama.com/settings/keys
+
+# Cache is opt-in. Library never writes to disk unless you supply one.
+cache = VerdictCache(Path("./cache"))
+
+verdict = audit_pdf("path/to/kid.pdf", llm=llm, cache=cache)
+
+print(verdict.eligible)        # "yes" | "no" | "uncertain"
+print(verdict.replication)     # "physical" | "synthetic_swap" | "unknown"
+print(verdict.isin)            # deterministic — extracted from PDF text + Luhn-validated
+for c in verdict.evidence:
+    print(f"  p.{c.page}: « {c.quote} »")
+```
+
+### Audit by ticker (built-in URL registry)
+
+```python
+from pea_audit import audit_ticker, VerdictCache
+from pea_audit.llm import OllamaCloudClient
+
+llm = OllamaCloudClient(api_key="sk-...")
+cache = VerdictCache(Path("./cache"))
+
+result = audit_ticker("EWLD.PA", llm=llm, kid_dir=Path("./kids"), cache=cache)
+print(result.verdict.eligible)  # "yes"
+```
+
+Built-ins ship for the most common French ETFs (Amundi PEA range, BNP Paribas Easy). Add more:
+
+```python
+from pea_audit.sources import register_source, KIDSource
+
+register_source(KIDSource(
+    ticker="LYX.PA",
+    isin="FR0010411884",
+    url="https://www.lyxoretf.fr/.../kid.pdf",
+    issuer="Lyxor",
+))
+```
+
+## Architecture
+
+Two protocols make this library extensible without forking:
+
+### `VisionLLM` — swap the model
+
+```python
+from typing import Any, Protocol
+
+class VisionLLM(Protocol):
+    def analyze_images(
+        self,
+        images: list[bytes],
+        prompt: str,
+        schema: dict[str, Any],
+        system: str | None = None,
+    ) -> dict[str, Any]: ...
+```
+
+The default `OllamaCloudClient` wraps Gemma 4 via Ollama Cloud with `tenacity` retries on transient errors and optional Langfuse tracing. Anyone can implement this protocol to plug in Claude vision, GPT-4o, Gemini, a local Ollama instance, etc.
+
+### `KIDSource` — add issuers
+
+```python
+from pea_audit.sources import register_source, KIDSource, get_source, all_sources
+```
+
+A registry of ticker → KID URL mappings. Ships builtins for Amundi (URL pattern), BNP Paribas (per-fund UUIDs); URL helpers for BlackRock/iShares + Vanguard are importable but don't auto-register (most of their funds are PEA-ineligible — they're for testing the negative path).
+
+## Eval baseline
+
+The repo ships **13 regression cases** under `evals/cases/*.yaml` — 7 PEA-eligible synthetic-swap, 6 ineligible physical non-EEA — covering Amundi, BNP, BlackRock/iShares, Vanguard. Current baseline on Gemma 4 31b-cloud: **13/13 (100%)**. Run before any prompt or model change:
+
+```bash
+python evals/run.py
+```
+
+## Production niceties
+
+- **Retries on transient errors** — `tenacity` with exponential backoff (1s → 4s → 16s), only on network/timeout/5xx (not on 4xx or schema errors that won't self-resolve)
+- **Optional observability** — Langfuse traces per LLM call (model, input/output, tokens, latency). Activates when `LANGFUSE_PUBLIC_KEY`/`LANGFUSE_SECRET_KEY` are set, silent no-op otherwise
+- **Deterministic ISINs** — vision misreads of the 12-char ISIN string are corrected by regex-extracting candidates from the PDF text layer and validating with the Luhn check digit
+- **Versioned prompts** — `pea_audit/prompts/audit_v{N}.md` files, selected via `prompt_version=` parameter; rollback is a config change, not a code edit
+- **Hard vs soft fields in diffs** — `compare_verdicts()` defaults to comparing only categorical fields (`eligible`, `replication`, `isin`) so monthly re-audit doesn't false-fire on LLM rephrasing of free-text issuer/index names
+
+## Reference app: ETFTracker
+
+The repo also ships a personal-tool app that consumes the library: a French ETF portfolio tracker with a Streamlit dashboard, monthly re-audit cron, FastAPI service, and Docker compose deployment. See `ETFTracker.md` (French) for that side.
+
+To run it: `cp positions.csv.example positions.csv`, edit with your own holdings, `cp .env.example .env` with your Ollama key, then `docker compose up -d web` or `streamlit run dashboard.py`.
+
+## Publishing checklist (maintainer)
+
+PyPI publication uses [trusted publishers](https://docs.pypi.org/trusted-publishers/) (OIDC) — no API token secret needed in CI.
+
+One-time setup:
+
+1. Create the project on https://pypi.org (or first on https://test.pypi.org for a dry-run)
+2. Add a Trusted Publisher pointing to `release.yml` in this repo, environment `pypi`
+3. In GitHub repo settings, create the `pypi` environment (no secrets needed)
+
+Per-release:
+
+```bash
+# 1. Update version in pyproject.toml + add entry to CHANGELOG.md
+# 2. Verify it builds + tests pass
+python -m build
+pytest tests/
+
+# 3. Tag and push — CI takes over
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The `release.yml` workflow builds the wheel + sdist and publishes to PyPI automatically on tag push.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE).
+
+## Disclaimer
+
+This is a personal-finance tool. The LLM-judged eligibility verdict is informational, not regulatory advice — always cross-check against the actual DIC/KID before buying.

pea_audit-0.1.0/pea_audit/__init__.py

@@ -0,0 +1,56 @@
+"""pea-audit — PEA-eligibility auditor for ETF KID documents.
+
+Audits ETF KID/DIC PDFs against French PEA (Plan d'Épargne en Actions)
+rules using a vision LLM. Ships with pluggable LLM backends, a registry
+of KID source URLs by ticker, versioned prompts, and a 13-case regression
+eval suite.
+
+Quickstart:
+    from pathlib import Path
+    from pea_audit import audit_pdf, VerdictCache
+    from pea_audit.llm import OllamaCloudClient
+
+    llm = OllamaCloudClient(api_key="sk-...")
+    cache = VerdictCache(Path("./cache"))
+
+    verdict = audit_pdf("kid.pdf", llm=llm, cache=cache)
+    print(verdict.eligible, verdict.replication, verdict.isin)
+"""
+
+from .cache import VerdictCache
+from .compare import HARD_FIELDS, SOFT_FIELDS, compare_verdicts
+from .core import (
+    DEFAULT_PROMPT_VERSION,
+    PEA_VERDICT_SCHEMA,
+    Citation,
+    PeaVerdict,
+    audit_pdf,
+)
+from .isin import extract_isins, isin_check_digit_valid
+from .ticker import TickerAuditResult, audit_ticker, get_cached_verdict
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # Core audit
+    "audit_pdf",
+    "audit_ticker",
+    "get_cached_verdict",
+    # Dataclasses
+    "PeaVerdict",
+    "Citation",
+    "TickerAuditResult",
+    # Cache
+    "VerdictCache",
+    # Comparison (for re-audit cron)
+    "compare_verdicts",
+    "HARD_FIELDS",
+    "SOFT_FIELDS",
+    # Schema (for advanced users with custom LLMs)
+    "PEA_VERDICT_SCHEMA",
+    "DEFAULT_PROMPT_VERSION",
+    # ISIN helpers
+    "extract_isins",
+    "isin_check_digit_valid",
+]

pea_audit-0.1.0/pea_audit/cache.py

@@ -0,0 +1,55 @@
+"""Opt-in file-based verdict cache.
+
+The library NEVER writes to disk unless the app explicitly passes a
+`VerdictCache(cache_dir=...)`. Keyed by sha256(pdf_bytes), so the same
+PDF returned from anywhere yields the same cache hit.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict
+from pathlib import Path
+
+from .core import Citation, PeaVerdict
+
+
+class VerdictCache:
+    """File-based cache for `PeaVerdict`, keyed by sha256(pdf_bytes)[:16].
+
+    Example:
+        >>> cache = VerdictCache(Path("./cache/audits"))
+        >>> v = audit_pdf("doc.pdf", llm=client, cache=cache)
+        >>> # next call with the same PDF returns instantly, no LLM hit.
+    """
+
+    def __init__(self, cache_dir: Path):
+        self._dir = Path(cache_dir)
+
+    @staticmethod
+    def cache_key(pdf_bytes: bytes) -> str:
+        return hashlib.sha256(pdf_bytes).hexdigest()[:16]
+
+    def _path(self, key: str) -> Path:
+        return self._dir / f"{key}.json"
+
+    def get(self, pdf_bytes: bytes) -> PeaVerdict | None:
+        f = self._path(self.cache_key(pdf_bytes))
+        if not f.exists():
+            return None
+        data = json.loads(f.read_text())
+        data["evidence"] = [Citation(**c) for c in data.get("evidence", [])]
+        return PeaVerdict(**data)
+
+    def put(self, pdf_bytes: bytes, verdict: PeaVerdict) -> None:
+        self._dir.mkdir(parents=True, exist_ok=True)
+        self._path(self.cache_key(pdf_bytes)).write_text(
+            json.dumps(asdict(verdict), ensure_ascii=False, indent=2)
+        )
+
+    def get_by_path(self, pdf_path: Path) -> PeaVerdict | None:
+        """Convenience: load by PDF file path (for badge lookups)."""
+        if not pdf_path.exists():
+            return None
+        return self.get(pdf_path.read_bytes())

pea_audit-0.1.0/pea_audit/compare.py

@@ -0,0 +1,33 @@
+"""Verdict comparison — for re-audit cron / change detection."""
+
+from __future__ import annotations
+
+from .core import PeaVerdict
+
+# Hard fields — categorical / deterministic, safe to diff across LLM runs.
+HARD_FIELDS = ("eligible", "replication", "isin")
+
+# Soft fields — free-text rendered by the LLM, drifts between runs
+# ("BNP Paribas" vs "BNP Paribas Asset Management"). Ignored by default.
+SOFT_FIELDS = ("issuer", "underlying_index")
+
+
+def compare_verdicts(
+    old: PeaVerdict,
+    new: PeaVerdict,
+    include_soft: bool = False,
+) -> list[str]:
+    """Return human-readable diffs between two verdicts.
+
+    By default compares only the hard fields. `include_soft=True` also
+    diffs `issuer` and `underlying_index` (useful for debugging, but
+    noisy in a recurring cron).
+    """
+    fields = HARD_FIELDS + (SOFT_FIELDS if include_soft else ())
+    diffs: list[str] = []
+    for field_name in fields:
+        old_val = getattr(old, field_name)
+        new_val = getattr(new, field_name)
+        if old_val != new_val:
+            diffs.append(f"{field_name}: {old_val!r} → {new_val!r}")
+    return diffs