# OpenAI Cookbook KG-RAG

A local retrieval toolkit that turns OpenAI Cookbook notebooks and Markdown into a searchable vector index and knowledge graph, then exposes the results through a CLI or MCP server.

The OpenAI Cookbook is an input corpus, not bundled source. This repository ships
the ingestion, graph, retrieval, evaluation, CLI, and MCP implementation; cloned
cookbooks, generated chunks, embeddings, caches, and SQLite databases remain local.
Gemini is used for ingest-time embeddings and entity extraction, so live ingestion
requires a Gemini API key. The smoke suite itself makes no live API calls.

## Install and verify

Python 3.11 or newer is recommended. On Termux, `--system-site-packages` reuses
native packages such as NumPy instead of attempting incompatible manylinux wheels.

```sh
python -m venv --system-site-packages .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
python smoke_test.py
```

In a fresh clone, data-integrity checks are reported as skipped because generated
indexes are intentionally absent. All unit and source-level smoke checks should pass.

## Use it

Set `GEMINI_API_KEY` in the environment or in a gitignored `.env.local`, then ingest
a local checkout of the Cookbook or another notebook/Markdown directory:

```sh
git clone https://github.com/openai/openai-cookbook.git openai-cookbooks
python openai-cookbook-agent.py --ingest --source ./openai-cookbooks --limit 10
python openai-cookbook-agent.py --build-kg
python openai-cookbook-agent.py --query "how do I stream responses?" --no-interactive
```

Run `python openai-cookbook-agent.py --help` for the complete CLI. Generated state
is written beneath `sources/`, `embeddings/`, `kg/`, and `.cache/`; all are ignored.

## MCP configuration

After installation and ingestion, add the server to your MCP client, replacing the
placeholder with the checkout's absolute path:

```json
{
  "mcpServers": {
    "openai-cookbook": {
      "command": "/absolute/path/to/openai-cookbook-kg-rag/.venv/bin/python",
      "args": [
        "/absolute/path/to/openai-cookbook-kg-rag/openai-cookbook-agent.py",
        "--serve-mcp"
      ],
      "env": {
        "GEMINI_API_KEY": "set-this-in-your-private-client-config"
      }
    }
  }
}
```

The server provides tools for semantic search, code exemplars, knowledge-graph
statistics, and cached retrieval.

## License

Apache-2.0. The separately cloned OpenAI Cookbook retains its own license and is not
redistributed by this repository.