Metadata-Version: 2.4
Name: kgviz
Version: 0.2.0
Summary: 3D knowledge graph visualization for Python — Jupyter, Streamlit, Gradio, Dash, and more
License: MIT
Project-URL: Homepage, https://github.com/dataprofessor/kgviz
Project-URL: Repository, https://github.com/dataprofessor/kgviz
Project-URL: Issues, https://github.com/dataprofessor/kgviz/issues
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: streamlit
Requires-Dist: streamlit>=1.30; extra == "streamlit"
Provides-Extra: networkx
Requires-Dist: networkx>=3.0; extra == "networkx"
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == "pandas"
Provides-Extra: jupyter
Requires-Dist: ipython>=8.0; extra == "jupyter"
Provides-Extra: gradio
Requires-Dist: gradio>=4.0; extra == "gradio"
Provides-Extra: dash
Requires-Dist: dash>=2.0; extra == "dash"
Provides-Extra: marimo
Requires-Dist: marimo>=0.8; extra == "marimo"
Provides-Extra: maps
Requires-Dist: numpy>=1.24; extra == "maps"
Requires-Dist: scikit-learn>=1.3; extra == "maps"
Requires-Dist: umap-learn>=0.5; extra == "maps"
Requires-Dist: minisom>=2.3; extra == "maps"
Provides-Extra: all
Requires-Dist: streamlit>=1.30; extra == "all"
Requires-Dist: networkx>=3.0; extra == "all"
Requires-Dist: pandas>=2.0; extra == "all"
Requires-Dist: ipython>=8.0; extra == "all"
Requires-Dist: gradio>=4.0; extra == "all"
Requires-Dist: dash>=2.0; extra == "all"
Requires-Dist: marimo>=0.8; extra == "all"
Requires-Dist: numpy>=1.24; extra == "all"
Requires-Dist: scikit-learn>=1.3; extra == "all"
Requires-Dist: umap-learn>=0.5; extra == "all"
Requires-Dist: minisom>=2.3; extra == "all"
Provides-Extra: dev
Requires-Dist: networkx>=3.0; extra == "dev"
Requires-Dist: pandas>=2.0; extra == "dev"
Requires-Dist: streamlit>=1.30; extra == "dev"
Requires-Dist: ipython>=8.0; extra == "dev"
Requires-Dist: numpy>=1.24; extra == "dev"
Requires-Dist: scikit-learn>=1.3; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: playwright>=1.40; extra == "dev"
Dynamic: license-file

# kgviz

3D knowledge graph visualization for Python — works like Plotly/Altair across Jupyter notebooks, Streamlit, Gradio, Dash, marimo, and plain HTML export.

**Repository:** [github.com/dataprofessor/kgviz](https://github.com/dataprofessor/kgviz)

## Project layout

```
kgviz/       Python wrapper — data prep, HTML export, framework adapters
viewer/      Browser component — React/Three.js 3D renderer (see viewer/README.md)
example/     Streamlit demo
AGENTS.md    Architecture guide for contributors and coding agents
```

## Install

**Python** (pip):

```bash
pip install kgviz
pip install "kgviz[all]"    # Streamlit, Jupyter, maps, etc.
```

**Node CLI** ([npm](https://www.npmjs.com/package/kgviz)) — no Python required for HTML export and session maps:

```bash
# One-off (no install) — good for trying it
npx kgviz help

# Or install globally and run `kgviz` directly
npm install -g kgviz
kgviz help
```

## Quick start

```python
from kgviz import Graph3D, kgviz

nodes = [
    {"id": "A", "label": "Alpha", "color": "#ff0000", "size": 5},
    {"id": "B", "label": "Beta", "color": "#00ff00", "size": 4},
    {"id": "C", "label": "Gamma", "color": "#0000ff", "size": 3},
]
edges = [
    {"source": "A", "target": "B"},
    {"source": "B", "target": "C"},
]

fig = Graph3D(nodes=nodes, edges=edges, show_labels=True)
fig.show()          # Jupyter cell or browser
fig.to_html()       # embed anywhere
```

### Knowledge-graph preset

```python
from kgviz import Graph3D

fig = Graph3D.kg_preset(
    nodes=nodes,
    edges=edges,
    node_color_by="type",
    node_size_by="degree",
    edge_color_by="relation",
    edge_width_by="weight",
    edge_label="label",
    show_edge_labels=True,
    show_legend=True,
)
```

**Explorer features:** schema legend (click to filter), multi-property search, multi-select, double-click neighborhood focus, typed edge labels/colors/widths, selection events for Streamlit sidebars.

### Embedding maps (PCA, t-SNE, UMAP, SOM)

Cosmograph-style 2D scatter maps from feature vectors (paper embeddings, node attributes, etc.):

```bash
pip install "kgviz[maps]"   # numpy, scikit-learn, umap-learn, minisom
```

```python
from kgviz import Graph3D
import numpy as np

nodes = [{"id": i, "label": f"Doc {i}", "topic": i % 5} for i in range(200)]
features = np.random.randn(200, 32)   # or sentence-transformer embeddings

fig = Graph3D.from_map(
    nodes,
    features,
    method="tsne",          # pca | tsne | umap | som
    node_color_by="topic",  # or cluster from auto k-means
    knn_k=0,                # 3 for light KNN overlay like Topic Explorer
)
fig.show()
```

Lower-level API: `from kgviz.layouts import compute_layout, build_map_graph, apply_layout_to_nodes`.

**Large maps (10k–100k+ points):** `map_mode` draws points on a **canvas overlay** (2D scatter or 3D orbit). Performance tiers automatically reduce labels and effects on big datasets. Regular knowledge graphs still use the **Three.js** 3D renderer for force-directed layouts.

```bash
python3 example/generate_map_demo_large.py   # demo_map_10k.html, demo_map_50k.html
```

### AI coding session maps (example use case)

Explore **where your agent conversations cluster** — by topic, project, or tool — as an interactive 2D/3D embedding map. Each point is a message turn or whole session (with `--per-session`).

| Tool | Default data path | What gets read |
|------|-------------------|----------------|
| **Snowflake Cortex Code** | `~/.snowflake/cortex/conversations/**/*.history.jsonl` | Cortex agent chats |
| **Cursor IDE** | `~/.cursor/projects/*/agent-transcripts/**/*.jsonl` | Cursor agent transcripts |
| **Claude Code (CLI)** | `~/.claude/projects/<project>/*.jsonl` | Claude Code session logs ([local storage](https://kentgigger.com/posts/claude-code-conversation-history)) |

**Python** (full t-SNE / UMAP on large histories):

```bash
pip install "kgviz[maps]"

# Cortex Code (default)
python3 example/generate_map_demo_sessions.py --per-session

# Cursor IDE transcripts
python3 example/generate_map_demo_sessions.py --source cursor --per-session --color-by project

# Claude Code CLI
python3 example/generate_map_demo_sessions.py --source claude --per-session

# All sources on one map
python3 example/generate_map_demo_sessions.py --source all --color-by source

python3 serve_demo.py   # → http://127.0.0.1:8765/demo_map_sessions_tsne.html
```

Options: `--per-session`, `--color-by topic|source|workspace|project`, `--method pca` for faster layout. Session HTML files are **gitignored** (private chat text) — generate locally only.

### Node CLI (npm / npx)

Package: **[kgviz on npm](https://www.npmjs.com/package/kgviz)** (`npx` = run without installing; `npm install -g` = install the `kgviz` command).

```bash
# Either form works:
npx kgviz build graph.json -o graph.html
kgviz build graph.json -o graph.html          # after: npm install -g kgviz

npx kgviz sessions --per-session -o sessions.html
npx kgviz sessions --source claude --color-by project
npx kgviz sessions --source all --color-by source
npx kgviz serve sessions.html
```

See [packages/kgviz/README.md](packages/kgviz/README.md) for all flags.

## Framework usage

### Jupyter / IPython

```python
fig  # auto-displays via _repr_html_
```

### Streamlit

```python
import streamlit as st
from kgviz import kgviz

click = kgviz(nodes=nodes, edges=edges, key="graph")
```

### Gradio

```python
import gradio as gr
from kgviz import Graph3D
from kgviz.integrations import gradio_html

fig = Graph3D(nodes=nodes, edges=edges)
gr.HTML(gradio_html(fig))
```

### Dash

```python
from kgviz import Graph3D
from kgviz.integrations import dash_iframe

fig = Graph3D(nodes=nodes, edges=edges)
layout = dash_iframe(fig, height=600)
```

## Standalone HTML demo

```bash
cd /path/to/kgviz
python3 serve_demo.py
```

Open **http://127.0.0.1:8765/demo.html** (must use `serve_demo.py` or `cd example` before `python3 -m http.server`).

## Development

```bash
cd viewer && npm install && npm run build
pip install -e ".[dev,all]"
python3 -m pytest tests/ -q
python3 -m playwright install chromium   # once, for browser tests
python3 -m pytest tests/test_browser_playwright.py -q
streamlit run example/app.py
```

**Notebook demo:** `example/notebook_demo.ipynb`
