docs: comprehensive README overhaul with prerequisites, extras, env vars, troubleshooting, dev setup

Added sections: - Prerequisites — Python 3.10+ requirement with per-OS install commands (Homebrew, winget, apt) - Optional extras table — all graphifyy[...] extras with what each adds and install command - Environment variables — consolidated reference for all GRAPHIFY_* vars and API keys needed for headless/CI extraction (ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY, MOONSHOT_API_KEY, OLLAMA_BASE_URL/MODEL, GRAPHIFY_MAX_WORKERS, etc.) - Troubleshooting — 8 common issues with exact fix commands (PATH, PowerShell slash, Ollama VRAM, graph.json merge conflicts, empty extraction, version mismatch) - Development setup (inside Contributing) — editable install steps, venv creation, pytest instructions, git workflow, macOS case-sensitive fixture note Preserved all existing content unchanged: logo, badges, star chart, translations, platform install tables, full command reference, privacy section, Penpax section. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-07-14 03:17:28 +00:00 · 2026-05-12 14:25:52 +05:30
parent 094d8ba731
commit 2db5d966f2
1 changed files with 179 additions and 6 deletions
@@ -47,19 +47,57 @@ graphify export callflow-html

 ---

-## Install
+## Prerequisites

-**Requires Python 3.10+**
+| Requirement | Minimum | Check | Install |
+|---|---|---|---|
+| Python | 3.10+ | `python --version` | [python.org](https://www.python.org/downloads/) |
+| uv *(recommended)* | any | `uv --version` | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
+| pipx *(alternative)* | any | `pipx --version` | `pip install pipx` |

+**macOS quick install (Homebrew):**
 ```bash
-uv tool install graphifyy && graphify install
-# or: pipx install graphifyy && graphify install
-# or: pip install graphifyy && graphify install
+brew install python@3.12 uv
 ```

+**Windows quick install:**
+```powershell
+winget install astral-sh.uv
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt install python3.12 python3-pip pipx
+# or install uv:
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+---
+
+## Install
+
 > **Official package:** The PyPI package is `graphifyy` (double-y). Other `graphify*` packages on PyPI are not affiliated. The CLI command is still `graphify`.

-> **PowerShell note:** Use `graphify .` not `/graphify .` — the leading slash is a path separator in PowerShell and will cause a "not recognized" error.
+**Step 1 — install the package:**
+
+```bash
+# Recommended (uv puts graphify on PATH automatically):
+uv tool install graphifyy
+
+# Alternatives:
+pipx install graphifyy
+pip install graphifyy
+```
+
+**Step 2 — register the skill with your AI assistant:**
+
+```bash
+graphify install
+```
+
+That's it. Open your AI assistant and type `/graphify .`
+
+> **PowerShell note:** Use `graphify .` not `/graphify .` — the leading slash is a path separator in PowerShell.

 > **`graphify: command not found`?** Use `uv tool install graphifyy` or `pipx install graphifyy` — both put the CLI on PATH automatically. With plain `pip`, add `~/.local/bin` (Linux) or `~/Library/Python/3.x/bin` (Mac) to your PATH, or run `python -m graphify`.

@@ -89,6 +127,27 @@ uv tool install graphifyy && graphify install
 > Codex users: also add `multi_agent = true` under `[features]` in `~/.codex/config.toml`.
 > Codex uses `$graphify` instead of `/graphify`.

+### Optional extras
+
+Install only what you need:
+
+| Extra | What it adds | Install |
+|---|---|---|
+| `pdf` | PDF extraction | `pip install "graphifyy[pdf]"` |
+| `office` | `.docx` and `.xlsx` support | `pip install "graphifyy[office]"` |
+| `google` | Google Sheets rendering | `pip install "graphifyy[google]"` |
+| `video` | Video/audio transcription (faster-whisper + yt-dlp) | `pip install "graphifyy[video]"` |
+| `mcp` | MCP stdio server | `pip install "graphifyy[mcp]"` |
+| `neo4j` | Neo4j push support | `pip install "graphifyy[neo4j]"` |
+| `svg` | SVG graph export | `pip install "graphifyy[svg]"` |
+| `leiden` | Leiden community detection (Python < 3.13 only) | `pip install "graphifyy[leiden]"` |
+| `ollama` | Ollama local inference | `pip install "graphifyy[ollama]"` |
+| `openai` | OpenAI / OpenAI-compatible APIs | `pip install "graphifyy[openai]"` |
+| `gemini` | Google Gemini API | `pip install "graphifyy[gemini]"` |
+| `bedrock` | AWS Bedrock (uses IAM, no API key) | `pip install "graphifyy[bedrock]"` |
+| `sql` | SQL schema extraction | `pip install "graphifyy[sql]"` |
+| `all` | Everything above | `pip install "graphifyy[all]"` |
+
 ---

 ## Make your assistant always use the graph
@@ -247,6 +306,29 @@ The MCP server gives your assistant structured access: `query_graph`, `get_node`

 ---

+## Environment variables
+
+These are only needed for **headless / CI extraction** (`graphify extract`). When running via the `/graphify` skill inside your IDE, the model API is provided by your IDE session — no extra keys needed.
+
+| Variable | Used for | When required |
+|---|---|---|
+| `ANTHROPIC_API_KEY` | Claude (Anthropic) backend | `--backend claude` |
+| `GEMINI_API_KEY` or `GOOGLE_API_KEY` | Google Gemini backend | `--backend gemini` |
+| `OPENAI_API_KEY` | OpenAI or OpenAI-compatible APIs | `--backend openai` |
+| `MOONSHOT_API_KEY` | Kimi Code backend | `--backend kimi` |
+| `OLLAMA_BASE_URL` | Ollama local inference URL | `--backend ollama` (default: `http://localhost:11434`) |
+| `OLLAMA_MODEL` | Ollama model name | `--backend ollama` (default: auto-detect) |
+| `GRAPHIFY_OLLAMA_NUM_CTX` | Override Ollama KV-cache window size | optional — auto-sized by default |
+| `GRAPHIFY_OLLAMA_KEEP_ALIVE` | Minutes to keep Ollama model loaded | optional — set `0` to unload after each chunk |
+| `AWS_*` / `~/.aws/credentials` | AWS Bedrock — standard credential chain | `--backend bedrock` (no API key, uses IAM) |
+| `GRAPHIFY_MAX_WORKERS` | AST parallelism thread count | optional — also `--max-workers` flag |
+| `GRAPHIFY_MAX_OUTPUT_TOKENS` | Raise output cap for dense corpora | optional — e.g. `32768` for large files |
+| `GRAPHIFY_API_TIMEOUT` | HTTP timeout in seconds (default: 600) | optional — also `--api-timeout` flag |
+| `GRAPHIFY_FORCE` | Force graph rebuild even with fewer nodes | optional — also `--force` flag |
+| `GRAPHIFY_GOOGLE_WORKSPACE` | Auto-enable Google Workspace export | optional — set to `1` |
+
+---
+
 ## Privacy

 - **Code files** — processed locally via tree-sitter. Nothing leaves your machine.
@@ -256,6 +338,54 @@ The MCP server gives your assistant structured access: `query_graph`, `get_node`

 ---

+## Troubleshooting
+
+**`graphify: command not found` after `pip install graphifyy`**
+pip installs scripts to a user bin directory that may not be on your PATH. Fix:
+- macOS: add `~/Library/Python/3.x/bin` to your PATH in `~/.zshrc`
+- Linux: add `~/.local/bin` to your PATH in `~/.bashrc`
+- Or use `uv tool install graphifyy` / `pipx install graphifyy` — both manage PATH automatically.
+
+**`python -m graphify` works but `graphify` command doesn't**
+Your shell's PATH doesn't include the Python scripts directory. Use `uv` or `pipx` instead of plain `pip`.
+
+**`/graphify .` causes "path not recognized" in PowerShell**
+PowerShell treats a leading `/` as a path separator. Use `graphify .` (no slash) on Windows.
+
+**Graph has fewer nodes after `--update` or rebuild**
+If a refactor deleted files, the old nodes linger. Pass `--force` (or set `GRAPHIFY_FORCE=1`) to overwrite even when the rebuild has fewer nodes.
+
+**Ollama runs out of VRAM / context window exceeded**
+The KV-cache window is auto-sized but may be too large for your GPU. Reduce it:
+```bash
+GRAPHIFY_OLLAMA_NUM_CTX=8192 graphify extract ./docs --backend ollama --token-budget 4000
+```
+
+**Graph HTML is too large to open in a browser (>5000 nodes)**
+Skip HTML generation and use the JSON directly:
+```bash
+graphify cluster-only ./my-project --no-viz
+graphify query "..."
+```
+
+**`graph.json` has conflict markers after two devs commit at once**
+Run `graphify hook install` — it sets up a git merge driver that union-merges `graph.json` automatically so conflicts never happen.
+
+**Extraction returns empty nodes/edges for docs or PDFs**
+Docs and PDFs require an LLM call. Check that your API key is set and the backend is correct:
+```bash
+ANTHROPIC_API_KEY=sk-... graphify extract ./docs --backend claude
+```
+
+**Skill version mismatch warning in your IDE**
+Your installed graphify version is different from the skill file. Update:
+```bash
+uv tool upgrade graphifyy
+graphify install  # overwrites the skill file
+```
+
+---
+
 ## Full command reference

 ```
@@ -365,6 +495,49 @@ Built for people whose work lives across hundreds of conversations and documents
 <details>
 <summary>Contributing</summary>

+### Development setup
+
+Clone the repo and install in editable mode:
+
+```bash
+git clone https://github.com/safishamsi/graphify.git
+cd graphify
+git checkout v7                        # active development branch
+
+# Create a virtual environment (Python 3.10+ required):
+python3 -m venv .venv
+source .venv/bin/activate              # Windows: .venv\Scripts\activate
+
+# Install in editable mode with all optional extras:
+pip install -e ".[all]"
+```
+
+Verify the editable install:
+```bash
+graphify --version
+python -c "import graphify; print(graphify.__file__)"
+```
+
+### Running tests
+
+```bash
+pip install pytest
+pytest tests/ -q                       # run the full suite
+pytest tests/test_extract.py -q        # one module
+pytest tests/ -q -k "python"           # filter by name
+```
+
+> macOS note: the test suite includes both `sample.f90` and `sample.F90` fixtures. These collide on case-insensitive HFS+ / APFS file systems. Run on Linux or in a Docker container if you need to test both Fortran variants simultaneously.
+
+### Git workflow
+
+- Active development happens on the `v7` branch.
+- Commit style: `fix: <description>` / `feat: <description>` / `docs: <description>`
+- Before opening a PR, run `pytest tests/ -q` and confirm it passes.
+- Add a fixture file to `tests/fixtures/` and tests to `tests/test_languages.py` for any new language extractor.
+
+### What to contribute
+
 **Worked examples** are the most useful contribution. Run `/graphify` on a real corpus, save the output to `worked/{slug}/`, write an honest `review.md` covering what the graph got right and wrong, and open a PR.

 **Extraction bugs** — open an issue with the input file, the cache entry (`graphify-out/cache/`), and what was missed or wrong.