rulegraph add-rule PHB.attack "When you make an attack roll..." --type mechanic --tag combat
rulegraph add-edge UA.flanking PHB.attack modifies
rulegraph query "How do I make an attack roll?"

╭──────────────────────────────────────╮
│ Query: How do I make an attack roll? │
│ Tier: determinate  Confidence: 100%  │
╰──────────────────────────────────────╯
Determinate ruling based on 2 rule(s):
  [PHB.attack] When you make an attack roll, roll d20 + modifier. If result >= AC, attack hits.
  [UA.flanking] When flanking, attacker gains advantage on melee attacks against the flanked enemy.

Provenance (2): PHB.attack, UA.flanking

flowchart LR
    A[Load rulebook\nRuleNode per rule] --> B[Add edges\nmodifies · supersedes · requires]
    B --> C[RuleGraph\ncontent-addressed nodes]
    C --> D{rulegraph query}
    D --> E[Keyword matching\nfind relevant rules]
    E --> F[Classify tier\ndeterminate vs indeterminate]
    F --> G[Detect contradictions\nsupersedes edges]
    G --> H[ArbitrationResult\nwith provenance + confidence]

pip install rulegraph
# or with API server:
pip install "rulegraph[api]"

# Add rules
rulegraph add-rule PHB.attack "Roll d20 + modifier. If result >= AC, attack hits." \
    --type mechanic --tag combat --tag attack

rulegraph add-rule PHB.difficult "Difficult terrain costs 1 extra foot per foot moved." \
    --type narrative --tag movement

# Add an edge (UA flanking modifies PHB attack roll)
rulegraph add-edge UA.flanking PHB.attack modifies --condition "when flanking"

# Query
rulegraph query "How do I make an attack roll?"
rulegraph query "What is difficult terrain?"

# List rules
rulegraph rules
rulegraph rules --tag combat

# Status
rulegraph status

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

cat tools/openai-tools.json | jq '.[].function.name'
# => "add_rule", "query_rules", "arbitrate"

rulegraph/
├── src/rulegraph/
│   ├── rule.py          # RuleNode, RuleEdge, RuleGraph, RuleStore, RuleArbiter
│   ├── report.py        # Rich, JSON, Markdown formatters
│   ├── cli.py           # Click CLI
│   ├── api.py           # FastAPI server
│   └── mcp_server.py    # MCP server
├── tests/
│   ├── test_rule.py
│   ├── test_graph.py
│   ├── test_store.py
│   ├── test_arbiter.py
│   ├── test_report.py
│   ├── test_cli_runner.py
│   └── test_api.py
├── examples/demo.py
├── smoke_test.py
└── pyproject.toml

from rulegraph.rule import RuleNode, RuleEdge, RuleGraph, RuleArbiter, ArbitrationResult

# 1. Create the rule graph
graph = RuleGraph()

# 2. Add the two conflicting rule nodes
phb_node = RuleNode(
    rule_id="PHB.rogue.uncanny_dodge",
    text=(
        "A rogue with Uncanny Dodge can use their reaction to halve the damage "
        "from an attack they can see."
    ),
    node_type="interpretation",
    tags=["rogue", "uncanny-dodge", "reaction", "combat"],
    source="Player's Handbook",
    confidence=1.0,
)

errata_node = RuleNode(
    rule_id="Errata.2024.uncanny_dodge",
    text="Uncanny Dodge does not apply against attacks from invisible creatures.",
    node_type="interpretation",
    tags=["rogue", "uncanny-dodge", "errata", "invisible"],
    source="D&D 2024 Errata",
    confidence=1.0,
)

graph.add_node(phb_node)
graph.add_node(errata_node)

# 3. Add a supersedes edge: newer errata supersedes the PHB base text
supersedes_edge = RuleEdge(
    source_id="Errata.2024.uncanny_dodge",
    target_id="PHB.rogue.uncanny_dodge",
    relation="supersedes",
    condition="when attacker is invisible",
)
graph.add_edge(supersedes_edge)

# 4. Create the arbiter
arbiter = RuleArbiter(graph)

# 5. Query: player asks about invisible attacker
question = "Can a rogue use Uncanny Dodge against an invisible attacker?"
result: ArbitrationResult = arbiter.query(question)

# 6. Check for contradiction and indeterminate tier
assert result.tier == "indeterminate", f"Expected indeterminate, got {result.tier!r}"
assert len(result.contradictions) > 0, "Expected at least one contradiction"

# 7. Print the ruling and the contradicting rules
print(f"Query   : {result.query}")
print(f"Tier    : {result.tier}")
print(f"Confidence: {result.confidence:.0%}")
print()
print("Ruling:")
print(result.answer)
print()
print(f"Provenance  : {result.provenance}")
print(f"Contradictions: {result.contradictions}")
print()
print("--- Contradicting rule texts ---")
for rule_id in result.contradictions:
    node = graph.get_node(rule_id)
    if node:
        print(f"  [{node.rule_id}] {node.text}")

Query   : Can a rogue use Uncanny Dodge against an invisible attacker?
Tier    : indeterminate
Confidence: 85%

Ruling:
Indeterminate ruling — requires GM interpretation (2 rule(s) found):
  [Errata.2024.uncanny_dodge] Uncanny Dodge does not apply against attacks from invisible creatures.
  [PHB.rogue.uncanny_dodge] A rogue with Uncanny Dodge can use their reaction to halve the damage from an attack the…
WARNING: 1 contradiction(s) detected: PHB.rogue.uncanny_dodge

Provenance  : ['Errata.2024.uncanny_dodge', 'PHB.rogue.uncanny_dodge']
Contradictions: ['PHB.rogue.uncanny_dodge']

--- Contradicting rule texts ---
  [PHB.rogue.uncanny_dodge] A rogue with Uncanny Dodge can use their reaction to halve the damage from an attack they can see.