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.

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:

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:

{
  "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.