Metadata-Version: 2.4
Name: graphite-engine
Version: 0.3.0
Summary: Open-source claim verification engine for high-stakes decisions
Author: Min Jun Kim
License: Apache-2.0
Project-URL: Homepage, https://github.com/graf-research/graphite
Project-URL: Documentation, https://github.com/graf-research/graphite#readme
Project-URL: Repository, https://github.com/graf-research/graphite
Project-URL: Issues, https://github.com/graf-research/graphite/issues
Keywords: verification,claims,evidence,provenance,trust,graph
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
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 :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: networkx>=3.0
Requires-Dist: pydantic>=2.0
Provides-Extra: neo4j
Requires-Dist: neo4j>=5.0; extra == "neo4j"
Provides-Extra: llm
Requires-Dist: google-genai>=1.0; extra == "llm"
Provides-Extra: pdf
Requires-Dist: pdfplumber>=0.9; extra == "pdf"
Provides-Extra: geo
Requires-Dist: rasterio>=1.3; extra == "geo"
Requires-Dist: numpy>=1.24; extra == "geo"
Provides-Extra: all
Requires-Dist: graphite-engine[geo,llm,neo4j,pdf]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: python-dotenv>=1.0; extra == "dev"
Dynamic: license-file

<div align="center">
  <h1>⛏️ Graphite</h1>
  <p><strong>Open-source claim verification engine for high-stakes decisions.</strong></p>
  <p>Turn documents into structured claims with provenance, then verify whether downstream assertions are actually grounded in evidence.</p>
  <p>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License"></a>
    <a href="https://python.org"><img src="https://img.shields.io/badge/python-3.10%2B-brightgreen.svg" alt="Python"></a>
  </p>
</div>

> ⚠️ **v0.3.x — Experimental**. Usable and tested, but API may change before 1.0. Pin your version.

---

### 10 lines to your first verified claim

```python
from graphite import Claim, ClaimStore, ClaimType, Provenance
from graphite.enums import SourceType, ConfidenceLevel

# 1. Extract a claim from a document
claim = Claim(
    subject_entities=["company:TSMC"],
    predicate="SUPPLIES_TO",
    object_entities=["company:NVDA"],
    claim_text="TSMC supplies advanced CoWoS packaging to Nvidia.",
    claim_type=ClaimType.RELATIONSHIP,
    supporting_evidence=[Provenance(
        source_id="tsmc-10k-2024",
        source_type=SourceType.SEC_10K,
        evidence_quote="The Company provides advanced packaging services including CoWoS.",
        confidence=ConfidenceLevel.HIGH,
    )],
)

# 2. Persist to a claim registry
store = ClaimStore(db_path="/tmp/demo.db")
store.save_claim(claim)

# 3. Query: does anyone supply to Nvidia?
results = store.search_claims(object_contains="NVDA")
for c in results:
    print(f"{c.claim_text}  [{c.supporting_evidence[0].source_id}]")
```

Every claim is traceable: **source, quote, confidence**. No black-box assertions.

> See [`examples/quickstart_verification/`](examples/quickstart_verification/) for a fully runnable example.

---

### Quickstart

```bash
pip install graphite-engine
```

Or from source:

```bash
git clone https://github.com/graf-research/graphite.git
cd graphite
pip install -e .
python examples/quickstart_verification/run.py
```

No database. No LLM. No API keys. Start local, stay local.

---

## Why Graphite?

Graphite is built for domains where being wrong is expensive: financial research, regulatory compliance, infrastructure risk.

| Problem | Most tools | Graphite |
|---------|-----------|----------|
| **Unverifiable claims** | Assertions without audit trail | Every claim carries `Provenance`: source, quote, confidence |
| **No trust scoring** | Binary pass/fail | Explainable `ConfidenceScorer` with named factors |
| **Opaque pipelines** | Fragile chains, no persistence | `ClaimStore` with SQLite-backed registry + search |

### Core primitives

| Primitive | What it does |
|-----------|-------------|
| `Claim` | The atomic unit of trust — structured assertion with provenance |
| `ClaimStore` | SQLite-backed registry for persisting and querying claims |
| `Provenance` | First-class evidence source: document, quote, confidence |
| `ConfidenceScorer` | Explainable confidence scoring with named factors |
| `BaseFetcher` / `BaseExtractor` | Plugin interface for domain-specific extraction |

### What belongs where

| Graphite (engine) | Your application |
|---|---|
| Claim schemas & enums | Domain-specific extractors |
| Claim registry (ClaimStore) | Extraction prompts & calibration |
| Confidence scoring | Verification logic |
| Plugin interfaces (Fetcher, Extractor) | UI, API, alerts |

---

## Also included: graph assembly & propagation

Graphite also provides graph assembly and shock propagation for supply chain analysis:

```python
from graphite import GraphAssembler, top_k_paths_from_source, build_blast_radius

edges = my_extractor.extract(documents)
G = GraphAssembler().assemble(edges)

paths, _ = top_k_paths_from_source(G, source="country:CD", max_hops=3, k=3)
blast = build_blast_radius(paths, k=3)
```

See [`examples/toy_battery_demo/`](examples/toy_battery_demo/) and [`examples/flood_replay_demo/`](examples/flood_replay_demo/) for end-to-end examples.

---

## Built with Graphite: EdgarOS

**EdgarOS** is the first commercial application built on Graphite — a verification engine for AI-generated financial research memos against SEC evidence.

![EdgarOS — verification results with grounding levels and evidence status](docs/edgaros.png)

- 📄 **Claim verification** — every memo claim graded against SEC filings
- 🔍 **Two-axis verdicts** — grounding level + evidence conflict detection
- ⚖️ **Explainable scoring** — provenance-traced confidence with reason codes

> Building on Graphite? [Open an issue](https://github.com/graf-research/graphite/issues) to get featured.

---

## Benchmark

In EdgarOS benchmark runs built on Graphite primitives:

| Metric | Score |
|--------|-------|
| Conservative Precision | 90.5% |
| Weakest-Link Top-1 Accuracy | 69.0% |
| False Contradiction Rate | 0.0% |
| Neutral Precision | 91.7% |

<sup>100 synthetic memos, 320 claims, evaluated against gold-labeled verdicts. Full methodology and eval harness in the EdgarOS repo.</sup>

---

## Optional extras

**Core** (always included): `networkx` + `pydantic`

```bash
pip install -e ".[llm]"     # Gemini structured extraction
pip install -e ".[neo4j]"   # Neo4j graph storage
pip install -e ".[pdf]"     # PDF parsing
pip install -e ".[all]"     # Everything
```

---

## License

Apache-2.0 — see [LICENSE](LICENSE).
