kglite-visual: see a knowledge graph, and let an agent drive it

PyPI version Python versions License: MIT Docs

kglite-visual is an interactive viewer, a headless renderer and an agent interface for .kgl knowledge-graph files produced by KGLite. One command opens a browser on a localhost server; the same binary draws an image without one; and while the server runs it speaks the Model Context Protocol, so an agent can drive the window you are looking at.

The Python wheel has no required runtime dependencies: the graph engine, the HTTP server and the WebGL frontend bundle are all inside one compiled extension. No Node, no separate server process, no database service.

Quick Start

pip install kglite-visual
kglite-visual graph.kgl        # opens a browser on localhost

What you land on is not the graph. .kgl files reach 100M+ nodes and no browser renders that, so the entry screen is the type-level meta-graph — the labels and relationship types with their counts, always small whatever sits underneath — and you drill in from there with Cypher and bounded neighbourhood expansion.

144 fields drawn where they actually are, on a real coastline at the scale the frame can resolve

Above: kglite-visual render graph.kgl --cypher "MATCH (f:Field) RETURN f" --layout geo. No tiles, no network — the coastline ships in the binary.

Two more commands, no server and no browser in either:

kglite-visual render graph.kgl --meta -o schema.svg      # one image, one JSON line
kglite-visual export graph.kgl --format gexf -o out.gexf # one file for somebody else's tool

Then hand the running server to an agent. The MCP endpoint is on the same port, and its URL is printed on the same stdout line as everything else:

{"url":"http://127.0.0.1:54137/","port":54137,"pid":69850,"graph":"graph.kgl","mcp":"http://127.0.0.1:54137/mcp"}

→ Getting started · Agents and MCP.

What makes it different

Three things this does that a graph viewer normally does not.

An agent drives the window you are watching. The running server speaks MCP at /mcp — no second process to start, no discovery file, nothing to install: attaching an agent is pointing it at a URL. Thirteen tools act on one shared view, last writer wins: read what is on screen, put a Cypher result into it, expand or collapse, highlight, zoom, recolour, re-lay-out, export it, draw a picture of it, and run the queries you saved under the names you chose. Whoever changes the view — you, the agent, a curl — every connected window sees the change immediately. Watching an agent expand a type and zoom to what it found is the feature, not a side effect of it. → Agents and MCP.

The honesty model: truncation is drawn into the picture. A graph viewer is a machine for showing you less than there is, and the design position here is that the subset must name itself. The response bound lives in core, not in the UI — a guarantee the client implements is not a guarantee — so a curl, an agent and a second tab all hit the same ceiling. Every bounded answer carries {returned, total, truncated}; a slice carries two of those, because nodes and links share one byte budget and a complete node list can sit beside an incomplete link list. And because an image travels without its response, the banner is drawn into the image, beside three more counts for the other ways a picture can be less than its input: types_shown (a canvas too small for the schema draws the largest types and says top 24 of 98), names_shown (labels that lost their cell keep their circle and lose their name), and folded (a fan too big to read is one wedge saying how big it is). → The honesty model.

Layouts chosen from the graph's own structure — including a real map. A force layout is the right tool for a graph with no discoverable shape and the wrong one for a star, a bipartite result or a schema with disconnected families, which is most of what a real graph hands it. So a neighbourhood is drawn as hop rings, a community-structured graph as packed islands with a quiet boundary round each, and unattached nodes as one labelled grid. And where the nodes carry coordinates there is --layout geo: an equirectangular projection whose longitudes are corrected by the cosine of the data's mid-latitude — so a shelf at 68°N comes out its own shape rather than 2.7× too wide — over the world's real coastline at three scales chosen by how much of the world the frame covers, so a North Sea crop gets the fjords and a world map does not carry 400,000 points nothing can resolve. Nodes with no coordinate go in a labelled tray with a count, never dropped. → Layouts.

From Python, and from a notebook

import kglite_visual as kv

view = kv.show("graph.kgl")     # the same server, in-process
view.url                        # 'http://127.0.0.1:54137/'
view.launch_info                # {'url', 'port', 'pid', 'graph', 'mcp'}
view.close()                    # stops it, frees the port

# Or hand over an in-memory kglite graph — through to_bytes(), never the disk.
import kglite
view = kv.show(kglite.load("graph.kgl"))

In a notebook the returned object renders itself in the cell: a proxy-prefixed iframe where jupyter-server-proxy can reach the port, and no iframe at all — the URL plus an ssh -N -L hint — where the kernel looks remote, because a localhost iframe from a remote kernel is a silently blank frame.

show(path) is the large-graph answer: handing over an in-memory graph costs about 2× the graph's size at the moment of the call. → Python API.

Render and export

# an image: --meta, --cypher "…" or --expand type=T rel=R dir=out
kglite-visual render graph.kgl --meta -o schema.svg
kglite-visual render graph.kgl --cypher "MATCH (f:Field) RETURN f" --layout geo --format png

# a file: graphml | gexf | csv | csv-edges | json
kglite-visual export graph.kgl --format gexf -o graph.gexf
kglite-visual export graph.kgl --format csv --cypher "MATCH (n:Field) RETURN n"

The render's layout is seeded and deterministic — the same request produces the same bytes, forever — so --seed is how you get a different arrangement of the same data, and an exact golden baseline is possible at all. Each command writes its file and prints one JSON line describing it; nothing else ever touches stdout. → Render · Export.

Requirements

CPython 3.10+ (one abi3 wheel serves every version from 3.10 up) on macOS, Linux and Windows, plus a .kgl file written by a matching KGLite release — this version pins kglite 0.16.17. Building from source additionally needs a Rust toolchain; the published wheels and the source distribution both carry a prebuilt frontend, so neither needs Node at install time.

Documentation

Full docs at kglite-visual.readthedocs.io.

Rendering is cosmos.gl (MIT, OpenJS Foundation): a WebGL GPU force layout, fed over a binary protocol — typed-array buffers for topology and positions, JSON for metadata.

Stability

Alpha, pre-1.0. The launch contract (one JSON line: url, port, pid, graph, mcp), the render and export summary lines, and the MCP tool names are the surfaces to depend on; everything else may move. CHANGELOG.md records what a user can see change.

License

MIT — see LICENSE.

Project links

Data verified by PyPI on Aug 31, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.1.7)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for kkollsg from gravatar.com kkollsg

Credits

Author: Kristian dF Kollsgård

GitHub Statistics

Data verified by PyPI on Aug 31, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Tags

graph knowledge-graph visualization webgl kglite

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

kglite_visual-0.1.3.tar.gz (2.7 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

kglite_visual-0.1.3-cp310-abi3-win_amd64.whl (10.0 MB view details)

Uploaded CPython 3.10+Windows x86-64

kglite_visual-0.1.3-cp310-abi3-musllinux_1_2_x86_64.whl (10.1 MB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ x86-64

kglite_visual-0.1.3-cp310-abi3-musllinux_1_2_aarch64.whl (9.5 MB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ ARM64

kglite_visual-0.1.3-cp310-abi3-manylinux_2_28_aarch64.whl (9.3 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.28+ ARM64

kglite_visual-0.1.3-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (9.9 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ x86-64

kglite_visual-0.1.3-cp310-abi3-macosx_11_0_arm64.whl (9.0 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

kglite_visual-0.1.3-cp310-abi3-macosx_10_12_x86_64.whl (9.5 MB view details)

Uploaded CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file kglite_visual-0.1.3.tar.gz.

File metadata

  • Download URL: kglite_visual-0.1.3.tar.gz
  • Upload date:
  • Size: 2.7 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for kglite_visual-0.1.3.tar.gz
Algorithm Hash digest
SHA256 9ea1a62ae10cf74cabcf58bd902f24a857e5716deba9caf979bdb6e27ec93866
MD5 f6a7081babab21873f31f0d2d859d0e6
BLAKE2b-256 ba33fece4c7124dd59eb9b66c0de6c4b25c0bf556ce2073f2a351e58ca8dd3d8

See more details on using hashes here.

Provenance

The following attestation bundles were made for kglite_visual-0.1.3.tar.gz:

Publisher: release.yml on kkollsga/kglite-visual

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file kglite_visual-0.1.3-cp310-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for kglite_visual-0.1.3-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 ac1cd23ae32294c399a804f0140891ee8f6c6fafed18f02aa50c98edd651056e
MD5 0d3d02e57bf7773173ebe50ac5acbe76
BLAKE2b-256 f7e6e4f7f31d06b10f65b04273e000b05a6441eebd5b1b16beb70a9eb8e8e8f1

See more details on using hashes here.

Provenance

The following attestation bundles were made for kglite_visual-0.1.3-cp310-abi3-win_amd64.whl:

Publisher: release.yml on kkollsga/kglite-visual

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file kglite_visual-0.1.3-cp310-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for kglite_visual-0.1.3-cp310-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 cc74b079869dd27b6205fbd2bcfc877364635277a68f4ef21e18d7fc8beeafae
MD5 f48b8a7b0b8606fd61e7e40bc0d773d4
BLAKE2b-256 ad1eb18c9075fd4df50c8ccdbefaac4cfb2b2025738bee0ea7743e2dc12bd807

See more details on using hashes here.

Provenance

The following attestation bundles were made for kglite_visual-0.1.3-cp310-abi3-musllinux_1_2_x86_64.whl:

Publisher: release.yml on kkollsga/kglite-visual

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file kglite_visual-0.1.3-cp310-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for kglite_visual-0.1.3-cp310-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 6e8220642d371143216efa58db1110cab854ac0e4c1bedde6b6a10f568b0bbd6
MD5 866caf8aea8f91f8af95ce6c08245a2a
BLAKE2b-256 daf9684760c059ae4eb59b6c0f36fa02233eb250da7748c8755523cfc7797b3e

See more details on using hashes here.

Provenance

The following attestation bundles were made for kglite_visual-0.1.3-cp310-abi3-musllinux_1_2_aarch64.whl:

Publisher: release.yml on kkollsga/kglite-visual

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file kglite_visual-0.1.3-cp310-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for kglite_visual-0.1.3-cp310-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 50bfcb6cc3338426c99186bd4ddb301e9a955809591343044f914bafe6507aab
MD5 a58c3ef54a88d05f73fc69f9c9ec2098
BLAKE2b-256 b4af11b744ec00180739ed5a05ef24682f752c1f644a598dd76388e1c3cc4579

See more details on using hashes here.

Provenance

The following attestation bundles were made for kglite_visual-0.1.3-cp310-abi3-manylinux_2_28_aarch64.whl:

Publisher: release.yml on kkollsga/kglite-visual

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file kglite_visual-0.1.3-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for kglite_visual-0.1.3-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 db4b3b828abe5532120ee2d0992e664fc455fb1a40ea89f218eac6b85fcf6c64
MD5 720d8f0cab1c067e6d5f8e7cc5df0e4c
BLAKE2b-256 b567c24f69a20753431ca28751fca8aa60bb81993d26ac2572115148149997cc

See more details on using hashes here.

Provenance

The following attestation bundles were made for kglite_visual-0.1.3-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on kkollsga/kglite-visual

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file kglite_visual-0.1.3-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for kglite_visual-0.1.3-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 bbdef8247d01e534f9b85a1fc6aa26cb6aedeb124e6227fea78122878fb56699
MD5 76cdc538fcccc887fa37dd92d31e6cf1
BLAKE2b-256 d80d932647e20bc1bf5a7f018ed991dd96cf9bdacacd92c8d177ee56c4a1db75

See more details on using hashes here.

Provenance

The following attestation bundles were made for kglite_visual-0.1.3-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on kkollsga/kglite-visual

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file kglite_visual-0.1.3-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for kglite_visual-0.1.3-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 7eab7a2e66ff39e052f15b6a7f08c5c9af9007731fba6ef8985ea59f86d86952
MD5 9791e61515bb9e98ba5f8ff0a6503f8c
BLAKE2b-256 014b0a6725a8997ba02b128f6e9521da2de5d85239008590ae3d9ecaab6fc439

See more details on using hashes here.

Provenance

The following attestation bundles were made for kglite_visual-0.1.3-cp310-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on kkollsga/kglite-visual

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.1.7

8 files

0.1.6

8 files

0.1.5

8 files

0.1.4

8 files

This release

0.1.3 This release

8 files

0.1.2

8 files

0.1.1

8 files

0.1.0

8 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page