# 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

```sh
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:

```sh
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:

```sh
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](CLAUDE.md) for project-level Claude operating instructions and [project.ctx](project.ctx) for the architecture graph.