worldoracle

Contradiction detector and belief repair for multi-source fact states — game worlds, AI pipelines, and multi-tool agents.

Quick Start · How It Works · Use Cases · Features · CLI Reference · MCP · OpenAI Tools · Alternatives

Why

Any system that merges facts from multiple sources ends up with contradictions. The sources don't coordinate — they just answer independently and move on.

In game worlds: The blacksmith "knows" the king is both alive and dead; the guard believes the bridge is passable while the quest log says it collapsed. These inconsistencies break immersion and cause dialogue bugs.

In AI pipelines: A web-search tool returns a price of $899. A RAG knowledge base (synced 14 days ago) returns $749. A reasoning LLM infers $820. Without reconciliation, the agent synthesises an average that is wrong for every tier — and 44% of multi-tool pipelines hit this pattern when the KB is more than 7 days stale.

worldoracle gives any system a typed belief store with automatic contradiction detection and principled repair strategies — so your world stays consistent even when multiple independent sources update the same facts.

Related MCP server: coherra

Use Cases

Multi-tool AI agents

When you fan out a question to web-search + RAG + LLM and combine the results, conflicting answers are the rule, not the exception. worldoracle detects which facts contradict, applies a priority strategy (prefer_newer, prefer_higher_confidence, prefer_observation), and surfaces a single resolved answer.

# Three AI tools answered the same question differently
state = BeliefState(npc_id="support-pipeline-run-001")
state.add(WorldPredicate("enterprise-tier", "monthly_price_usd", 899,
                         source="web-search", confidence=0.95, timestamp=now))
state.add(WorldPredicate("enterprise-tier", "monthly_price_usd", 749,
                         source="knowledge-base", confidence=0.75, timestamp=14_days_ago))

detector = ContradictionDetector()
pairs = detector.detect(state)  # [(web-search:899, knowledge-base:749)]

repairer = BeliefRepairer()
frame = repairer.repair(*pairs[0])
print(frame.resolved_value)   # 899  (web-search wins — newer + higher confidence)

See examples/ai_tool_contradiction_detector.py for a full walkthrough.

Game NPCs

Game NPCs frequently end up with contradictory world models across event systems, quest triggers, and dialogue trees. worldoracle gives every NPC a content-addressed belief store — consistent even when multiple systems update the same facts.

How It Works

flowchart LR
    A[Game event / quest trigger] --> B[WorldPredicate]
    B --> C[WorldOracleStore]
    C --> D{ContradictionDetector}
    D -- contradictions found --> E[BeliefRepairer]
    E --> F[RepairFrame]
    F --> G[Updated BeliefState]
    D -- no contradictions --> G

1. WorldPredicate — a typed belief: subject, attribute, value, source, confidence, timestamp. Content-addressed by SHA-256 of subject|attribute|str(value).

2. BeliefState — an NPC's full belief set; also content-addressed.

3. ContradictionDetector — scans for predicates with the same (subject, attribute) but different values.

4. BeliefRepairer — resolves each contradiction using strategies: prefer_newer, prefer_higher_confidence, prefer_observation.

Features

Quick Start

pip install worldoracle

from worldoracle import WorldPredicate, BeliefState, ContradictionDetector, BeliefRepairer

# Build a belief state
state = BeliefState(npc_id="guard-1")
state.add(WorldPredicate(subject="king", attribute="alive", value=True, source="quest-giver", confidence=0.8, timestamp=1.0))
state.add(WorldPredicate(subject="king", attribute="alive", value=False, source="observation", confidence=1.0, timestamp=2.0))

# Detect contradictions
detector = ContradictionDetector()
pairs = detector.detect(state)
print(f"Found {len(pairs)} contradiction(s)")

# Repair — strategies are applied automatically in priority order:
# prefer_newer → prefer_higher_confidence → prefer_observation
repairer = BeliefRepairer()
for a, b in pairs:
    frame = repairer.repair(a, b)  # repair(pred_a, pred_b) → RepairFrame
    print(f"Resolved: {frame.resolved_value!r} ({frame.strategy})")

CLI Reference

worldoracle [--db PATH] COMMAND [ARGS]

# Add beliefs
worldoracle add guard-1 king alive True --source observation --confidence 0.9 --timestamp 100
worldoracle add guard-1 king alive False --source rumor --confidence 0.5 --timestamp 50

# Check for contradictions
worldoracle check guard-1
# Found 1 contradiction(s) for guard-1:
#   CONFLICT: king.alive: 'True' vs 'False'

# Repair
worldoracle repair guard-1

REST Server

Install the API extra and start the server:

pip install 'worldoracle[api]'
uvicorn worldoracle.api:app --reload

The OpenAPI docs are available at http://localhost:8000/docs. See openapi.yaml for the full schema.

Repo Tree

worldoracle/
├── src/worldoracle/     ← Python package
│   ├── predicate.py     ← WorldPredicate, BeliefState, Detector, Repairer
│   ├── store.py         ← SQLite persistence
│   ├── cli.py           ← Click CLI
│   ├── api.py           ← FastAPI server
│   ├── mcp_server.py    ← MCP server
│   ├── report.py        ← Rich + JSON + Markdown formatters
│   └── py.typed
├── tests/               ← 45+ tests
├── docs/
├── tools/openai-tools.json
└── openapi.yaml

MCP / Claude Desktop

Install the MCP server:

pip install "worldoracle[mcp]"

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "worldoracle": {
      "command": "worldoracle-mcp"
    }
  }
}

Tools exposed: add_predicate, check_beliefs, repair_contradictions.

See docs/mcp.md and Smithery for hosted registry.

OpenAI Tools

The tools/openai-tools.json file defines function-calling schemas for GPT-4o and Codex CLI:

cat tools/openai-tools.json

See docs/openai.md for integration examples.

Alternatives

Topics

This project is tagged: #npc #game-ai #belief-revision #llm #agents #mcp #fastapi

GitHub Topics: npc, belief-revision, game-ai, contradiction, agents, mcp, llmops

Case Studies

See how teams are using worldoracle in production:

• Eliminating Immersion-Breaking NPC Contradictions in a Narrative Game — Narrative Forge eliminates NPC belief contradictions across 300 NPCs with a 12ms consistency check

• Automated Contradiction Resolution Across 50+ Data Sources — Meridian Intelligence reduces manual reconciliation from 4 hours to 0 per report

Stay Updated

Subscribe to The Silence Layer — weekly dispatches on production AI infrastructure, new releases, and the failure modes that production AI systems don't surface until it's too late.

Star History

Closed loop / Non-Ornament

See docs/CLOSED_LOOP.md for when this library is load-bearing vs ornamental, and when not to use it.