From 2db5d966f26ec26ee1ca75bf2175ef759b256f4c Mon Sep 17 00:00:00 2001 From: sachinampity <83079912+sachinampity@users.noreply.github.com> Date: Tue, 12 May 2026 14:25:52 +0530 Subject: [PATCH] docs: comprehensive README overhaul with prerequisites, extras, env vars, troubleshooting, dev setup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- README.md | 185 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 179 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index cc75664a..afe14457 100644 --- a/README.md +++ b/README.md @@ -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
Contributing +### 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: ` / `feat: ` / `docs: ` +- 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.