graphwalk

Cheap, confidence-scored question answering over a knowledge graph you already have. Python library, CLI, and MCP server for agents.

graphwalk answers a question by walking the graph from the entities it names. Each hop is a constrained classification decision: the current node's relations, plus STOP, are the options, and a decider returns a probability for each. So every answer comes with a path and a confidence, and you can escalate the unsure ones to a stronger model.

Bring your own decider. graphwalk is the machinery (options, walks, confidence, escalation, the MCP tools); the decider plugs in:

• Jev (default), TypeSafe's classification model: the fastest we measured.
• Any model that returns token probabilities, at any OpenAI-compatible endpoint (OpenRouter, vLLM, llama.cpp, OpenAI). With Qwen3.8-27B (open weights) it matched Jev's accuracy and confidence quality, at about 10× the latency through OpenRouter; other models vary, so check yours.
• Your own: anything implementing DecisionBackend (a fine-tuned classifier, a cross-encoder). See deciders.

pip install graphwalk
graphwalk import kg.nt --graph kg.db          # triples: CSV, TSV, JSONL, N-Triples; no key needed
graphwalk query kg.db "Where was the director of Inception born?" --escalate-below 0.9

When to use it (measured)

Every number below comes from an experiment in docs/, on samples of 30–300 questions. Treat them as directions, not guarantees.

graphwalk does not claim to be more accurate than an LLM. What it offers is a cheap first answer that knows when it might be wrong.

Quickstart

The default decider is Jev, through OpenRouter (OPENROUTER_API_KEY) or TypeSafe (TYPESAFE_API_KEY). GRAPHWALK_DECIDER=logprob decides with an open-weights model's token probabilities instead (on OpenRouter by default, or your own server via GRAPHWALK_DECIDER_BASE_URL).

import asyncio
from graphwalk import Index


async def main() -> None:
    async with Index.open("kg.db", escalate_below=0.9) as index:
        await index.import_triples("kg.nt")  # idempotent
        result = await index.walk("Where was the director of Inception born?")
        print(result.best.names, result.confidence, result.escalated, result.cost_usd)


asyncio.run(main())

A runnable example over a 15-triple movie graph is in examples/kg/.

For agents (MCP)

pip install 'graphwalk[mcp]'
claude mcp add --env OPENROUTER_API_KEY=sk-or-... graphwalk -- graphwalk mcp --db kg.db

Tools: walk (answers, paths, confidence), neighbors, get_node, status, plus locate/read/ingest for text. The usual loop: call walk first; at confidence 0.9 or above, take the answer; below it, check it with neighbors or escalate. The server also runs over HTTP with bearer or OAuth 2.1 auth, and ships as a container. See MCP setup.

The package carries its own guide for coding agents: graphwalk guide (or graphwalk guide --skill for a SKILL.md), and llms.txt.

Install options

Documentation

• Docs site: quickstart, agents and MCP, configuration, text ingestion, evidence.
• Results: every experiment, with CIs, costs, and the runs behind it.
• Design record and roadmap.

Status

Alpha (v0.3). The public API is what graphwalk exports; submodules may change between minor versions. Results are from small samples, mostly one seed. Jev is a hosted model from TypeSafe; this project has no affiliation with TypeSafe, and does not depend on it: any model with token probabilities can decide.

Development

See CONTRIBUTING.md.

License

Apache-2.0. See LICENSE.