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 fast decision model 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.

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

Decisions use the Jev model, through OpenRouter (OPENROUTER_API_KEY) or TypeSafe (TYPESAFE_API_KEY). Without either, GRAPHWALK_DECISION_FALLBACK=llm lets any chat model decide (slower, not calibrated).

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.1). The public API is what graphwalk exports; submodules may change between minor versions. Results are from small samples, mostly one seed. The decision model (Jev) is a hosted model from TypeSafe; this project has no affiliation with TypeSafe, and the LLM-decider fallback keeps it usable without Jev.

Development

See CONTRIBUTING.md.

License

Apache-2.0. See LICENSE.