Metadata-Version: 2.3
Name: graphwiki
Version: 0.1.0
Summary: Graph-grounded code wiki generator: deterministic traversal, LLM writes prose only.
Keywords: documentation,wiki,code-graph,llm,developer-tools
Author: Mayur Pise
Author-email: Mayur Pise <mayurpise@gmail.com>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Documentation
Requires-Dist: pydantic>=2.0
Requires-Dist: openai>=1.0
Requires-Dist: httpx>=0.27
Requires-Dist: watchfiles>=0.21
Requires-Dist: typer>=0.12
Requires-Dist: pyyaml>=6.0
Requires-Dist: mcp>=1.0 ; extra == 'mcp'
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/mayurpise/graphwiki
Project-URL: Repository, https://github.com/mayurpise/graphwiki
Project-URL: Issues, https://github.com/mayurpise/graphwiki/issues
Provides-Extra: mcp
Description-Content-Type: text/markdown

# graphwiki

[![CI](https://github.com/mayurpise/graphwiki/actions/workflows/ci.yml/badge.svg)](https://github.com/mayurpise/graphwiki/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Status: pre-1.0 (v0.1.0), alpha.

Graph-grounded code wiki generator. **Deterministic traversal decides what to
document; the LLM only writes prose.** Standalone, language-agnostic, local-first.

## Why this exists

| | DeepWiki (Cognition) | OpenWiki | This tool |
|---|---|---|---|
| Traversal | undisclosed (clone: vector RAG) | LLM agent greps around | **Deterministic graph walk** |
| Coverage guarantee | "cluster-based planning" (algorithm hidden) | none | **coverage law — every module gets a page** |
| Citations | prompt-level, **unverified** | none | **verified against the graph — build fails on a hallucinated path** |
| Architecture diagram | LLM-drawn Mermaid | none | **Mermaid synthesized from the dependency graph** |
| Verification | none disclosed | none | **validation gates, fail-loud** |
| Reproducible output | no | no | **yes (deterministic context)** |
| Q&A / MCP | 3-tool MCP, retrieval | none | **same 3-tool MCP surface, deterministic retrieval** |
| Model | proprietary | cloud OSS | **any OpenAI-compatible, local-first** |

The LLM never traverses the graph and never decides coverage. Python does, by
fixed rules. That is what makes incremental refresh trustworthy: a page changes
only when its source subgraph changes.

### How it beats DeepWiki

DeepWiki's documented weak spots ([research](docs/research/deepwiki-generation-pipeline.md))
become this tool's guarantees:

- **Citations are verified, not promised.** Every source path a page cites must
  exist in the code graph; a hallucinated path fails the build. DeepWiki (and its
  clones) cite at the prompt level with nothing checking the paths are real.
- **The architecture diagram is graph-synthesized**, not LLM-freehand — the
  cross-package dependency Mermaid comes straight from CALLS edges, with churn
  hotspots marked (🔥).
- **"Cluster-based planning" is made explicit**: pages are ranked by graph-derived
  churn hotspots + fan-in, deterministically, instead of a hidden algorithm.
- **The MCP Q&A surface matches DeepWiki's three tools** (`read_wiki_structure`,
  `read_wiki_contents`, `ask_question`) but retrieval is reproducible and every
  answer is a set of real, gate-verified pages.

## How it works

```
codebase-memory-mcp (MCP server, 158 langs, MIT)
        │  query_graph / trace_path / detect_changes  (warm stdio connection)
        ▼
  plan (coverage law) → assemble context (deterministic) → writer (LLM, no tools)
        → gates (structure/quality/coverage) → atomic emit
```

## Install

graphwiki is a Python tool. Install it whichever way fits your stack:

```bash
# Python (recommended) — isolated install via uv
uv tool install graphwiki
# or: pipx install graphwiki   /   pip install graphwiki

# npm — thin launcher that runs the Python CLI (needs Python present; uv is easiest)
npm install -g @graphwikihq/graphwiki
```

The npm package is a launcher, not a reimplementation: it locates a Python
runtime (`graphwiki` on PATH → `uvx` → `pipx` → `python -m graphwiki`) and
forwards every command to the real CLI. See [`npm/README.md`](npm/README.md).

## Quickstart (community default: Ollama)

```bash
# Have Ollama installed (https://ollama.com/download). That's the only prereq.
graphwiki build .
```

That one command is a **one-shot**: by default graphwiki auto-manages the whole
local stack for you —

- **engine** — if `codebase-memory-mcp` isn't found, it fetches the pinned
  release (checksum-verified) into `~/.cache/graphwiki/bin`, then indexes the
  repo if it isn't indexed yet;
- **Ollama** — if the server is down, it starts `ollama serve`; if the model
  isn't pulled, it runs `ollama pull <model>`.

It will **not** install Ollama itself — a missing `ollama` binary is a fail-loud
stop with the install link, not a remote install script run on your machine.

```bash
graphwiki build .            # auto-manage everything (default)
graphwiki build . --no-auto  # fail loud instead: no daemons, no downloads (CI)
graphwiki build . --backend offline   # no model at all; deterministic bodies
```

## Backends

`--backend` expands to a working `base-url` + `model` preset in one flag; an
explicit `--base-url`/`--model` still overrides it. The writer makes one plain
OpenAI-compatible chat call per page (no tools passed), so any such endpoint
works.

| `--backend` | Endpoint | Model | Code leaves host? |
|---|---|---|---|
| `ollama` (default) | `http://localhost:11434/v1` | `gemma3` | No |
| `nim` | `http://localhost:8000/v1` | `gemma` | No |
| `offline` | none | none | No (no LLM at all) |
| `grok` | `https://api.x.ai/v1` | `grok-4` | **Yes** — external SaaS |
| `claude` | `https://api.anthropic.com/v1` | `claude-opus-4-8` | **Yes** — external SaaS |
| `openai` | `https://api.openai.com/v1` | `gpt-4o` | **Yes** — external SaaS |

```bash
# local — for sensitive/proprietary repos, code never leaves the host
graphwiki build . --backend nim
graphwiki build . --base-url http://triton.internal:8001/v1 --model my-model

# cloud — needs a key (--api-key or $GRAPHWIKI_API_KEY) and explicit consent
export GRAPHWIKI_API_KEY=...
graphwiki build . --backend claude --allow-cloud-egress
```

Named cloud backends (`grok`/`claude`/`openai`) send code-derived context to an
external SaaS, so they're **gated off by default**: the run aborts before any
page is sent unless you pass `--allow-cloud-egress` or set
`GRAPHWIKI_ALLOW_CLOUD_EGRESS=1` (consent then prints a one-line warning, so
egress is never silent). A raw non-local `--base-url` (an internal NIM/Triton
box) is only logged, never blocked. Full policy: [DATA_GOVERNANCE.md](docs/DATA_GOVERNANCE.md).

> **Note:** these are model **APIs**. Coding-agent CLIs (Codex CLI, Claude Code)
> are deliberately not supported as backends: they are interactive, tool-wielding
> agents, whereas the writer needs a stateless completion that is fed ONLY the
> pre-assembled graph context and forbidden from traversing — the invariant that
> keeps citations verifiable. To use Claude, point `--base-url` at the Anthropic
> API, not the CLI.

## Commands

| Command | Purpose | Key flags |
|---|---|---|
| `graphwiki build .` | Full deterministic pass: plan → write → gate → emit | `--backend`, `--base-url`/`--model`, `--api-key`, `--allow-cloud-egress`, `--offline`, `--out`, `--engine-bin`, `--allow-defer GLOB`, `--auto`/`--no-auto`, `--web`/`--no-web`, `--host`, `--port` |
| `graphwiki update .` | Incremental: rewrite only pages whose subgraph moved | same flags as `build` |
| `graphwiki validate .` | Re-run the gates against the existing wiki, no LLM | `--out`, `--engine-bin` |
| `graphwiki watch .` | Long-running: incremental refresh on every change | same backend flags as `build`, no web-viewer flags |
| `graphwiki web` | Serve an already-built wiki as a local HTML site | `--out`, `--host`, `--port`, `--open`/`--no-open`, `--token`, `--tls-cert`, `--tls-key` |
| `graphwiki serve` | Serve the wiki over MCP (needs the `mcp` extra) | `--out` |
| `graphwiki doctor .` | Health check: engine path/version, index, backend, wiki state — read-only, no LLM, no egress | `[repo]` |

Full, current flags for any command: `graphwiki <command> --help`. Task-oriented
walkthrough: [docs/USER_GUIDE.md](docs/USER_GUIDE.md).

**Diagnostics & logging.** `-v/--verbose` (repeatable — DEBUG detail: engine
calls, stage timings), `-q/--quiet` (errors only), and `--log-json` (structured
JSON log lines on stderr) are global flags: like `git`, they go **before** the
subcommand — `graphwiki -v build .`, not `graphwiki build . -v`. Run
`graphwiki doctor .` first to confirm the engine, index, and backend are healthy.

### Where the wiki lives

`<repo>/wiki/` by default (`--out` to change) — so building another repo writes
into that repo, not your cwd — a plain markdown tree: `systems/`,
`features/`, `entrypoints/` (one `.md` per concept), plus `architecture.md` (the
graph-synthesized Mermaid diagram), `.ai-context.md` (index), `.state/` (refresh
hashes), and `log.md`. Markdown is the source of truth; nothing else is generated.

`--offline` renders deterministic, graph-grounded page bodies without an LLM —
useful for CI, gate testing, and demos. Drop it (and point `--base-url`/`--model`
at a live endpoint) for narrated prose.

## Serving the wiki

**Over HTTP** — `build`/`update` open a local HTML viewer automatically when
they finish (`--no-web` to skip, e.g. in CI). Serve an already-built wiki
anytime with `graphwiki web`. It's a zero-dependency stdlib server that renders
markdown on the fly (nav tree, breadcrumbs, on-this-page rail) — no build step,
no HTML written to disk. Mermaid diagrams render from a **vendored** local
script, so the viewer works air-gapped (CDN is only a fallback if that asset
is missing).

```bash
graphwiki web                                   # serve ./wiki at http://127.0.0.1:8765
graphwiki web --host 0.0.0.0                    # LAN — auto-generated access token printed
graphwiki web --host 0.0.0.0 --token "$SECRET" \
  --tls-cert cert.pem --tls-key key.pem          # LAN over HTTPS with a pinned token
```

Binds to `127.0.0.1` by default (not network-reachable). A non-local `--host`
without an explicit `--token` gets one auto-generated so an exposed viewer is
never unauthenticated by default; `--tls-cert`/`--tls-key` serve over HTTPS.

**Over MCP** — `graphwiki serve` exposes the generated wiki with the same three
tools DeepWiki ships — `read_wiki_structure`, `read_wiki_contents`,
`ask_question` — so any MCP-aware editor/agent works against it unmodified.
Retrieval is deterministic (graph-derived term overlap + hotspot ranking), so
`ask_question` returns the same gate-verified pages for the same question every
time.

```bash
uv add mcp            # or: pip install 'graphwiki[mcp]'
graphwiki serve --out wiki
```

## Docs

- [docs/USER_GUIDE.md](docs/USER_GUIDE.md) — task-oriented usage guide.
- [docs/RUNBOOK.md](docs/RUNBOOK.md) — ops: install/upgrade, air-gapped operation, security posture, troubleshooting, exit codes.
- [docs/DATA_GOVERNANCE.md](docs/DATA_GOVERNANCE.md) — what data leaves the environment and the cloud-egress consent gate.
- [docs/audit/ENTERPRISE_READINESS.md](docs/audit/ENTERPRISE_READINESS.md) — enterprise-readiness scorecard and gaps.

## Status

**Working.** The full pipeline is implemented and verified end-to-end against a
real `codebase-memory-mcp` graph: plan (coverage law) → deterministic context →
writer (LLM or offline) → three-layer gates → atomic emit → subgraph-hash state.
`build`, `update`, `validate`, and `watch` all function. Test suite (`pytest`),
lint (`ruff`), and types (`mypy`) are green.

Engine integration uses the binary's `cli <tool>` subprocess interface (v0.8.x),
not the stdio MCP SDK path — simpler for a batch generator, swappable in one file.

Name verified available on PyPI. See `docs/WORK_TRACKER.md` for remaining
publish-polish.

## Credits

Coverage law + validation gates + type taxonomy ported from
[Draft](https://github.com/drafthq/draft) (OKF emitter, MIT). Graph engine:
[codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) (MIT).

MIT.
