Metadata-Version: 2.4
Name: worldoracle
Version: 0.1.1
Summary: NPC contradiction detector and belief repair for game worlds
Project-URL: Homepage, https://github.com/sandeep-alluru/worldoracle
Project-URL: Repository, https://github.com/sandeep-alluru/worldoracle
Project-URL: Documentation, https://sandeep-alluru.github.io/worldoracle
Project-URL: Changelog, https://github.com/sandeep-alluru/worldoracle/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/sandeep-alluru/worldoracle/issues
Author-email: Sandeep Alluru <onepuncchh@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Sandeep Alluru
        
        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: agents,belief-revision,contradiction,gaming,llmops,mcp,npc
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT 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 :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Provides-Extra: api
Requires-Dist: fastapi>=0.110; extra == 'api'
Requires-Dist: httpx>=0.27; extra == 'api'
Requires-Dist: uvicorn>=0.29; extra == 'api'
Provides-Extra: dev
Requires-Dist: fastapi>=0.110; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

![worldoracle](assets/hero.png)

# worldoracle

[![CI](https://github.com/sandeep-alluru/worldoracle/actions/workflows/ci.yml/badge.svg)](https://github.com/sandeep-alluru/worldoracle/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/worldoracle.svg)](https://pypi.org/project/worldoracle/)
[![Python Versions](https://img.shields.io/pypi/pyversions/worldoracle.svg)](https://pypi.org/project/worldoracle/)
[![Downloads](https://img.shields.io/pepy/dt/worldoracle)](https://pepy.tech/project/worldoracle)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![codecov](https://codecov.io/gh/sandeep-alluru/worldoracle/branch/main/graph/badge.svg)](https://codecov.io/gh/sandeep-alluru/worldoracle)
[![Typed](https://img.shields.io/badge/mypy-typed-blue.svg)](https://mypy.readthedocs.io)

**NPC contradiction detector and belief repair for game worlds.**

[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Features](#features) · [CLI Reference](#cli-reference) · [MCP](#mcp--claude-desktop) · [OpenAI Tools](#openai-tools) · [Alternatives](#alternatives)

---

## Why

Game NPCs frequently end up with contradictory world models: 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.

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

---

## How It Works

```mermaid
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

| Feature | Status |
|---------|--------|
| Content-addressed predicates (SHA-256) | ✅ |
| SQLite persistence (`WorldOracleStore`) | ✅ |
| Contradiction detection | ✅ |
| Belief repair (3 strategies) | ✅ |
| Rich CLI (7 subcommands) | ✅ |
| FastAPI REST server | ✅ |
| MCP server for Claude Desktop | ✅ |
| OpenAI function-calling tools | ✅ |
| 93 tests, >98% coverage | ✅ |
| Fully typed (py.typed) | ✅ |

---

## Quick Start

```bash
pip install worldoracle
```

```python
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]
```

| Command | Description |
|---------|-------------|
| `add NPC_ID SUBJECT ATTRIBUTE VALUE` | Add a predicate to an NPC's belief state |
| `check NPC_ID` | Detect contradictions |
| `repair NPC_ID` | Generate repair frames for all contradictions |
| `beliefs NPC_ID` | List all beliefs for an NPC |
| `consistency` | Run full consistency check across all NPCs |
| `diff NPC_ID TIMESTAMP_A TIMESTAMP_B` | Diff belief state at two points in time |
| `status` | Show database stats |

```bash
# 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:

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

The OpenAPI docs are available at `http://localhost:8000/docs`. See [openapi.yaml](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:

```bash
pip install "worldoracle[mcp]"
```

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

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

Tools exposed: `add_predicate`, `check_beliefs`, `repair_contradictions`.

See [docs/mcp.md](docs/mcp.md) and [Smithery](https://smithery.ai) for hosted registry.

---

## OpenAI Tools

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

```bash
cat tools/openai-tools.json
```

See [docs/openai.md](docs/openai.md) for integration examples.

---

## Alternatives

| Tool | Approach | worldoracle advantage |
|------|----------|-----------------------|
| Manual quest flags | Unstructured booleans | Typed, content-addressed, auditable |
| Event sourcing logs | Append-only, no repair | Built-in contradiction detection + repair |
| Prolog / logic engines | Heavyweight runtime | Zero-dep Python, SQLite storage |
| LLM world models | Probabilistic, opaque | Deterministic, inspectable, fast |

---

## 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](docs/case-studies/gaming-npc-world-consistency.md) — Narrative Forge eliminates NPC belief contradictions across 300 NPCs with a 12ms consistency check
- [Automated Contradiction Resolution Across 50+ Data Sources](docs/case-studies/enterprise-multi-source-factbase.md) — Meridian Intelligence reduces manual reconciliation from 4 hours to 0 per report

---

## Stay Updated

Subscribe to [**The Silence Layer**](https://newsletter.salluru.dev) — 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

[![Star History Chart](https://api.star-history.com/svg?repos=sandeep-alluru/worldoracle&type=Date)](https://star-history.com/#sandeep-alluru/worldoracle&Date)

<!-- mcp-name: io.github.sandeep-alluru/worldoracle -->
