grounded-reasoning 0.1.0__py3-none-any.whl

grounded_reasoning/__init__.py

@@ -0,0 +1,38 @@
+"""
+grounded-reasoning — a relation-reasoning verifier for LLMs and agents.
+
+Public API (clean import surface):
+
+    from grounded_reasoning import GroundedReasoner, verify_relation, TOOL_SPEC
+
+- GroundedReasoner : load facts, then verify / filter_claims / contradictions.
+- verify_relation  : a stateless function-calling tool (0 tokens, returns a proof).
+- TOOL_SPEC / openai_tool_spec : tool schemas (Anthropic / OpenAI).
+- ConformalReasoner : distribution-free coverage guarantee >=1-alpha under a noisy graph.
+- LLMClient : a multi-provider (OpenAI-compatible) client for demos/experiments.
+"""
+from src.agent import (
+    TOOL_SPEC,
+    GroundedReasoner,
+    Verdict,
+    openai_tool_spec,
+    run_tool,
+    verify_relation,
+)
+from src.reasoning.conformal_reasoning import ConformalReasoner, conformal_threshold
+from src.reasoning.llm_client import LLMClient
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "GroundedReasoner",
+    "Verdict",
+    "verify_relation",
+    "run_tool",
+    "TOOL_SPEC",
+    "openai_tool_spec",
+    "ConformalReasoner",
+    "conformal_threshold",
+    "LLMClient",
+    "__version__",
+]

grounded_reasoning-0.1.0.dist-info/METADATA

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: grounded-reasoning
+Version: 0.1.0
+Summary: Zero-token, precision-guaranteed verifier for LLM/agent multi-hop relational reasoning
+License: MIT
+Project-URL: Homepage, https://github.com/ALEXaquarius/grounded-reasoning
+Project-URL: Repository, https://github.com/ALEXaquarius/grounded-reasoning
+Project-URL: Paper, https://github.com/ALEXaquarius/grounded-reasoning/blob/main/PAPER.md
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=6; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# grounded-reasoning — Grounded, Guaranteed Reasoning for LLMs & Agents
+
+[![CI](https://github.com/ALEXaquarius/grounded-reasoning/actions/workflows/ci.yml/badge.svg)](https://github.com/ALEXaquarius/grounded-reasoning/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ALEXaquarius/grounded-reasoning/blob/main/examples/quickstart.ipynb)
+
+> **TL;DR.** LLMs hallucinate on multi-hop relational reasoning. This is a
+> **relation-algebra verifier** an agent calls to check a claim *before* asserting it:
+> **zero model tokens**, **precision-guaranteed** (accepts a claim iff a grounded proof
+> path exists), language-agnostic, and provider-agnostic. Plugs in as a **library**, a
+> **function-calling tool**, or an **MCP server**. Validated on **real LLMs** (DeepSeek
+> et al.) and the public **CLUTRR** benchmark. See [docs/integration.md](docs/integration.md).
+
+📄 Full paper: **[PAPER.md](PAPER.md)** · Integration guide: **[docs/integration.md](docs/integration.md)** · Try it in 30 seconds: **[quickstart notebook](https://colab.research.google.com/github/ALEXaquarius/grounded-reasoning/blob/main/examples/quickstart.ipynb)**
+
+Đọc bằng tiếng Việt: **[README.vi.md](README.vi.md)**
+
+---
+
+## Why this exists
+
+LLMs are solid on one-hop facts but **collapse on composition** — chaining several
+correct facts into a multi-step conclusion. On CLUTRR (kinship reasoning), DeepSeek's
+accuracy **falls off with depth**, while a grounded operator-composition solver holds
+**~100% flat — at zero tokens**:
+
+```
+acc
+100% ●─────●─────●─────●─────●─────●─────●   ● Grounded solver (algebra, 0 tokens)
+ 90% |
+ 80% ○
+ 70% |  ╲
+ 60% |   ╲
+ 50% |    ╲
+ 40% |     ○           ○                     ○ DeepSeek (LLM)
+ 30% |      ╲         ╱ ╲
+ 20% |       ○─────○     ╲
+ 10% |                    ○─────○
+  0% +──┴─────┴─────┴─────┴─────┴─────┴─────┴─
+      hop 2    3     4     5     6     7     8   (composition steps)
+
+     hop:      2     3     4     5     6     7     8
+     DeepSeek: 83%   42%   25%   25%   42%   17%   8%
+     Solver:   100%  100%  100%  100%  100%  100%  100%
+```
+
+*(CLUTRR/v1 gen_train234_test2to10, clean-chain, n=12/hop; full test set n=635: solver
+covers 99.5%, accuracy 99.2%. `src/experiments/clutrr_eval.py`.)*
+
+---
+
+## What it is / is NOT (honestly)
+
+**Is:** a guaranteed reasoning-verification layer built on relation operator algebra.
+- **Precision = 1.0, guaranteed** (Theorem G) — accepts a claim only if a grounded proof path exists.
+- **Zero extra tokens** — local matrix multiplication, no LLM call. Compare to
+  "have the LLM self-verify," which costs +110% tokens for 34% precision.
+- **Two-sided guarantee** (Theorem I) — precision *and* recall both have tight bounds.
+- **No external KB required** (SGDC) — uses the LLM's own internal consistency.
+
+**Is not:** an "unprecedented breakthrough." The Katz index, the Neumann series,
+graph reachability, and neuro-symbolic grounding are all classical math and
+technique. The contribution here is unification, a measured guarantee, and
+benchmark numbers — not a new primitive. The guard needs a relation graph
+(supplied, or extracted from LLM facts); flexibility is bounded (see
+[PAPER §5](PAPER.md)).
+
+### How this differs from the usual fixes
+
+| Approach | Extra tokens | Guarantee | Needs an external KB |
+|---|---|---|---|
+| LLM self-verification (2nd call) | +110% | none (measured 34% precision) | no |
+| Self-consistency / majority vote | multiplies with sample count | none, statistical only | no |
+| RAG / external KG grounding | varies | only as good as retrieval | yes |
+| **This guard** | **+0** | **precision = 1.0** (Theorem G) | no |
+| **This guard, self-grounded (SGDC)** | **+0** | precision = 1.0 given sound atomic facts (Theorem I) | no |
+| **This guard, conformal** | **+0** | coverage ≥ 1−α, distribution-free (Theorem K) | no |
+
+---
+
+## Three theorems, one operator (F = G = H)
+
+The reasoning core rests on a single unification (numerically verified, zero error):
+
+| View | Theorem | Content |
+|------|---------|---------|
+| Fuzzy diffusion inference | **F** | conf(a→b) = Σ αᵏ(Pᵏ)[a,b], calibrated + grounded |
+| Relation operator algebra | **G** | composition = operator product, transitive closure = Σ powers |
+| Spectral analysis (Katz) | **H** | `engine.infer` = resolvent (I−αP)⁻¹−I (matches **0.0** error) |
+
+⟹ fuzzy inference **is** spectral analysis of the relation operator. `src/reasoning/`.
+
+Four further theorems extend this core: **I** (two-sided precision/recall guarantee
+for a self-grounded, no-external-KB variant), **J** (closure-learning completeness,
+validated on CLUTRR), **K** (conformal reasoning — distribution-free coverage under a
+*noisy* relation graph, including one extracted by an LLM from raw text), and **L**
+(Horn forward-chaining, generalizing transitive closure to conjunctive rules). All
+seven are stated, proved, and numerically verified in [PAPER.md](PAPER.md).
+
+---
+
+## Evidence on real LLMs (DeepSeek)
+
+| Experiment | Result |
+|------------|--------|
+| Hallucination guard (kinship) | precision **33% → 100%**, catches 94/94, 0 false rejects |
+| Guard token cost | **+0 tokens** (vs. LLM self-verify: +110% tokens, 34% precision) |
+| SGDC (self-grounded, no external KB) | precision **78% → 100%** from internal consistency alone |
+| CLUTRR (public benchmark) | solver **~100% at every hop** vs. DeepSeek 83%→8% |
+| Hard passage (9-step chain) | DeepSeek **fabricates 2/10** (wrong direction); grounded system **10/10**, with proofs — [`examples/hallucination_demo.py`](examples/hallucination_demo.py) |
+
+---
+
+## Guaranteed reasoning over a graph an LLM extracted from raw text
+
+The guard/solver needs a **clean** graph. But if you let an **LLM extract** relations
+from natural-language text, the graph is **noisy** (missing/spurious edges).
+**Conformal Reasoning** (Theorem K) fixes exactly that: use operator confidence as a
+score, calibrate a threshold ⟹ **distribution-free coverage ≥ 1−α**, even on a noisy
+graph.
+
+End-to-end demo: **DeepSeek extracts an "is a" graph from text** → conformal runs on
+that extracted graph (ground truth is used only for scoring):
+
+| Text | LLM extraction (P / R) | Coverage (target ≥90%) | Efficiency (FPR) |
+|------|------------------------:|----------------------------:|------------------:|
+| Easy | 100% / 99.7% | **91.3%** | 0.0 |
+| Hard (nested clauses + near-miss distractors) | 99.5% / **68.5%** | **93.0%** | 0.77 |
+
+> The LLM's extraction **drops 31% of the edges** (a genuinely noisy graph) →
+> **the coverage guarantee still holds** (93% ≥ 90%), only efficiency degrades.
+> *Validity always holds; efficiency scales with graph quality.*
+
+⟹ A path to guaranteed reasoning over **natural-language relations** — where the hard
+guard can't reach. `src/experiments/conformal_llm_eval.py`.
+
+---
+
+## Quickstart
+
+```bash
+git clone https://github.com/ALEXaquarius/grounded-reasoning
+cd grounded-reasoning && pip install -e ".[dev]"     # not yet on PyPI — install from source
+pytest tests/                       # every theorem + offline-locked logic, no network needed
+
+# Use it right now (no LLM/network needed):
+python -c "from grounded_reasoning import GroundedReasoner as G; r=G(); r.add_facts([('a','p','b'),('b','p','c')]); print(r.verify('a','c',via='p'))"
+
+# Real-LLM experiments (need a key — read from an env var, NEVER hardcoded):
+export DEEPSEEK_API_KEY=sk-...        # bring your own; .env is gitignored
+python -m src.experiments.guard_llm_eval        # hallucination guard
+python -m src.experiments.self_grounded_eval    # SGDC
+python -m src.experiments.clutrr_eval           # public CLUTRR benchmark
+python -m src.experiments.conformal_llm_eval    # end-to-end conformal (LLM-extracted graph)
+```
+
+---
+
+## Integrating with an Agent / LLM (`src/agent/`)
+
+A **relation-reasoning verifier** for agents: check a multi-hop claim **before
+asserting it** — zero model tokens, precision guaranteed (accepts iff a grounded proof
+path exists).
+
+```python
+from grounded_reasoning import GroundedReasoner
+gr = GroundedReasoner()
+gr.add_facts([("alice","parent","bob"),("bob","parent","carol")])
+gr.verify("alice","carol", via="parent")   # Verdict(grounded=True, proof=['alice','bob','carol'])
+gr.verify("alice","zed",   via="parent")   # Verdict(grounded=False, proof=None)  ← hallucination blocked
+```
+
+Three integration paths (details: [docs/integration.md](docs/integration.md)):
+- **Library**: `GroundedReasoner.verify / filter_claims / contradictions`.
+- **Function-calling**: `TOOL_SPEC` (Anthropic) / `openai_tool_spec()` (OpenAI) + `run_tool` — a stateless `verify_relation` tool.
+- **MCP server**: `python -m src.agent.mcp_server` — plugs into Claude or any MCP-compatible agent.
+
+**Multi-provider** (not just DeepSeek): `LLMClient(provider=...)` for DeepSeek / OpenAI /
+Groq / OpenRouter / Together / Mistral / Ollama (local) — all OpenAI-compatible, switch
+providers without changing code. **Multilingual**: entities/relations are opaque
+Unicode strings ⟹ works with any language (`cha`, `父`, `والد`…) with zero configuration.
+
+A real function-calling demo (agent verifies itself, blocks hallucination):
+`python -m src.experiments.agent_demo`. When the graph is **noisy** (relations
+extracted by an LLM from text), use `ConformalReasoner` for a **coverage ≥1−α**
+guarantee instead of hard precision.
+
+---
+
+## Source map
+
+| Path | Content |
+|------|---------|
+| `grounded_reasoning/` | Public package — `GroundedReasoner`, `verify_relation`, `TOOL_SPEC`, `ConformalReasoner`, `LLMClient` |
+| `src/agent/{verifier,tool,mcp_server}.py` | Public API implementation — HallucinationGuard, function-calling tool, MCP server |
+| `src/reasoning/abstract_inference.py` | FuzzyInferenceEngine, TypedInferenceEngine, HallucinationGuard (Theorem F) |
+| `src/reasoning/operator_algebra.py` | Relation operator algebra (Theorem G) |
+| `src/reasoning/relation_spectrum.py` | Spectrum, nilpotency, Katz resolvent (Theorem H) |
+| `src/reasoning/conformal_reasoning.py` | Conformal — coverage guarantee under noise (Theorem K) |
+| `src/reasoning/composition_algebra.py` | Composition-table learning, validated on CLUTRR (Theorem J) |
+| `src/reasoning/horn.py` | Horn forward-chaining, least-model semantics (Theorem L) |
+| `src/reasoning/llm_client.py` | Provider-agnostic LLM client (key read from an env var) |
+| `src/theory/theorems.py` | **Seven theorems (F–L)** with numerical verification |
+| `src/experiments/{guard_llm,self_grounded,nl_ontology,guard_cost,clutrr,conformal_llm,inference}_eval.py` | Real-LLM and benchmark experiments backing every claim above |
+| `examples/hallucination_demo.py` | End-to-end function-calling demo |
+| `examples/quickstart.ipynb` | Runnable tour of the library (offline, Colab-ready) |
+
+---
+
+## Origin story
+
+This project began as an attempt to invent an embedding-free retrieval algorithm that
+could compete with dense/RAG retrieval. That research question reached a rigorous,
+fully honest **negative** conclusion (ties BM25, loses significantly to dense
+embeddings — with a proof of why). The same mathematical toolkit — operator algebra,
+spectral analysis — turned out to have real, measurable value on a different problem:
+**guaranteeing** multi-hop relational reasoning. This repository ships only that
+validated, tested reasoning system; the full retrieval research trail (including every
+failed attempt, honestly recorded) lives in a separate research repository and is not
+part of this package. See [PAPER.md §1](PAPER.md) for the full framing.
+
+---
+
+## Contributing & Community
+
+- How to contribute + research principles: [CONTRIBUTING.md](CONTRIBUTING.md)
+- Code of conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) · Security: [SECURITY.md](SECURITY.md)
+- Version history: [CHANGELOG.md](CHANGELOG.md) · Citation: [CITATION.cff](CITATION.cff)
+- License: **MIT** ([LICENSE](LICENSE))
+
+---
+
+*Principle: proof before code, formal definitions, falsifiability, and honest
+reporting of negative results — see [CONTRIBUTING.md](CONTRIBUTING.md).*

grounded_reasoning-0.1.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+grounded_reasoning/__init__.py,sha256=XFxfon70jvzj8bPAL6fzYdnfAxAEolQeLdB1n4ufKBo,1112
+grounded_reasoning-0.1.0.dist-info/licenses/LICENSE,sha256=MqhOEz7X42LVfaxFNmWGqTHENDxbC64xidGpANVud8k,1088
+src/__init__.py,sha256=btdnrY03zgQ1GeBCUyB7jZnkLvz6UhGkMf7wwUdnEvs,94
+src/agent/__init__.py,sha256=yxo279ck2ud0bOn00cFZRHdTN215N-OGDFgd_0mpE5k,580
+src/agent/mcp_server.py,sha256=dvIcm7pGzEhe2JopnBQ70OMgbS_36X0bAGIz90bhU0o,1135
+src/agent/tool.py,sha256=AKT5OvHacnJI8GY3gMt12gI4trc0SZWOk3hQJY3Msds,3431
+src/agent/verifier.py,sha256=YukMbHo15Q6P9siwYHZ1XUhMYVFJ5AOxp-ZZiqltEu4,7701
+src/experiments/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/experiments/agent_demo.py,sha256=mVF_6UAgNuYg8rpqobQWPxe1RZDqoysbOcrD9KtRPoU,4215
+src/experiments/clutrr_eval.py,sha256=oGjBbBNhDEzUP-IBWEyo-oXtwHYcfP7yGX5rom6od7M,10603
+src/experiments/conformal_llm_eval.py,sha256=a4Jz76OlUlLkZg5qE4iNee4Wz8l_n42_Qkub30tYc74,7397
+src/experiments/guard_cost_eval.py,sha256=v68m1DUa3cu7AEi5VrEefPhsFQk8KeIgSeiZjlXp4Qw,4000
+src/experiments/guard_llm_eval.py,sha256=Dpf100Xikkwutx8kO4vMsh1kzKy6uHcujlBEbWy85Jg,5614
+src/experiments/inference_eval.py,sha256=FMB-mejGduzrvaHvACPYF6oRE9zWn0k6pEZLLsqI6GY,4165
+src/experiments/nl_ontology_eval.py,sha256=oRMGD2bLFWej-dapAdvx3aewwsRjPIrz3H6_Y4LbXQU,9334
+src/experiments/self_grounded_eval.py,sha256=Xi6vFFXQuChyke6E7VB7P5X-5CCjQ4WaCpLskBcCqoo,6438
+src/reasoning/__init__.py,sha256=x8cuGTx7m_yqXj5wM-lQ4ZXRg6qqXFEBIGKqqm99d-4,610
+src/reasoning/abstract_inference.py,sha256=Lchg_rnGkvSMy5LcJhb_GZmjwSu_K9Q_FKa0hnP7L_Q,7045
+src/reasoning/composition_algebra.py,sha256=eK4jI4cBmRXDm5vHB9rWhLfFpjcasQB3bKq-I6PZDFg,2491
+src/reasoning/conformal_reasoning.py,sha256=PyT2n_Zeb1OHOlHAIx-YMJD7Cj_9JYy1gll7JRcI6PU,3115
+src/reasoning/horn.py,sha256=lVGWcZPQFS_BPcoAJpLEg6Nk9UYnG35_zKfE5Fn-8w4,2124
+src/reasoning/llm_client.py,sha256=QME0RW2X7Gm9z9IqoHZCce1qinKlcKV1KD-7Wepg92w,5852
+src/reasoning/operator_algebra.py,sha256=6Ix0k8sg9v3a-g7R3RwUYsahCSXLuxC6axZJWiiCXeo,5094
+src/reasoning/relation_spectrum.py,sha256=pFe0LSQx4krFhseaQom-QGn2kwn0GGnXwjtHFu_kVpI,4428
+src/theory/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/theory/theorems.py,sha256=5j4B8eypv2zN1jAkjRfdJn0a2I2zdgWjj4QwfPQ3fxw,27740
+grounded_reasoning-0.1.0.dist-info/METADATA,sha256=s9vwvbBcwpc6rAYnsgnzK7rEDtcp0J1NNlnxZ3NpV38,13317
+grounded_reasoning-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+grounded_reasoning-0.1.0.dist-info/entry_points.txt,sha256=LeiyVmu4Bw3Y8lVpNsTsiTd8Zg_GyVrokAtv3Q91p5I,69
+grounded_reasoning-0.1.0.dist-info/top_level.txt,sha256=nq6246FMNze-gecMmsMSXlX1pvQpMc_GecIcV0RTMMA,23
+grounded_reasoning-0.1.0.dist-info/RECORD,,

grounded_reasoning-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

grounded_reasoning-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+grounded-reasoning-mcp = src.agent.mcp_server:main

grounded_reasoning-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 grounded-reasoning contributors
+
+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.

grounded_reasoning-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+grounded_reasoning
+src

src/__init__.py

@@ -0,0 +1,3 @@
+"""RAG-Laclac: Research framework for beyond-RAG retrieval methods."""
+
+__version__ = "0.1.0"

src/agent/__init__.py

@@ -0,0 +1,18 @@
+"""
+Agent/LLM integration layer for grounded reasoning.
+
+- GroundedReasoner : facade — load facts, verify multi-hop relational claims.
+- verify_relation  : a stateless function-calling tool (0 tokens, returns a proof).
+- TOOL_SPEC        : tool schema (Anthropic/OpenAI) for registering with a model.
+"""
+from src.agent.tool import TOOL_SPEC, openai_tool_spec, run_tool, verify_relation
+from src.agent.verifier import GroundedReasoner, Verdict
+
+__all__ = [
+    "GroundedReasoner",
+    "Verdict",
+    "verify_relation",
+    "run_tool",
+    "TOOL_SPEC",
+    "openai_tool_spec",
+]

src/agent/mcp_server.py

@@ -0,0 +1,37 @@
+"""
+MCP server — exposes `verify_relation` as an MCP tool so ANY MCP-compatible agent
+(Claude, etc.) can use it directly: the agent verifies a relational claim before
+asserting it, at 0 tokens, with a proof.
+
+Run (requires `pip install mcp`):
+    python -m src.agent.mcp_server        # stdio server
+
+The `mcp` import is LAZY-loaded inside build_server() so this module still imports
+cleanly even without `mcp` installed (tests/CI don't need the dependency).
+"""
+from __future__ import annotations
+
+from src.agent.tool import TOOL_SPEC, verify_relation
+
+
+def build_server():
+    """Build a FastMCP server exposing the verify_relation tool (lazy `mcp` import)."""
+    from mcp.server.fastmcp import FastMCP
+
+    server = FastMCP("grounded-reasoning")
+
+    @server.tool(name=TOOL_SPEC["name"], description=TOOL_SPEC["description"])
+    def verify_relation_tool(
+        facts: list[list[str]], subject: str, relation: str, object: str  # noqa: A002
+    ) -> dict:
+        return verify_relation(facts, subject, relation, object)
+
+    return server
+
+
+def main() -> None:
+    build_server().run()
+
+
+if __name__ == "__main__":
+    main()

src/agent/tool.py

@@ -0,0 +1,93 @@
+"""
+A tool for AGENTS (function-calling) — verifies a relational claim BEFORE it is
+asserted.
+
+Stateless & JSON-friendly: the agent passes `facts` + a claim, and gets back a
+verdict + proof path. Catches multi-hop relational hallucination at 0 LLM tokens,
+with a precision guarantee (Theorem G).
+
+Use with Anthropic/OpenAI function-calling:
+    tools=[TOOL_SPEC]; ... when the model calls the tool -> run_tool(tool_input)
+Or call directly: verify_relation(facts, subject, relation, object).
+"""
+from __future__ import annotations
+
+from src.agent.verifier import GroundedReasoner
+
+TOOL_SPEC = {
+    "name": "verify_relation",
+    "description": (
+        "Verify whether a relational claim is grounded (provable by chaining the "
+        "given atomic facts) BEFORE asserting it. Use this to catch hallucinated "
+        "multi-hop relations (e.g. ancestor/prerequisite/cause chains). Returns "
+        "grounded=false with proof=null when the claim cannot be derived, and a "
+        "proof path when it can. Costs zero model tokens and never accepts an "
+        "ungrounded claim."
+    ),
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "facts": {
+                "type": "array",
+                "description": "Known atomic (one-hop) facts as [subject, relation, object] triples.",
+                "items": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "minItems": 3,
+                    "maxItems": 3,
+                },
+            },
+            "subject": {"type": "string", "description": "Start entity of the claim."},
+            "relation": {
+                "type": "string",
+                "description": "Relation to verify transitively (e.g. 'parent' to test ancestor).",
+            },
+            "object": {"type": "string", "description": "End entity of the claim."},
+        },
+        "required": ["facts", "subject", "relation", "object"],
+    },
+}
+
+
+def openai_tool_spec() -> dict:
+    """TOOL_SPEC in OpenAI/DeepSeek/Groq (function-calling) format."""
+    return {
+        "type": "function",
+        "function": {
+            "name": TOOL_SPEC["name"],
+            "description": TOOL_SPEC["description"],
+            "parameters": TOOL_SPEC["input_schema"],
+        },
+    }
+
+
+def verify_relation(facts, subject: str, relation: str, object: str) -> dict:  # noqa: A002
+    """
+    Verify `subject --relation*--> object` from `facts`. Returns a JSON dict:
+    {grounded, proof, confidence, relation}.
+
+    Tolerant of LLM input: SKIPS any fact not shaped like [s, r, o] (instead of
+    crashing the agent), and reports the number skipped under `skipped_facts`.
+    """
+    gr = GroundedReasoner()
+    clean, skipped = [], 0
+    for t in facts or []:
+        if isinstance(t, (list, tuple)) and len(t) == 3 and all(x is not None for x in t):
+            clean.append([str(t[0]), str(t[1]), str(t[2])])
+        else:
+            skipped += 1
+    gr.add_facts(clean)
+    out = gr.verify(str(subject), str(object), via=str(relation)).as_dict()
+    if skipped:
+        out["skipped_facts"] = skipped
+    return out
+
+
+def run_tool(tool_input: dict) -> dict:
+    """Dispatcher for function-calling: takes the tool's JSON input, returns a verdict dict."""
+    return verify_relation(
+        tool_input["facts"],
+        tool_input["subject"],
+        tool_input["relation"],
+        tool_input["object"],
+    )