graphwiki 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- graphwiki-0.1.0/PKG-INFO +258 -0
- graphwiki-0.1.0/README.md +230 -0
- graphwiki-0.1.0/pyproject.toml +64 -0
- graphwiki-0.1.0/src/graphwiki/__init__.py +12 -0
- graphwiki-0.1.0/src/graphwiki/__main__.py +6 -0
- graphwiki-0.1.0/src/graphwiki/assets/README.md +22 -0
- graphwiki-0.1.0/src/graphwiki/assets/mermaid.min.js +3587 -0
- graphwiki-0.1.0/src/graphwiki/bootstrap.py +118 -0
- graphwiki-0.1.0/src/graphwiki/cli.py +1015 -0
- graphwiki-0.1.0/src/graphwiki/context.py +177 -0
- graphwiki-0.1.0/src/graphwiki/emit.py +129 -0
- graphwiki-0.1.0/src/graphwiki/gates.py +289 -0
- graphwiki-0.1.0/src/graphwiki/graph_client.py +698 -0
- graphwiki-0.1.0/src/graphwiki/logging_util.py +127 -0
- graphwiki-0.1.0/src/graphwiki/mcp_server.py +204 -0
- graphwiki-0.1.0/src/graphwiki/plan.py +320 -0
- graphwiki-0.1.0/src/graphwiki/py.typed +0 -0
- graphwiki-0.1.0/src/graphwiki/render.py +190 -0
- graphwiki-0.1.0/src/graphwiki/state.py +61 -0
- graphwiki-0.1.0/src/graphwiki/types.py +100 -0
- graphwiki-0.1.0/src/graphwiki/watch.py +96 -0
- graphwiki-0.1.0/src/graphwiki/web.py +689 -0
- graphwiki-0.1.0/src/graphwiki/writer.py +460 -0
graphwiki-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,258 @@
|
|
|
1
|
+
Metadata-Version: 2.3
|
|
2
|
+
Name: graphwiki
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Graph-grounded code wiki generator: deterministic traversal, LLM writes prose only.
|
|
5
|
+
Keywords: documentation,wiki,code-graph,llm,developer-tools
|
|
6
|
+
Author: Mayur Pise
|
|
7
|
+
Author-email: Mayur Pise <mayurpise@gmail.com>
|
|
8
|
+
License: MIT
|
|
9
|
+
Classifier: Development Status :: 3 - Alpha
|
|
10
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Topic :: Software Development :: Documentation
|
|
15
|
+
Requires-Dist: pydantic>=2.0
|
|
16
|
+
Requires-Dist: openai>=1.0
|
|
17
|
+
Requires-Dist: httpx>=0.27
|
|
18
|
+
Requires-Dist: watchfiles>=0.21
|
|
19
|
+
Requires-Dist: typer>=0.12
|
|
20
|
+
Requires-Dist: pyyaml>=6.0
|
|
21
|
+
Requires-Dist: mcp>=1.0 ; extra == 'mcp'
|
|
22
|
+
Requires-Python: >=3.11
|
|
23
|
+
Project-URL: Homepage, https://github.com/mayurpise/graphwiki
|
|
24
|
+
Project-URL: Repository, https://github.com/mayurpise/graphwiki
|
|
25
|
+
Project-URL: Issues, https://github.com/mayurpise/graphwiki/issues
|
|
26
|
+
Provides-Extra: mcp
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
|
|
29
|
+
# graphwiki
|
|
30
|
+
|
|
31
|
+
[](https://github.com/mayurpise/graphwiki/actions/workflows/ci.yml)
|
|
32
|
+
[](LICENSE)
|
|
33
|
+
|
|
34
|
+
Status: pre-1.0 (v0.1.0), alpha.
|
|
35
|
+
|
|
36
|
+
Graph-grounded code wiki generator. **Deterministic traversal decides what to
|
|
37
|
+
document; the LLM only writes prose.** Standalone, language-agnostic, local-first.
|
|
38
|
+
|
|
39
|
+
## Why this exists
|
|
40
|
+
|
|
41
|
+
| | DeepWiki (Cognition) | OpenWiki | This tool |
|
|
42
|
+
|---|---|---|---|
|
|
43
|
+
| Traversal | undisclosed (clone: vector RAG) | LLM agent greps around | **Deterministic graph walk** |
|
|
44
|
+
| Coverage guarantee | "cluster-based planning" (algorithm hidden) | none | **coverage law — every module gets a page** |
|
|
45
|
+
| Citations | prompt-level, **unverified** | none | **verified against the graph — build fails on a hallucinated path** |
|
|
46
|
+
| Architecture diagram | LLM-drawn Mermaid | none | **Mermaid synthesized from the dependency graph** |
|
|
47
|
+
| Verification | none disclosed | none | **validation gates, fail-loud** |
|
|
48
|
+
| Reproducible output | no | no | **yes (deterministic context)** |
|
|
49
|
+
| Q&A / MCP | 3-tool MCP, retrieval | none | **same 3-tool MCP surface, deterministic retrieval** |
|
|
50
|
+
| Model | proprietary | cloud OSS | **any OpenAI-compatible, local-first** |
|
|
51
|
+
|
|
52
|
+
The LLM never traverses the graph and never decides coverage. Python does, by
|
|
53
|
+
fixed rules. That is what makes incremental refresh trustworthy: a page changes
|
|
54
|
+
only when its source subgraph changes.
|
|
55
|
+
|
|
56
|
+
### How it beats DeepWiki
|
|
57
|
+
|
|
58
|
+
DeepWiki's documented weak spots ([research](docs/research/deepwiki-generation-pipeline.md))
|
|
59
|
+
become this tool's guarantees:
|
|
60
|
+
|
|
61
|
+
- **Citations are verified, not promised.** Every source path a page cites must
|
|
62
|
+
exist in the code graph; a hallucinated path fails the build. DeepWiki (and its
|
|
63
|
+
clones) cite at the prompt level with nothing checking the paths are real.
|
|
64
|
+
- **The architecture diagram is graph-synthesized**, not LLM-freehand — the
|
|
65
|
+
cross-package dependency Mermaid comes straight from CALLS edges, with churn
|
|
66
|
+
hotspots marked (🔥).
|
|
67
|
+
- **"Cluster-based planning" is made explicit**: pages are ranked by graph-derived
|
|
68
|
+
churn hotspots + fan-in, deterministically, instead of a hidden algorithm.
|
|
69
|
+
- **The MCP Q&A surface matches DeepWiki's three tools** (`read_wiki_structure`,
|
|
70
|
+
`read_wiki_contents`, `ask_question`) but retrieval is reproducible and every
|
|
71
|
+
answer is a set of real, gate-verified pages.
|
|
72
|
+
|
|
73
|
+
## How it works
|
|
74
|
+
|
|
75
|
+
```
|
|
76
|
+
codebase-memory-mcp (MCP server, 158 langs, MIT)
|
|
77
|
+
│ query_graph / trace_path / detect_changes (warm stdio connection)
|
|
78
|
+
▼
|
|
79
|
+
plan (coverage law) → assemble context (deterministic) → writer (LLM, no tools)
|
|
80
|
+
→ gates (structure/quality/coverage) → atomic emit
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## Install
|
|
84
|
+
|
|
85
|
+
graphwiki is a Python tool. Install it whichever way fits your stack:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
# Python (recommended) — isolated install via uv
|
|
89
|
+
uv tool install graphwiki
|
|
90
|
+
# or: pipx install graphwiki / pip install graphwiki
|
|
91
|
+
|
|
92
|
+
# npm — thin launcher that runs the Python CLI (needs Python present; uv is easiest)
|
|
93
|
+
npm install -g @graphwikihq/graphwiki
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
The npm package is a launcher, not a reimplementation: it locates a Python
|
|
97
|
+
runtime (`graphwiki` on PATH → `uvx` → `pipx` → `python -m graphwiki`) and
|
|
98
|
+
forwards every command to the real CLI. See [`npm/README.md`](npm/README.md).
|
|
99
|
+
|
|
100
|
+
## Quickstart (community default: Ollama)
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
# Have Ollama installed (https://ollama.com/download). That's the only prereq.
|
|
104
|
+
graphwiki build .
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
That one command is a **one-shot**: by default graphwiki auto-manages the whole
|
|
108
|
+
local stack for you —
|
|
109
|
+
|
|
110
|
+
- **engine** — if `codebase-memory-mcp` isn't found, it fetches the pinned
|
|
111
|
+
release (checksum-verified) into `~/.cache/graphwiki/bin`, then indexes the
|
|
112
|
+
repo if it isn't indexed yet;
|
|
113
|
+
- **Ollama** — if the server is down, it starts `ollama serve`; if the model
|
|
114
|
+
isn't pulled, it runs `ollama pull <model>`.
|
|
115
|
+
|
|
116
|
+
It will **not** install Ollama itself — a missing `ollama` binary is a fail-loud
|
|
117
|
+
stop with the install link, not a remote install script run on your machine.
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
graphwiki build . # auto-manage everything (default)
|
|
121
|
+
graphwiki build . --no-auto # fail loud instead: no daemons, no downloads (CI)
|
|
122
|
+
graphwiki build . --backend offline # no model at all; deterministic bodies
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
## Backends
|
|
126
|
+
|
|
127
|
+
`--backend` expands to a working `base-url` + `model` preset in one flag; an
|
|
128
|
+
explicit `--base-url`/`--model` still overrides it. The writer makes one plain
|
|
129
|
+
OpenAI-compatible chat call per page (no tools passed), so any such endpoint
|
|
130
|
+
works.
|
|
131
|
+
|
|
132
|
+
| `--backend` | Endpoint | Model | Code leaves host? |
|
|
133
|
+
|---|---|---|---|
|
|
134
|
+
| `ollama` (default) | `http://localhost:11434/v1` | `gemma3` | No |
|
|
135
|
+
| `nim` | `http://localhost:8000/v1` | `gemma` | No |
|
|
136
|
+
| `offline` | none | none | No (no LLM at all) |
|
|
137
|
+
| `grok` | `https://api.x.ai/v1` | `grok-4` | **Yes** — external SaaS |
|
|
138
|
+
| `claude` | `https://api.anthropic.com/v1` | `claude-opus-4-8` | **Yes** — external SaaS |
|
|
139
|
+
| `openai` | `https://api.openai.com/v1` | `gpt-4o` | **Yes** — external SaaS |
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
# local — for sensitive/proprietary repos, code never leaves the host
|
|
143
|
+
graphwiki build . --backend nim
|
|
144
|
+
graphwiki build . --base-url http://triton.internal:8001/v1 --model my-model
|
|
145
|
+
|
|
146
|
+
# cloud — needs a key (--api-key or $GRAPHWIKI_API_KEY) and explicit consent
|
|
147
|
+
export GRAPHWIKI_API_KEY=...
|
|
148
|
+
graphwiki build . --backend claude --allow-cloud-egress
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Named cloud backends (`grok`/`claude`/`openai`) send code-derived context to an
|
|
152
|
+
external SaaS, so they're **gated off by default**: the run aborts before any
|
|
153
|
+
page is sent unless you pass `--allow-cloud-egress` or set
|
|
154
|
+
`GRAPHWIKI_ALLOW_CLOUD_EGRESS=1` (consent then prints a one-line warning, so
|
|
155
|
+
egress is never silent). A raw non-local `--base-url` (an internal NIM/Triton
|
|
156
|
+
box) is only logged, never blocked. Full policy: [DATA_GOVERNANCE.md](docs/DATA_GOVERNANCE.md).
|
|
157
|
+
|
|
158
|
+
> **Note:** these are model **APIs**. Coding-agent CLIs (Codex CLI, Claude Code)
|
|
159
|
+
> are deliberately not supported as backends: they are interactive, tool-wielding
|
|
160
|
+
> agents, whereas the writer needs a stateless completion that is fed ONLY the
|
|
161
|
+
> pre-assembled graph context and forbidden from traversing — the invariant that
|
|
162
|
+
> keeps citations verifiable. To use Claude, point `--base-url` at the Anthropic
|
|
163
|
+
> API, not the CLI.
|
|
164
|
+
|
|
165
|
+
## Commands
|
|
166
|
+
|
|
167
|
+
| Command | Purpose | Key flags |
|
|
168
|
+
|---|---|---|
|
|
169
|
+
| `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` |
|
|
170
|
+
| `graphwiki update .` | Incremental: rewrite only pages whose subgraph moved | same flags as `build` |
|
|
171
|
+
| `graphwiki validate .` | Re-run the gates against the existing wiki, no LLM | `--out`, `--engine-bin` |
|
|
172
|
+
| `graphwiki watch .` | Long-running: incremental refresh on every change | same backend flags as `build`, no web-viewer flags |
|
|
173
|
+
| `graphwiki web` | Serve an already-built wiki as a local HTML site | `--out`, `--host`, `--port`, `--open`/`--no-open`, `--token`, `--tls-cert`, `--tls-key` |
|
|
174
|
+
| `graphwiki serve` | Serve the wiki over MCP (needs the `mcp` extra) | `--out` |
|
|
175
|
+
| `graphwiki doctor .` | Health check: engine path/version, index, backend, wiki state — read-only, no LLM, no egress | `[repo]` |
|
|
176
|
+
|
|
177
|
+
Full, current flags for any command: `graphwiki <command> --help`. Task-oriented
|
|
178
|
+
walkthrough: [docs/USER_GUIDE.md](docs/USER_GUIDE.md).
|
|
179
|
+
|
|
180
|
+
**Diagnostics & logging.** `-v/--verbose` (repeatable — DEBUG detail: engine
|
|
181
|
+
calls, stage timings), `-q/--quiet` (errors only), and `--log-json` (structured
|
|
182
|
+
JSON log lines on stderr) are global flags: like `git`, they go **before** the
|
|
183
|
+
subcommand — `graphwiki -v build .`, not `graphwiki build . -v`. Run
|
|
184
|
+
`graphwiki doctor .` first to confirm the engine, index, and backend are healthy.
|
|
185
|
+
|
|
186
|
+
### Where the wiki lives
|
|
187
|
+
|
|
188
|
+
`<repo>/wiki/` by default (`--out` to change) — so building another repo writes
|
|
189
|
+
into that repo, not your cwd — a plain markdown tree: `systems/`,
|
|
190
|
+
`features/`, `entrypoints/` (one `.md` per concept), plus `architecture.md` (the
|
|
191
|
+
graph-synthesized Mermaid diagram), `.ai-context.md` (index), `.state/` (refresh
|
|
192
|
+
hashes), and `log.md`. Markdown is the source of truth; nothing else is generated.
|
|
193
|
+
|
|
194
|
+
`--offline` renders deterministic, graph-grounded page bodies without an LLM —
|
|
195
|
+
useful for CI, gate testing, and demos. Drop it (and point `--base-url`/`--model`
|
|
196
|
+
at a live endpoint) for narrated prose.
|
|
197
|
+
|
|
198
|
+
## Serving the wiki
|
|
199
|
+
|
|
200
|
+
**Over HTTP** — `build`/`update` open a local HTML viewer automatically when
|
|
201
|
+
they finish (`--no-web` to skip, e.g. in CI). Serve an already-built wiki
|
|
202
|
+
anytime with `graphwiki web`. It's a zero-dependency stdlib server that renders
|
|
203
|
+
markdown on the fly (nav tree, breadcrumbs, on-this-page rail) — no build step,
|
|
204
|
+
no HTML written to disk. Mermaid diagrams render from a **vendored** local
|
|
205
|
+
script, so the viewer works air-gapped (CDN is only a fallback if that asset
|
|
206
|
+
is missing).
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
graphwiki web # serve ./wiki at http://127.0.0.1:8765
|
|
210
|
+
graphwiki web --host 0.0.0.0 # LAN — auto-generated access token printed
|
|
211
|
+
graphwiki web --host 0.0.0.0 --token "$SECRET" \
|
|
212
|
+
--tls-cert cert.pem --tls-key key.pem # LAN over HTTPS with a pinned token
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
Binds to `127.0.0.1` by default (not network-reachable). A non-local `--host`
|
|
216
|
+
without an explicit `--token` gets one auto-generated so an exposed viewer is
|
|
217
|
+
never unauthenticated by default; `--tls-cert`/`--tls-key` serve over HTTPS.
|
|
218
|
+
|
|
219
|
+
**Over MCP** — `graphwiki serve` exposes the generated wiki with the same three
|
|
220
|
+
tools DeepWiki ships — `read_wiki_structure`, `read_wiki_contents`,
|
|
221
|
+
`ask_question` — so any MCP-aware editor/agent works against it unmodified.
|
|
222
|
+
Retrieval is deterministic (graph-derived term overlap + hotspot ranking), so
|
|
223
|
+
`ask_question` returns the same gate-verified pages for the same question every
|
|
224
|
+
time.
|
|
225
|
+
|
|
226
|
+
```bash
|
|
227
|
+
uv add mcp # or: pip install 'graphwiki[mcp]'
|
|
228
|
+
graphwiki serve --out wiki
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
## Docs
|
|
232
|
+
|
|
233
|
+
- [docs/USER_GUIDE.md](docs/USER_GUIDE.md) — task-oriented usage guide.
|
|
234
|
+
- [docs/RUNBOOK.md](docs/RUNBOOK.md) — ops: install/upgrade, air-gapped operation, security posture, troubleshooting, exit codes.
|
|
235
|
+
- [docs/DATA_GOVERNANCE.md](docs/DATA_GOVERNANCE.md) — what data leaves the environment and the cloud-egress consent gate.
|
|
236
|
+
- [docs/audit/ENTERPRISE_READINESS.md](docs/audit/ENTERPRISE_READINESS.md) — enterprise-readiness scorecard and gaps.
|
|
237
|
+
|
|
238
|
+
## Status
|
|
239
|
+
|
|
240
|
+
**Working.** The full pipeline is implemented and verified end-to-end against a
|
|
241
|
+
real `codebase-memory-mcp` graph: plan (coverage law) → deterministic context →
|
|
242
|
+
writer (LLM or offline) → three-layer gates → atomic emit → subgraph-hash state.
|
|
243
|
+
`build`, `update`, `validate`, and `watch` all function. Test suite (`pytest`),
|
|
244
|
+
lint (`ruff`), and types (`mypy`) are green.
|
|
245
|
+
|
|
246
|
+
Engine integration uses the binary's `cli <tool>` subprocess interface (v0.8.x),
|
|
247
|
+
not the stdio MCP SDK path — simpler for a batch generator, swappable in one file.
|
|
248
|
+
|
|
249
|
+
Name verified available on PyPI. See `docs/WORK_TRACKER.md` for remaining
|
|
250
|
+
publish-polish.
|
|
251
|
+
|
|
252
|
+
## Credits
|
|
253
|
+
|
|
254
|
+
Coverage law + validation gates + type taxonomy ported from
|
|
255
|
+
[Draft](https://github.com/drafthq/draft) (OKF emitter, MIT). Graph engine:
|
|
256
|
+
[codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) (MIT).
|
|
257
|
+
|
|
258
|
+
MIT.
|
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
# graphwiki
|
|
2
|
+
|
|
3
|
+
[](https://github.com/mayurpise/graphwiki/actions/workflows/ci.yml)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
|
|
6
|
+
Status: pre-1.0 (v0.1.0), alpha.
|
|
7
|
+
|
|
8
|
+
Graph-grounded code wiki generator. **Deterministic traversal decides what to
|
|
9
|
+
document; the LLM only writes prose.** Standalone, language-agnostic, local-first.
|
|
10
|
+
|
|
11
|
+
## Why this exists
|
|
12
|
+
|
|
13
|
+
| | DeepWiki (Cognition) | OpenWiki | This tool |
|
|
14
|
+
|---|---|---|---|
|
|
15
|
+
| Traversal | undisclosed (clone: vector RAG) | LLM agent greps around | **Deterministic graph walk** |
|
|
16
|
+
| Coverage guarantee | "cluster-based planning" (algorithm hidden) | none | **coverage law — every module gets a page** |
|
|
17
|
+
| Citations | prompt-level, **unverified** | none | **verified against the graph — build fails on a hallucinated path** |
|
|
18
|
+
| Architecture diagram | LLM-drawn Mermaid | none | **Mermaid synthesized from the dependency graph** |
|
|
19
|
+
| Verification | none disclosed | none | **validation gates, fail-loud** |
|
|
20
|
+
| Reproducible output | no | no | **yes (deterministic context)** |
|
|
21
|
+
| Q&A / MCP | 3-tool MCP, retrieval | none | **same 3-tool MCP surface, deterministic retrieval** |
|
|
22
|
+
| Model | proprietary | cloud OSS | **any OpenAI-compatible, local-first** |
|
|
23
|
+
|
|
24
|
+
The LLM never traverses the graph and never decides coverage. Python does, by
|
|
25
|
+
fixed rules. That is what makes incremental refresh trustworthy: a page changes
|
|
26
|
+
only when its source subgraph changes.
|
|
27
|
+
|
|
28
|
+
### How it beats DeepWiki
|
|
29
|
+
|
|
30
|
+
DeepWiki's documented weak spots ([research](docs/research/deepwiki-generation-pipeline.md))
|
|
31
|
+
become this tool's guarantees:
|
|
32
|
+
|
|
33
|
+
- **Citations are verified, not promised.** Every source path a page cites must
|
|
34
|
+
exist in the code graph; a hallucinated path fails the build. DeepWiki (and its
|
|
35
|
+
clones) cite at the prompt level with nothing checking the paths are real.
|
|
36
|
+
- **The architecture diagram is graph-synthesized**, not LLM-freehand — the
|
|
37
|
+
cross-package dependency Mermaid comes straight from CALLS edges, with churn
|
|
38
|
+
hotspots marked (🔥).
|
|
39
|
+
- **"Cluster-based planning" is made explicit**: pages are ranked by graph-derived
|
|
40
|
+
churn hotspots + fan-in, deterministically, instead of a hidden algorithm.
|
|
41
|
+
- **The MCP Q&A surface matches DeepWiki's three tools** (`read_wiki_structure`,
|
|
42
|
+
`read_wiki_contents`, `ask_question`) but retrieval is reproducible and every
|
|
43
|
+
answer is a set of real, gate-verified pages.
|
|
44
|
+
|
|
45
|
+
## How it works
|
|
46
|
+
|
|
47
|
+
```
|
|
48
|
+
codebase-memory-mcp (MCP server, 158 langs, MIT)
|
|
49
|
+
│ query_graph / trace_path / detect_changes (warm stdio connection)
|
|
50
|
+
▼
|
|
51
|
+
plan (coverage law) → assemble context (deterministic) → writer (LLM, no tools)
|
|
52
|
+
→ gates (structure/quality/coverage) → atomic emit
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## Install
|
|
56
|
+
|
|
57
|
+
graphwiki is a Python tool. Install it whichever way fits your stack:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
# Python (recommended) — isolated install via uv
|
|
61
|
+
uv tool install graphwiki
|
|
62
|
+
# or: pipx install graphwiki / pip install graphwiki
|
|
63
|
+
|
|
64
|
+
# npm — thin launcher that runs the Python CLI (needs Python present; uv is easiest)
|
|
65
|
+
npm install -g @graphwikihq/graphwiki
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
The npm package is a launcher, not a reimplementation: it locates a Python
|
|
69
|
+
runtime (`graphwiki` on PATH → `uvx` → `pipx` → `python -m graphwiki`) and
|
|
70
|
+
forwards every command to the real CLI. See [`npm/README.md`](npm/README.md).
|
|
71
|
+
|
|
72
|
+
## Quickstart (community default: Ollama)
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
# Have Ollama installed (https://ollama.com/download). That's the only prereq.
|
|
76
|
+
graphwiki build .
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
That one command is a **one-shot**: by default graphwiki auto-manages the whole
|
|
80
|
+
local stack for you —
|
|
81
|
+
|
|
82
|
+
- **engine** — if `codebase-memory-mcp` isn't found, it fetches the pinned
|
|
83
|
+
release (checksum-verified) into `~/.cache/graphwiki/bin`, then indexes the
|
|
84
|
+
repo if it isn't indexed yet;
|
|
85
|
+
- **Ollama** — if the server is down, it starts `ollama serve`; if the model
|
|
86
|
+
isn't pulled, it runs `ollama pull <model>`.
|
|
87
|
+
|
|
88
|
+
It will **not** install Ollama itself — a missing `ollama` binary is a fail-loud
|
|
89
|
+
stop with the install link, not a remote install script run on your machine.
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
graphwiki build . # auto-manage everything (default)
|
|
93
|
+
graphwiki build . --no-auto # fail loud instead: no daemons, no downloads (CI)
|
|
94
|
+
graphwiki build . --backend offline # no model at all; deterministic bodies
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## Backends
|
|
98
|
+
|
|
99
|
+
`--backend` expands to a working `base-url` + `model` preset in one flag; an
|
|
100
|
+
explicit `--base-url`/`--model` still overrides it. The writer makes one plain
|
|
101
|
+
OpenAI-compatible chat call per page (no tools passed), so any such endpoint
|
|
102
|
+
works.
|
|
103
|
+
|
|
104
|
+
| `--backend` | Endpoint | Model | Code leaves host? |
|
|
105
|
+
|---|---|---|---|
|
|
106
|
+
| `ollama` (default) | `http://localhost:11434/v1` | `gemma3` | No |
|
|
107
|
+
| `nim` | `http://localhost:8000/v1` | `gemma` | No |
|
|
108
|
+
| `offline` | none | none | No (no LLM at all) |
|
|
109
|
+
| `grok` | `https://api.x.ai/v1` | `grok-4` | **Yes** — external SaaS |
|
|
110
|
+
| `claude` | `https://api.anthropic.com/v1` | `claude-opus-4-8` | **Yes** — external SaaS |
|
|
111
|
+
| `openai` | `https://api.openai.com/v1` | `gpt-4o` | **Yes** — external SaaS |
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
# local — for sensitive/proprietary repos, code never leaves the host
|
|
115
|
+
graphwiki build . --backend nim
|
|
116
|
+
graphwiki build . --base-url http://triton.internal:8001/v1 --model my-model
|
|
117
|
+
|
|
118
|
+
# cloud — needs a key (--api-key or $GRAPHWIKI_API_KEY) and explicit consent
|
|
119
|
+
export GRAPHWIKI_API_KEY=...
|
|
120
|
+
graphwiki build . --backend claude --allow-cloud-egress
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Named cloud backends (`grok`/`claude`/`openai`) send code-derived context to an
|
|
124
|
+
external SaaS, so they're **gated off by default**: the run aborts before any
|
|
125
|
+
page is sent unless you pass `--allow-cloud-egress` or set
|
|
126
|
+
`GRAPHWIKI_ALLOW_CLOUD_EGRESS=1` (consent then prints a one-line warning, so
|
|
127
|
+
egress is never silent). A raw non-local `--base-url` (an internal NIM/Triton
|
|
128
|
+
box) is only logged, never blocked. Full policy: [DATA_GOVERNANCE.md](docs/DATA_GOVERNANCE.md).
|
|
129
|
+
|
|
130
|
+
> **Note:** these are model **APIs**. Coding-agent CLIs (Codex CLI, Claude Code)
|
|
131
|
+
> are deliberately not supported as backends: they are interactive, tool-wielding
|
|
132
|
+
> agents, whereas the writer needs a stateless completion that is fed ONLY the
|
|
133
|
+
> pre-assembled graph context and forbidden from traversing — the invariant that
|
|
134
|
+
> keeps citations verifiable. To use Claude, point `--base-url` at the Anthropic
|
|
135
|
+
> API, not the CLI.
|
|
136
|
+
|
|
137
|
+
## Commands
|
|
138
|
+
|
|
139
|
+
| Command | Purpose | Key flags |
|
|
140
|
+
|---|---|---|
|
|
141
|
+
| `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` |
|
|
142
|
+
| `graphwiki update .` | Incremental: rewrite only pages whose subgraph moved | same flags as `build` |
|
|
143
|
+
| `graphwiki validate .` | Re-run the gates against the existing wiki, no LLM | `--out`, `--engine-bin` |
|
|
144
|
+
| `graphwiki watch .` | Long-running: incremental refresh on every change | same backend flags as `build`, no web-viewer flags |
|
|
145
|
+
| `graphwiki web` | Serve an already-built wiki as a local HTML site | `--out`, `--host`, `--port`, `--open`/`--no-open`, `--token`, `--tls-cert`, `--tls-key` |
|
|
146
|
+
| `graphwiki serve` | Serve the wiki over MCP (needs the `mcp` extra) | `--out` |
|
|
147
|
+
| `graphwiki doctor .` | Health check: engine path/version, index, backend, wiki state — read-only, no LLM, no egress | `[repo]` |
|
|
148
|
+
|
|
149
|
+
Full, current flags for any command: `graphwiki <command> --help`. Task-oriented
|
|
150
|
+
walkthrough: [docs/USER_GUIDE.md](docs/USER_GUIDE.md).
|
|
151
|
+
|
|
152
|
+
**Diagnostics & logging.** `-v/--verbose` (repeatable — DEBUG detail: engine
|
|
153
|
+
calls, stage timings), `-q/--quiet` (errors only), and `--log-json` (structured
|
|
154
|
+
JSON log lines on stderr) are global flags: like `git`, they go **before** the
|
|
155
|
+
subcommand — `graphwiki -v build .`, not `graphwiki build . -v`. Run
|
|
156
|
+
`graphwiki doctor .` first to confirm the engine, index, and backend are healthy.
|
|
157
|
+
|
|
158
|
+
### Where the wiki lives
|
|
159
|
+
|
|
160
|
+
`<repo>/wiki/` by default (`--out` to change) — so building another repo writes
|
|
161
|
+
into that repo, not your cwd — a plain markdown tree: `systems/`,
|
|
162
|
+
`features/`, `entrypoints/` (one `.md` per concept), plus `architecture.md` (the
|
|
163
|
+
graph-synthesized Mermaid diagram), `.ai-context.md` (index), `.state/` (refresh
|
|
164
|
+
hashes), and `log.md`. Markdown is the source of truth; nothing else is generated.
|
|
165
|
+
|
|
166
|
+
`--offline` renders deterministic, graph-grounded page bodies without an LLM —
|
|
167
|
+
useful for CI, gate testing, and demos. Drop it (and point `--base-url`/`--model`
|
|
168
|
+
at a live endpoint) for narrated prose.
|
|
169
|
+
|
|
170
|
+
## Serving the wiki
|
|
171
|
+
|
|
172
|
+
**Over HTTP** — `build`/`update` open a local HTML viewer automatically when
|
|
173
|
+
they finish (`--no-web` to skip, e.g. in CI). Serve an already-built wiki
|
|
174
|
+
anytime with `graphwiki web`. It's a zero-dependency stdlib server that renders
|
|
175
|
+
markdown on the fly (nav tree, breadcrumbs, on-this-page rail) — no build step,
|
|
176
|
+
no HTML written to disk. Mermaid diagrams render from a **vendored** local
|
|
177
|
+
script, so the viewer works air-gapped (CDN is only a fallback if that asset
|
|
178
|
+
is missing).
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
graphwiki web # serve ./wiki at http://127.0.0.1:8765
|
|
182
|
+
graphwiki web --host 0.0.0.0 # LAN — auto-generated access token printed
|
|
183
|
+
graphwiki web --host 0.0.0.0 --token "$SECRET" \
|
|
184
|
+
--tls-cert cert.pem --tls-key key.pem # LAN over HTTPS with a pinned token
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
Binds to `127.0.0.1` by default (not network-reachable). A non-local `--host`
|
|
188
|
+
without an explicit `--token` gets one auto-generated so an exposed viewer is
|
|
189
|
+
never unauthenticated by default; `--tls-cert`/`--tls-key` serve over HTTPS.
|
|
190
|
+
|
|
191
|
+
**Over MCP** — `graphwiki serve` exposes the generated wiki with the same three
|
|
192
|
+
tools DeepWiki ships — `read_wiki_structure`, `read_wiki_contents`,
|
|
193
|
+
`ask_question` — so any MCP-aware editor/agent works against it unmodified.
|
|
194
|
+
Retrieval is deterministic (graph-derived term overlap + hotspot ranking), so
|
|
195
|
+
`ask_question` returns the same gate-verified pages for the same question every
|
|
196
|
+
time.
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
uv add mcp # or: pip install 'graphwiki[mcp]'
|
|
200
|
+
graphwiki serve --out wiki
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
## Docs
|
|
204
|
+
|
|
205
|
+
- [docs/USER_GUIDE.md](docs/USER_GUIDE.md) — task-oriented usage guide.
|
|
206
|
+
- [docs/RUNBOOK.md](docs/RUNBOOK.md) — ops: install/upgrade, air-gapped operation, security posture, troubleshooting, exit codes.
|
|
207
|
+
- [docs/DATA_GOVERNANCE.md](docs/DATA_GOVERNANCE.md) — what data leaves the environment and the cloud-egress consent gate.
|
|
208
|
+
- [docs/audit/ENTERPRISE_READINESS.md](docs/audit/ENTERPRISE_READINESS.md) — enterprise-readiness scorecard and gaps.
|
|
209
|
+
|
|
210
|
+
## Status
|
|
211
|
+
|
|
212
|
+
**Working.** The full pipeline is implemented and verified end-to-end against a
|
|
213
|
+
real `codebase-memory-mcp` graph: plan (coverage law) → deterministic context →
|
|
214
|
+
writer (LLM or offline) → three-layer gates → atomic emit → subgraph-hash state.
|
|
215
|
+
`build`, `update`, `validate`, and `watch` all function. Test suite (`pytest`),
|
|
216
|
+
lint (`ruff`), and types (`mypy`) are green.
|
|
217
|
+
|
|
218
|
+
Engine integration uses the binary's `cli <tool>` subprocess interface (v0.8.x),
|
|
219
|
+
not the stdio MCP SDK path — simpler for a batch generator, swappable in one file.
|
|
220
|
+
|
|
221
|
+
Name verified available on PyPI. See `docs/WORK_TRACKER.md` for remaining
|
|
222
|
+
publish-polish.
|
|
223
|
+
|
|
224
|
+
## Credits
|
|
225
|
+
|
|
226
|
+
Coverage law + validation gates + type taxonomy ported from
|
|
227
|
+
[Draft](https://github.com/drafthq/draft) (OKF emitter, MIT). Graph engine:
|
|
228
|
+
[codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) (MIT).
|
|
229
|
+
|
|
230
|
+
MIT.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
# Name verified available on PyPI (2026-07-01). npm has an unrelated `graphwiki`
|
|
3
|
+
# but this is a Python-only tool, so there is no conflict.
|
|
4
|
+
name = "graphwiki"
|
|
5
|
+
version = "0.1.0"
|
|
6
|
+
description = "Graph-grounded code wiki generator: deterministic traversal, LLM writes prose only."
|
|
7
|
+
readme = "README.md"
|
|
8
|
+
requires-python = ">=3.11"
|
|
9
|
+
authors = [{ name = "Mayur Pise", email = "mayurpise@gmail.com" }]
|
|
10
|
+
license = { text = "MIT" }
|
|
11
|
+
keywords = ["documentation", "wiki", "code-graph", "llm", "developer-tools"]
|
|
12
|
+
classifiers = [
|
|
13
|
+
"Development Status :: 3 - Alpha",
|
|
14
|
+
"License :: OSI Approved :: MIT License",
|
|
15
|
+
"Programming Language :: Python :: 3.11",
|
|
16
|
+
"Programming Language :: Python :: 3.12",
|
|
17
|
+
"Intended Audience :: Developers",
|
|
18
|
+
"Topic :: Software Development :: Documentation",
|
|
19
|
+
]
|
|
20
|
+
dependencies = [
|
|
21
|
+
# Engine is driven via its `cli <tool>` subprocess interface (see
|
|
22
|
+
# graph_client.py); the `mcp` SDK stdio path is a documented future option,
|
|
23
|
+
# not a runtime dependency today.
|
|
24
|
+
"pydantic>=2.0", # frontmatter contract / typed models
|
|
25
|
+
"openai>=1.0", # OpenAI-compatible writer (Ollama/NIM/Triton/Claude/GLM)
|
|
26
|
+
"httpx>=0.27", # Ollama preflight probe (also an openai transitive dep)
|
|
27
|
+
"watchfiles>=0.21", # watch mode
|
|
28
|
+
"typer>=0.12", # CLI
|
|
29
|
+
"pyyaml>=6.0", # frontmatter serialization
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
[project.urls]
|
|
33
|
+
Homepage = "https://github.com/mayurpise/graphwiki"
|
|
34
|
+
Repository = "https://github.com/mayurpise/graphwiki"
|
|
35
|
+
Issues = "https://github.com/mayurpise/graphwiki/issues"
|
|
36
|
+
|
|
37
|
+
[project.optional-dependencies]
|
|
38
|
+
# Serve the generated wiki over MCP (graphwiki serve) — same 3-tool surface as
|
|
39
|
+
# DeepWiki. Optional so the base install stays lean; the tool logic (WikiIndex)
|
|
40
|
+
# has no third-party deps and is always available for embedding/testing.
|
|
41
|
+
mcp = ["mcp>=1.0"]
|
|
42
|
+
|
|
43
|
+
[project.scripts]
|
|
44
|
+
graphwiki = "graphwiki.cli:app"
|
|
45
|
+
|
|
46
|
+
[dependency-groups]
|
|
47
|
+
dev = ["pytest>=8", "ruff>=0.6", "mypy>=2.2.0", "types-PyYAML>=6.0"]
|
|
48
|
+
|
|
49
|
+
[tool.mypy]
|
|
50
|
+
python_version = "3.11"
|
|
51
|
+
ignore_missing_imports = true
|
|
52
|
+
|
|
53
|
+
[tool.pytest.ini_options]
|
|
54
|
+
testpaths = ["tests"]
|
|
55
|
+
|
|
56
|
+
[build-system]
|
|
57
|
+
requires = ["uv_build>=0.11.28,<0.12.0"]
|
|
58
|
+
build-backend = "uv_build"
|
|
59
|
+
|
|
60
|
+
# No [tool.uv.build-backend] section needed: uv_build includes the *entire*
|
|
61
|
+
# module directory (src/graphwiki/) in both sdist and wheel by default, minus
|
|
62
|
+
# __pycache__/*.pyc/*.pyo — so non-.py package data (e.g. a vendored .js under
|
|
63
|
+
# src/graphwiki/assets/) is packaged automatically without extra config.
|
|
64
|
+
# https://docs.astral.sh/uv/concepts/build-backend/
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
"""graphwiki — graph-grounded code wiki generator.
|
|
2
|
+
|
|
3
|
+
Deterministic graph traversal builds the concept work-list; the LLM writes only
|
|
4
|
+
the prose body per page. Standalone; depends on codebase-memory-mcp (MCP) and any
|
|
5
|
+
OpenAI-compatible model endpoint.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from importlib.metadata import version as _version
|
|
9
|
+
|
|
10
|
+
# Single-sourced from installed package metadata (pyproject.toml is authoritative);
|
|
11
|
+
# no second copy of the version number to drift out of sync.
|
|
12
|
+
__version__ = _version("graphwiki")
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Vendored viewer assets
|
|
2
|
+
|
|
3
|
+
`mermaid.min.js` — the **self-contained UMD** build of [Mermaid] v11, bundled so
|
|
4
|
+
the web viewer (`graphwiki serve`) renders diagrams with **no CDN / no network**
|
|
5
|
+
(air-gapped safe). It exposes `window.mermaid` when loaded via a classic
|
|
6
|
+
`<script>` tag; `src/graphwiki/web.py` serves it at `/assets/mermaid.min.js` and
|
|
7
|
+
falls back to the jsDelivr CDN only when this file is absent.
|
|
8
|
+
|
|
9
|
+
Do **not** use the `.../mermaid@11/+esm` endpoint here: that bundle lazy-loads
|
|
10
|
+
~50 diagram chunks and dependency modules from jsDelivr at runtime, so it breaks
|
|
11
|
+
offline. The `dist/mermaid.min.js` UMD build inlines everything.
|
|
12
|
+
|
|
13
|
+
## Refresh (pin to a new Mermaid version)
|
|
14
|
+
|
|
15
|
+
curl -L https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js \
|
|
16
|
+
-o src/graphwiki/assets/mermaid.min.js
|
|
17
|
+
|
|
18
|
+
Verify it is self-contained (should print `0`):
|
|
19
|
+
|
|
20
|
+
grep -c '"/npm/' src/graphwiki/assets/mermaid.min.js
|
|
21
|
+
|
|
22
|
+
[Mermaid]: https://mermaid.js.org/
|