Refract: deterministic observation engine for revision histories

Refract reveals how claims change across public revision histories — and gives AI researchers reproducible evidence for model evaluation.

npx @refract-org/cli analyze "Earth" --depth brief

Demo Quick start

Node.js 20+ or Bun 1.2+ · Git 2.x · Any MediaWiki instance

Refract reads a page's revision history and emits a typed event for each change it finds: sentences first seen, modified, removed or reintroduced; citations added, removed or replaced; template, link, category and section changes; reverts; talk page activity.

Features

Deterministic

The same revisions produce byte-identical events on every run. No model is called.

Provenance-tagged

Every event carries revision, section, timestamp, and analyzer identity.

BYO-inference boundaries

Every threshold is a configurable boundary. Plug a model where you need one; defaults run offline.

26 event types

Sentence lifecycles, citations, reverts, talk pages, protection levels, and edit clusters.

Hash-verifiable exports

Evidence bundles carry a SHA-256 hash and replay manifests a Merkle root, so a recipient can check that events were not altered.

MCP server

refract mcp serves six tools — analyze, claim, export, cron, classify and get_statement_history — to any MCP client over stdio.

Quick start

# 1. Analyze a page
npx @refract-org/cli analyze "Earth" --depth brief

# 2. Explore results in the web UI
refract explore "Earth"

# 3. Connect an AI agent
refract mcp

# 4. Export as structured data
refract export "Earth" --format ndjson > earth-events.jsonl

# 5. Save an evidence bundle (revisions, events and a SHA-256 hash)
refract export "Earth" --bundle > earth-bundle.json

# 6. Output an ObservationReport with claim lifecycle
refract analyze "Earth" --report > earth-report.json

What Refract is

Deterministic: The same input gives the same output.
Provenance-tagged: Identifies source revision, timestamp, and analyzer version.
Verifiable: Replay manifests carry a Merkle root over the event hashes.
Open layer: A raw observation feed designed for downstream processing.

What Refract is not

No model interpretation: Does not decide semantic meaning or intent.
No truth claims: Observes what changed, not which version is correct.
No editor profiles: Does not rank, grade, score, or track editors.
No policy judgments: Leaves decision relevance and rules to downstream tools.

By use case

Journalist / Researcher

Trace claim evolution and sources across revision history.

Demo → Quick start → Wikipedia history

Data scientist / OSINT

Extract NDJSON events and run columnar SQL analysis in DuckDB.

Python SDK → SDK reference → Notebooks

ML / RAG engineer

Score retrieved texts by stability and provenance quality indicators.

RAG provenance → Python SDK → BYO-inference

Policy / Compliance

Re-check pages on a schedule and send Slack, email or webhook notifications.

Monitoring → CLI cron → Citation churn

AI agent developer

Give agents Refract's tools through the built-in MCP server.

MCP tutorial → MCP reference → BYO-inference

AI model evaluator

Test for temporal leakage and recency cutoffs against revision histories.

Model evaluation → RAG provenance → Frontier use cases

Ecosystem

Refract is one tool in a family of three:

Tool	What it does	Install
Refract	CLI + TypeScript SDK — the deterministic observation engine	`npm install -g @refract-org/cli`
Python SDK	Typed Python wrapper — pandas DataFrames, notebooks, LangChain	`pip install git+https://github.com/refract-org/refract-py.git`
Refract UI	Browser visualizer — drag-and-drop JSONL, timelines, word-level diffs	`git clone refract-ui && bun run dev`

A typical workflow: analyze with Refract, export as NDJSON, then explore in Python or the UI.

Other pathways: System Integrators (SDK Reference · Production DDL · Private Wikis) · Engine Contributors (Custom Analyzer · Custom Eval · Architecture Decisions)

Further uses

Tutorials, and a longer list of use cases, built on the event stream:

Capability	Read
Claim-level search	Frontier use cases — Search claim histories, not documents. "Claims removed as unsourced." "Claims that softened after events."
LLM summarization	Summarization tutorial — Pipe events through any model. Get human-readable change reports with audit trail.
Non-Wikipedia sources	Custom adapter tutorial — Confluence, GitHub wikis, Notion. Same analyzers, different data.

License

AGPL-3.0. Built and maintained by NextConsensus.