Tutorial: BYO-inference summarization

Goal

Pipe Refract's deterministic event stream through an LLM to produce a human-readable summary of what changed on a Wikipedia page. The engine stays deterministic. The model provides the narrative. Each one is auditable independently.

Why summarize with a model

Refract produces 26 event types — raw, structured, queryable. Non-technical users don't want an event stream. They want: "This week, 3 citations were removed from the lead section, the origin claims were softened, and a dispute template was added."

The model doesn't change Refract's output. It reads it and summarizes. The FactProvenance.parameters field records which path was taken.

Step 1: Export the event stream

refract analyze "COVID-19" --since 2026-01-01 --depth forensic > covid-events.jsonl

Step 2: Summarize with a model

# Pipe to any OpenAI-compatible endpoint
cat covid-events.jsonl | head -100 | \
  jq -s '{events: .}' | \
  curl -s https://api.openai.com/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
      "model": "gpt-4o-mini",
      "messages": [{
        "role": "system",
        "content": "Summarize these Wikipedia revision events in 3-5 bullet points. Group by theme: citations, claims, disputes, structure. Mention which sections were affected. Be specific about what changed."
      }, {
        "role": "user",
        "content": "."
      }],
      "temperature": 0
    }' | jq -r '.choices[0].message.content'

Output:

• Citations: 2 sources removed from "Origins" section (WHO report dated 2023-01-15,
  Lancet study dated 2022-06-03). 1 new citation added to "Transmission" section
  (CDC update dated 2026-01-10).
• Claims: Origin language softened — "The virus originated in Wuhan" changed to
  "The earliest known cases were identified in Wuhan." 4 sentence modifications
  across "Origins" and "Timeline" sections.
• Disputes: NPOV template added to "Origins" section on 2026-01-12. 2 reverts
  detected in same section within 24 hours.
• Structure: "Variants" section reorganized — 2 new subsections added.
• Talk page: 1 new thread opened on 2026-01-13 discussing origin language.
  8 replies across 3 threads.

Step 3: Use the MCP server for agent-driven summarization

refract mcp

Connect any MCP client and ask:

"Analyze the COVID-19 Wikipedia page since January 2026. Give me a summary of what changed: citations, claims, disputes, structure. Be specific."

The agent calls refract analyze via MCP, receives structured events, and synthesizes a summary. Every claim in the summary is backed by a deterministic event with a hash — the agent can cite provenance.

Step 4: Audit which path was taken

Every event carries FactProvenance.parameters recording whether the default heuristic or a model was used. When a model produces a summary, the original events are unchanged — the model consumed the stream, it didn't modify it.

To verify: compare the eventId hashes before and after summarization. They match. The engine is deterministic. The narrative is interpretive. Each is auditable independently.

Available models

Any OpenAI-compatible endpoint works:

Next steps

• BYO-inference tutorial — replacing heuristics with models at each boundary
• MCP agent tutorial — connect AI coding agents to Refract
• RAG provenance tutorial — stability signals for retrieval