kaos-graph

Part of Kelvin Agentic OS (KAOS) — open agentic infrastructure for legal work, built by 273 Ventures. See the full KAOS package map for the rest of the stack.

kaos-graph is a high-performance graph library for KAOS — a typed Python API over a pure-Rust core backed by petgraph and the oxrdf RDF engine. It provides the graph-algorithm and knowledge-graph building blocks the rest of the stack relies on: 40+ algorithms (PageRank, shortest paths, centrality, community detection, DAG ops), RDF/SPARQL parsing, and typed Python wrappers throughout.

It is dependency-light: the BASE install pulls only kaos-graph itself plus defusedxml (~250 KB pure-Python). Optional extras layer in the rest of the KAOS ecosystem.

Install

uv add "kaos-graph>=0.1.0"
# or
pip install "kaos-graph>=0.1.0"

kaos-graph requires Python 3.13 or newer. The published wheels are cp313-abi3 — one wheel per OS/architecture covers every CPython 3.13+ minor (3.13, 3.14, 3.15, …). No re-release needed when 3.15 ships.

Platform coverage: Linux x86_64 (manylinux + musllinux), Linux aarch64 (manylinux + musllinux), macOS arm64, Windows x86_64, Windows arm64.

Quick start

from kaos_graph import Graph
from kaos_graph.algorithms import pagerank, shortest_paths, topological_sort

g = Graph()
g.add_node("alice", role="engineer")
g.add_node("bob", role="manager")
g.add_edge("alice", "bob", relationship="reports_to")

# Algorithms
ranks = pagerank(g)
costs = shortest_paths(g, "alice")
order = topological_sort(g)

Concepts

The package is built around a small set of typed primitives.

CLI

kaos-graph ships a kaos-graph administrative CLI plus an optional kaos-graph-serve MCP server (loopback-only by default):

kaos-graph version          # version info
kaos-graph serve            # forwards to kaos-graph-serve (stdio MCP)
kaos-graph-serve            # MCP server, stdio transport
kaos-graph-serve --http     # MCP server, streamable HTTP (loopback only)

Note: 17 MCP tools are registered by register_graph_tools() and are available with pip install "kaos-graph[mcp]>=0.1.0" (pulls in kaos-mcp).

Compatibility & status

Documentation

Per-package reference: docs/ in this repo.

Cross-cutting KAOS guides (agentic patterns, persona presets, settings policy, citations, MCP data flow, migration to 0.1.0 GA) live in kaos-modules/docs/guides/.

Companion packages

kaos-graph is one of the packages in the Kelvin Agentic OS. The broader stack:

Packages depend on kaos-core; everything else is opt-in. Mix and match the ones you need.

Development

git clone https://github.com/273v/kaos-graph
cd kaos-graph
uv sync --group dev --extra rdf
uv run maturin develop --release

Install pre-commit hooks (recommended — they run the same checks as CI on every commit, scoped to staged files):

uvx pre-commit install
uvx pre-commit run --all-files     # one-time full sweep

Manual QA commands (the same set CI runs):

cargo fmt --check
cargo clippy --no-default-features --all-targets -- -D warnings
cargo test --no-default-features --lib
uv run ruff format --check python/kaos_graph tests
uv run ruff check python/kaos_graph tests
uv run ty check python/kaos_graph tests
uv run pytest tests/

Build from source

uv build
uv pip install dist/*.whl

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for setup, quality gates, pull request expectations, and engineering standards. By contributing you agree to follow the project conduct expectations and certify the Developer Certificate of Origin v1.1 — sign every commit with git commit -s. Please open an issue before starting on a non-trivial change so we can align on scope.

Security

For security issues, please do not file a public issue. Report privately via GitHub Private Vulnerability Reporting or email security@273ventures.com. See SECURITY.md for the full disclosure policy.

License

Apache License 2.0 — see LICENSE and NOTICE.

Copyright 2026 273 Ventures LLC. Built for kelvin.legal.