gemini-KG-RAG-coding-expert

Graph-RAG source toolkit for indexing Gemini documentation and application code into an interpretable, named-dimension knowledge graph with hybrid retrieval and an MCP interface.

Status: The v0.1 implementation and 65-test suite are complete. This source release intentionally excludes the generated kg_rag.db and the author's source corpus; rebuild the database from content you are permitted to index before using the retrieval CLI or MCP server.

Quick start

python -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[retrieval,test]"
python -m pytest -q

The final command should report 65 passed.

Termux / Python 3.14 verification

When Termux already provides NumPy and pytest as native system packages, reuse them instead of building NumPy from its source distribution:

python -m venv --system-site-packages .venv
. .venv/bin/activate
python -m pip install --no-deps -e ".[retrieval,test]"
python -m pytest -q

This sequence also reports 65 passed. --no-deps is appropriate only when the listed extras are already available from the system Python.

Build a local knowledge graph

The repository does not redistribute the Gemini SDK documentation or the private application corpora used by the author. Build a source-specific database from your own Markdown files, score its named dimensions, and then start the MCP server:

python scripts/ingest_markdown.py --paths path/to/your/docs
python scripts/score_heuristic.py
python -m pip install -e ".[retrieval,mcp]"
python -m src.server

scripts/ingest_typescript.py is an optional corpus adapter whose default roots describe the author's workstation. Edit or adapt CLI_ROOT and MVP_ROOTS before using it with another checkout. The repo-local .mcp.json uses the checkout as its working directory; install the retrieval and mcp extras in the Python environment used by your MCP client.

Architecture in one paragraph

SQLite single-file store with 10 node types and 11 edge types. Each node carries a 50-dimension named-attribute embedding (interpretable, no neural model). Retrieval is hybrid: 0.40·cosine + 0.45·BM25 + 0.15·graph boost, with automatic deprecation filtering via valid_until. An eight-tool Python MCP server exposes the retrieval surface.

Why it exists

The earlier chunk-RAG approach exhibited five recurring failure modes: relevant documents ranked too low, duplicate chunks, excessive context, deprecated APIs in results, and application examples absent from retrieval. This project explores explicit graph structure and interpretable dimensions as remedies.

Author

Eyal Nof. See CLAUDE.md for project-level Claude operating instructions and project.ctx for the architecture graph.