kaos-graph 0.1.0a2

High-performance graph library for the Kelvin Agentic OS — petgraph-backed engine, 40+ algorithms, RDF/SPARQL, knowledge-graph tools

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
# or
pip install kaos-graph

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.

Concept	What it is
Graph	Property graph backed by petgraph::StableDiGraph. String-keyed nodes with JSON-valued properties; edges with arbitrary properties; multi-graph semantics opt-in. Stable node refs across mutations (additions/removals don't invalidate handles).
Node / Edge / Triple	Typed dataclass results emitted at the FFI boundary. Node(id, properties), Edge(source, target, properties), Triple(subject, predicate, object).
Algorithms	40+ functions in kaos_graph.algorithms covering traversal (BFS/DFS, topological sort), shortest paths (Dijkstra, A*, Bellman-Ford, Floyd-Warshall), centrality (PageRank, betweenness, closeness, eigenvector), community (Louvain, label propagation), connectivity (SCC, weakly-connected, articulation points, bridges), structure (cycles, cliques, isomorphism, max flow), and DAG ops (longest path, critical path).
Sparse PageRank	O((V+E)·n) instead of petgraph's O(V²·E·n). FOLIO ontology (~25K nodes, ~36K edges): 7 ms vs petgraph's 105 s. The marketing-grade benchmark exercised on every CI run.
RDF / SPARQL	oxrdf + oxrdfio parsers (Turtle, N-Triples, N-Quads, RDF/XML, TriG) with byte / triple / size caps applied at the FFI boundary. SPARQL via pyoxigraph opt-in through the [rdf] extra.
I/O & bridges	JSON (round-trippable), GraphML / GEXF (defusedxml-hardened), edgelist, adjacency-list, mermaid, dot. NetworkX bridge; Polars / DuckDB tabular bridge planned via the [tabular] extra in 0.1.0a2.
Knowledge graph	Schema, KnowledgeGraph, fact ingestion, reasoning rules, ontology bridges.
Storage	VFS-backed save_to_vfs / load_from_vfs with name validation against namespace escape.

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 become available with pip install kaos-graph[mcp] once the kaos-mcp companion package publishes (planned for 0.1.0a2).

Compatibility & status

Aspect
Python	3.13, 3.14 (informational matrix entries for 3.14t free-threaded and 3.15-dev). One cp313-abi3 wheel per OS/arch covers all 3.13+ minors.
OS	Linux (manylinux + musllinux, x86_64 + aarch64), macOS arm64, Windows x86_64, Windows arm64. macOS x86_64 deliberately skipped (Apple ended Intel sales in 2023).
Maturity	Alpha. The public API is documented in kaos_graph.__all__.
Stability policy	Pre-1.0: minor bumps may change behaviour. Every change is documented in CHANGELOG.md.
Test coverage	173 Rust unit tests + 402 Python tests passing (575 total). 38 dedicated security regressions covering the audit-pass A2 + two follow-up rounds.
Type checker	Validated with ty, Astral's Python type checker.

Companion packages

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

Package	Layer	What it does
kaos-core	Core	Foundational runtime, MCP-native types, registries, execution engine, VFS
kaos-content	Core	Typed document AST: Block/Inline, provenance, views
kaos-mcp	Bridge	FastMCP server, kaos management CLI, MCP resource templates
kaos-pdf	Extraction	PDF → AST with provenance
kaos-web	Extraction	Web extraction, browser automation, search, domain intelligence
kaos-office	Extraction	DOCX / PPTX / XLSX readers + writers to AST
kaos-tabular	Extraction	DuckDB-powered SQL analytics
kaos-source	Data	Government + financial data connectors (Federal Register, eCFR, EDGAR, GovInfo, PACER, GLEIF)
kaos-llm-client	LLM	Multi-provider LLM transport
kaos-llm-core	LLM	Typed LLM programming (Signatures, Programs, Optimizers)
kaos-nlp-core	Primitives (Rust)	High-performance NLP primitives
kaos-nlp-transformers	ML	Dense embeddings + retrieval
kaos-graph	Primitives (Rust)	Graph algorithms + RDF/SPARQL
kaos-ml-core	Primitives (Rust)	Classical ML on the document AST
kaos-citations	Legal	Legal citation extraction, resolution, verification
kaos-agents	Agentic	Agent runtime, memory, recipes
kaos-reference	Sample	Reference module for module authors

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. By contributing you 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 [e-mail]. 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.