API reference¶

The curated, documented surface — kglite::api::*. Items outside this surface (kglite::graph::*, kglite::datatypes::*, etc.) are implementation details and may move in any release. See Stability policy for what pre-1.0 guarantees.

For per-symbol API docs (function signatures, struct fields, trait method docs), use docs.rs/kglite. This page is the curated inventory. If you’re building a library that produces kglite graphs, see Building on kglite.

Stability policy¶

kglite::api::* — and the kglite-mcp-server library surface — are exact-baseline-locked in CI (cargo-public-api, pinned nightly): accidental drift cannot merge, because the generated public-API listing is diffed against a committed baseline on every PR. The include/kglite.h C header is drift-checked the same way (cbindgen vs the committed header).

Pre-1.0, the policy is:

Any release, including a PATCH, may ship a documented breaking change. KGLite’s crates ship in lockstep and deliberately ship breaking engine changes in patch bumps; the version number is not a compatibility signal. Every intentional break ships with a CHANGELOG.md entry naming the removed items and their replacements — the changelog, not the bump size, is the migration contract. Embedders should pin an exact version (kglite = "=X.Y.Z") and upgrade against the changelog. (This paragraph previously promised “patch releases never break the API”; 0.15.9 removed public items in a patch, per the actual policy, and this page was the outlier.)
New options land under 0.14’s options-struct convention (*Options structs, #[non_exhaustive] + Default), so adding an option is a non-breaking change rather than a signature break.

1.0 criterion: the 0.14 surface — after the options-struct pass on api::algorithms — soaks across releases without needing a breaking correction. When the curated facade proves stable in the field, we cut 1.0 and the pre-1.0 “any release may break” latitude ends.

Engine types¶

Item	Path	Purpose
`DirGraph` / `KnowledgeGraph`	`kglite::api::*`	Core graph handle/storage wrapper spanning memory, mapped, and disk modes.
`GraphRead` / `GraphWrite`	`kglite::api::*`	Storage-independent read/mutation traits; `GraphRead` is GAT-based and not object-safe.
Storage/config types	`kglite::api::storage::*`	Mode selection, construction, and lifecycle configuration.
`Value`	`kglite::api::Value`	Every value Cypher can return: scalars, `List`, `Map`, `Node`, `Relationship`, `Path`, ….
`NodeValue` / `PathValue` / `RelValue`	`kglite::api::*`	Per-variant carriers; pattern-match into them without deriving accessors.
`KgError` / `KgErrorCode`	`kglite::api::KgError`, `KgErrorCode`	Typed errors with 17 stable codes including cancellation. Map code/message/status through the binding.
`Embedder` (trait)	`kglite::api::Embedder`	Pluggable text-embedding backend for `text_score()` Cypher.
`FastEmbedAdapter` (feature `fastembed`)	`kglite::api::FastEmbedAdapter`	Rust-native ONNX embedder.
`SourceLocation` / `SourceLookup`	`kglite::api::*`	Code-entity location lookup result types.
`ExploreOptions` / `explore_markdown`	`kglite::api::*`	Codebase exploration as a markdown report.

I/O¶

Item	Path	Purpose
`load_file(path)`	`kglite::api::io::load_file`	Read a `.kgl` file (or disk dir) → `io::Result<Arc<DirGraph>>`.
`load_kgl_bytes(&[u8])`	`kglite::api::io::load_kgl_bytes`	Load an in-memory graph from a `.kgl` byte buffer (counterpart of `write_kgl_to`).
`save_graph(&mut arc, path)`	`kglite::api::io::save_graph`	Write an `Arc<DirGraph>` → `Result<(), String>`.
`write_kgl` / `write_kgl_with(..., fsync)`	`kglite::api::io::write_kgl*`	Atomic (temp+rename) + durable (`fsync`) `.kgl` write. `write_kgl_with` toggles the flush.
`write_kgl_to(&graph, &mut writer)`	`kglite::api::io::write_kgl_to`	Serialize the `.kgl` byte stream into any `Write` (backs `to_bytes`).

DirGraph::copy_embeddings_from(&src) carries embedding stores across a rebuild by node id (the core behind the Python copy_embeddings_from). The other new 0.11.0 methods — embedding_info / embedding_dim, replace_connections, embed_texts(mode=…), freeze — are binding-surface (Python KnowledgeGraph) methods, documented in the Python track, not raw kglite::api functions.

Schema introspection¶

Item	Path	Purpose
`compute_description(...)`	`kglite::api::introspection::compute_description`	XML schema description for agent system prompts.
`compute_schema(&dir)`	`kglite::api::introspection::compute_schema`	Structured `SchemaOverview` (node types, edge types, indexes).
`SchemaOverview`, `ConnectionDetail`, `CypherDetail`, `FluentDetail`	`kglite::api::*`	Structured introspection types.

Cypher pipeline (`kglite::api::cypher`)¶

For building custom pipelines. For the canonical pipeline, use the session module instead.

Item	Purpose
`parse_cypher(query)`	Parse a query string → `CypherQuery`. Uses the global cache.
`validate_schema(&parsed, &graph)`	Schema-check a parsed query against a graph.
`rewrite_text_score(...)`	Lower `text_score()` references into vector lookups.
`mark_lazy_eligibility(&mut parsed)`	Mark queries eligible for streaming materialization.
`optimize(...)` / `planner::*`	Run the optimizer passes; introspect the pipeline.
`CypherExecutor`	Execute a planned query against a graph.
`execute_mutable(...)`	Mutation execution path.
`is_mutation_query(&parsed)`	Heuristic: does this query mutate?
`generate_explain_result(...)`	Build an EXPLAIN-style plan as a CypherResult.
`CypherQuery`, `CypherResult`, `OutputFormat`	Data types.

Session (canonical query + transaction surface)¶

The canonical query and transaction pipeline for Rust-side bindings.

Item	Path	Purpose
`Session`	`kglite::api::session::Session`	Shared graph state with commit-swap semantics.
`Transaction`	`kglite::api::session::Transaction`	Snapshot/working CoW transaction state.
`CommitOutcome`	`kglite::api::session::CommitOutcome`	`NoWritesNoOp` / `Committed{new_version}` / `ConflictDetected{current_version, base_version}`.
`ExecuteOptions`	`kglite::api::session::ExecuteOptions`	Params, deadline, row/work budget, lazy hint, disabled passes, embedder, value codecs, cancellation, write scope, and provenance.
`ExecuteOutcome`	`kglite::api::session::ExecuteOutcome`	`result: CypherResult` + `is_mutation: bool` + `output_format: OutputFormat`.
`execute_read(&graph, query, &opts)`	`kglite::api::session::execute_read`	Run a read query.
`execute_mut(&mut graph, query, &opts)`	`kglite::api::session::execute_mut`	Run a mutation.

Dataset loaders¶

The pre-packaged dataset loaders (SEC EDGAR, Sodir, Wikidata) are no longer part of the kglite core API surface — they live in the separate kglite-datasets project, and kglite::api::datasets::* (and the sec / sodir / wikidata Cargo features) have been removed. kglite loads the graphs those loaders produce via the ordinary lifecycle API. To ingest RDF directly, use the kept RDF/N-Triples loaders.

Semver¶

kglite::api::* items above are the documented surface: locked against accidental drift by the CI API baseline, and every intentional break is announced in CHANGELOG.md. Pre-1.0 that break may arrive in any release, including a patch — see Stability policy. Anything outside that surface — kglite::graph::*, kglite::datatypes::*, raw module paths — is internal and may move freely in any release.

Change kind	Bumps
Additive item/options field in `api::*`	Patch or minor, with API baseline update
Intentional breaking change before 1.0	Any release, patch included, plus changelog/migration guidance
Internal rearrangement (non-api items)	Patch

The .kgl format is versioned separately from the source API. The current writer emits RGF v6/Postcard and the reader accepts v6 and v5. RGF v4/bincode and older containers are rejected with a clear migration/rebuild path. Convert pre-0.14 artifacts with kglite 0.13.4 before handing them to a current binding.

Where to find each item¶

kglite::                    (the crate root)
├── api::                   (this stable surface)
│   ├── cypher::            (parse / plan / execute primitives)
│   └── session::           (canonical Cypher pipeline + transactions)
├── datatypes::             (internal — use api::Value)
├── error                   (internal — use api::KgError)
├── graph::                 (internal — engine submodules)