Migrating 0.13 → 0.14¶

kglite 0.14 focuses the package on the graph engine: the code-graph builder and the dataset loaders moved to standalone projects. The engine, Cypher, the fluent API, and the MCP server’s read-side graph tools remain. Current 0.14 releases also complete the persistence move to Postcard: they do not decode pre-0.14 bincode artifacts.

If anything broke: the two-line escape¶

pip install "kglite<0.14"

0.13.4 stays on PyPI permanently. Pin, keep working, migrate when ready.

Convert persisted data before upgrading¶

Use kglite 0.13.4 as the bridge for any artifact created with a pre-0.14 bincode layout. Current releases detect those formats and stop with migration guidance; they never guess at or partially decode the old payload.

Artifact	Migration
`.kgl` v4	Open it with 0.13.4 and call `save()` to write an RGF v5/Postcard snapshot. If you want a version-independent recovery copy, also use `export_csv(..., selection_only=False)`.
`.kgle` v1/v2	In 0.13.4, import it into the matching graph and immediately call `export_embeddings()` to write `.kgle` v3/Postcard.
Mapped/disk graph directory	Prefer rebuilding from the original source. Otherwise load it with 0.13.4 and export the complete graph with `export_csv(..., selection_only=False)`, then rebuild from `blueprint.json` under the current release.
WAL or transient property log	Finish recovery or ingestion under 0.13.4, then save a clean current snapshot. Do not copy an old sidecar into a current graph.
Vector, ID, or type-index cache	No conversion is needed. These are rebuildable caches; current readers discard pre-0.14 encodings and regenerate them when safe.

For a .kgl bridge:

python -m venv .venv-kglite013
.venv-kglite013/bin/pip install "kglite==0.13.4"

import kglite

graph = kglite.load("graph-v4.kgl")
graph.save("graph-v5.kgl")
graph.export_csv("backup/", selection_only=False)  # optional portable copy

Then install the current release and load graph-v5.kgl. CSV/blueprint is a portable node/edge/property recovery path, not a complete engine snapshot: rebuild embeddings, indexes, schema configuration, timeseries data, and other engine-specific state from their source. See the import/export guide.

What moved where¶

You used	It became
`kglite.code_tree.build(...)` / `kglite.build_code_tree(...)` / `repo_tree(...)`	The codingest project: `pip install codingest`, then `import codingest` — `codingest.build(".")` returns a `kglite.KnowledgeGraph` and `codingest.repo_tree("owner/name")` clones + builds. (codingest requires kglite ≥ 0.14.)
`kglite code-tree build/status` (CLI)	The `codingest` CLI (`cargo install codingest-cli`): `codingest build .` / `codingest status .`, then `kglite.load(...)` the `.kgl`.
MCP workspace code-graph building (`set_root_dir`, `repo_management`)	Run codingest-mcp instead of `kglite-mcp-server` — see MCP operators: swap the server binary below. `kglite-mcp-server` still serves current Postcard `.kgl` files.
`kglite.datasets.sec` / `.sodir` / `.wikidata`	`pip install kglite-datasets`, then `import kglite_datasets` — a verified drop-in (byte-identical outputs; only the import root changes).
`kglite::api::code_tree` / `kglite::api::datasets` (Rust)	The `codingest` / `kglite-datasets` crates. Read-side code-entity helpers stayed, at `kglite::api::code_entities`.
`kglite_datasets_*` C-ABI functions	Removed from `kglite-c`; pin `kglite-c` 0.13.x, or ask on the tracker if you need them exposed from kglite-datasets.

MCP operators: swap the server binary¶

If your MCP server builds code graphs from source (workspace mode — set_root_dir, repo_management, watch-mode rebuild), swap the binary from kglite-mcp-server to codingest-mcp. codingest-mcp embeds the same kglite-mcp-server tool surface and injects the code-graph builder, so every graph tool — and your <basename>_mcp.yaml manifest — behaves identically. Only the command changes:

{
  "mcpServers": {
    "code-graph": {
      "command": "codingest-mcp",
      "args": ["--root-dir", "/path/to/repo"]
    }
  }
}

The old config read "command": "kglite-mcp-server"; the tools, the manifest, and the same source root are unchanged.

Install it: cargo install codingest-mcp, or grab a prebuilt binary from github.com/kkollsga/codingest/releases.
Rollback: keep the old kglite-mcp-server binary on disk (or pip install "kglite<0.14") and point command back at it.
Just serving a current .kgl? Nothing to do. kglite-mcp-server --graph path/to/graph.kgl serves current Postcard graphs — including codingest-built ones — with every read-side tool. Convert a pre-0.14 graph first using the bridge above. The server swap is only needed when it must build a graph from source.

What did NOT change¶

Current .kgl files move between kglite and companion projects in both directions — graphs built by codingest/kglite-datasets are ordinary kglite graphs. Pre-0.14 persistence still requires the 0.13.4 bridge above.
Code-graph reading: graph.source(), graph.find(), graph.context(), the read_code_source/explore MCP tools, and the rev_diff/affected_tests/dead_code procedures all work on codingest-built graphs.
load_rdf, OKF ingestion, graphgen, blueprints — all still built in.

Why¶

The wheel dropped from 40.3 MB to 18.0 MB, the engine now links zero network code (the entire HTTP/TLS closure left with the loaders), and the builder/loader projects can release on their own cadence. Extraction fidelity is enforced by frozen golden digests captured while both copies were verified byte-identical.