Skip to main content
Glama

Universal Technical RAG Tutor (rag-tutor)

Agnostic, sovereign local AI tutor for technical books (Software Engineering, Kubernetes Internals, Databases, Systems Programming in Rust/Go, Platform Engineering, AI Agents, and Cloud-Native Architectures).

IMPORTANT

BYOB (Bring Your Own Books) Philosophy & Universal Applicability:

  • You bring your own books: This repository is a 100% open-source software engine and does not distribute, host, or bundle copyrighted books; the books/ directory is intentionally empty.

  • Works with ANY technical book: While the initial reference benchmark was validated with 22 sources covering Cloud-Native and Platform Engineering, the engine is completely agnostic: you can drop in books on Databases (PostgreSQL, Redis), Frontend (React, TypeScript), Low-level Systems (Rust, Go, C++), Cybersecurity, Networking, or internal engineering handbooks. The system auto-profiles and auto-classifies them on first ingestion.

It implements a hybrid retrieval architecture (Vector + BM25 with Cross-Encoder Reranker), a lightweight agentic self-reflection loop, and dual exposure (MCP Server + REST API), architecturally decoupled to iteratively scale into Omnigraph (GraphRAG).

Consult the architectural decision record in ARCHITECTURE.md, the comprehensive strategic & LLM-free usage guide in STRATEGIC_GUIDE_AND_USAGE.md, the universal metadata engine in METADATA_SYSTEM.md, the open certifications multi-MCP integration in CERTIFICATION_TUTOR_MCP.md, the complete live demo runbook in DEMO_RUNBOOK_EN.md, the command cheatsheet in CHEATSHEET_DEMO_COMMANDS.md, the real use cases and setup walkthrough in USE_CASES_AND_EXAMPLES.md, the AI disclosure and guardrails in AI_DISCLOSURE_AND_GUARDRAILS.md, and reproducible empirical tests in VERIFICATION_TESTS.md.


Project Structure

rag-tutor/
├── books/                     # Place your technical books/folders here (git-ignored)
│   └── .gitkeep
├── chroma_db/                 # Persistent vector database (ChromaDB, git-ignored)
├── bm25_index.pkl             # Inverted BM25 lexical index for exact code tokens (git-ignored)
├── data/kuzu_db/              # Embedded KùzuDB property graph database (git-ignored)
├── docker-compose.yml         # Optional container for Omnigraph lakehouse daemon
├── src/
│   ├── __init__.py
│   ├── config.py              # Centralized configuration and engine selector (default: omnigraph)
│   ├── core.py                # Agentic Tutor Core with self-reflection loop & retrieve_only mode
│   ├── cli.py                 # CLI with SQL-like WHERE filters (--min-year, --domain, --tag, --no-llm)
│   ├── ingest.py              # Multi-format incremental ingestion with 3-layer SHA-256 deduplication
│   ├── ingest_graph.py        # Dynamic GraphRAG & KùzuDB ontology builder (Phase 2)
│   ├── metadata_engine.py     # Universal deterministic profiler (year, domain, tags, sections, syntax)
│   ├── graph_schema.py        # Schema of nodes and edges for the knowledge graph
│   ├── kuzu_graph.py          # Embedded KùzuDB Cypher query engine for GraphRAG
│   ├── schemas.py             # Pydantic contract schemas for syllabus and external MCPs
│   ├── mcp_server.py          # Progressive Zero-Token-Burn MCP server (5 specialized tools)
│   ├── api.py                 # FastAPI REST API & Tri-MCP Gateway with WHERE filter support
│   └── retrievers/
│       ├── __init__.py
│       ├── base.py            # Abstract BaseRetriever and RetrievedChunk interfaces
│       ├── hybrid.py          # Phase 1: ChromaDB + BM25 + Cross-Encoder Reranker + WHERE filters
│       └── omnigraph.py       # Phase 2: KùzuDB Cypher + Hybrid + Cross-Encoder Reranker
├── tests/
│   └── test_no_llm_pipeline.py # Automated end-to-end test suite (Zero LLM / No Ollama required)
├── requirements.txt           # Python dependencies
├── test_multi_mcp_live.py     # Live Tri-MCP verification (study-cybercirujas + k8s-docs-mcp + rag-tutor)
├── STRATEGIC_GUIDE_AND_USAGE.md # Complete operational guide, KùzuDB breakdown & architecture patterns
├── DEMO_RUNBOOK_EN.md         # Live demo runbook: Study platform, Open WebUI, Ollama & Tri-MCP
├── DEMO_RUNBOOK_STUDY_OPENWEBUI.md # Direct alias for DEMO_RUNBOOK_EN.md
├── CHEATSHEET_DEMO_COMMANDS.md # Quick reference for CLI, cURL, MCP & hardware checks
├── GLOSSARY.md                # Educational technology glossary with real-world analogies
├── ARCHITECTURE.md            # Architecture Decision Records (ADRs) and roadmap
├── METADATA_SYSTEM.md         # Universal zero-config metadata engine documentation
├── CERTIFICATION_TUTOR_MCP.md # Open WebUI + MCP integration with study-cybercirujas
├── HOW_TO_MULTI_MCP_101.md    # Beginner 101 guide: How agents coordinate multiple MCP servers
├── USE_CASES_AND_EXAMPLES.md  # Step-by-step setup walkthrough and real terminal outputs
├── RESEARCH_AND_LESSONS_LEARNED.md # Multi-MCP orchestration research, challenges & solutions
├── AI_DISCLOSURE_AND_GUARDRAILS.md # Transparency, traceability, and guardrails (EU AI Act)
├── VERIFICATION_TESTS.md      # Empirical verification test report and reproduction steps
├── LICENSE                    # Apache 2.0 Open Source License
└── README.md
NOTE

Understanding knowledge_graph.json (Seed Ontology Template): knowledge_graph.json (~7 KB) is provided as an out-of-the-box seed ontology template demonstrating how Phase 2 GraphRAG traverses entities and directional relationships. It contains zero copyrighted text (unlike vector embeddings). You are not required to keep this specific data: you can freely customize entities in src/ingest_graph.py or regenerate it for your specific engineering domains.


Related MCP server: tech-doc-mcp

Iterative Roadmap

  • Phase 1 (Hybrid Foundation):

    • Code-aware chunking optimized for YAML and Go syntax (verified with 22 sources, 8,516 pages, 23,343 chunks).

    • Hybrid retrieval (Chroma semantic dense search + BM25 exact lexical match).

    • Local reranking via Cross-Encoder (ms-marco-MiniLM-L-6-v2).

    • Agentic RAG reflection loop (context sufficiency evaluation in max 2 steps).

    • MCP Server compatible with mcp 2.x (MCPServer) + FastAPI REST API + interactive CLI.

  • Phase 2 (GraphRAG / KùzuDB / Omnigraph):

    • Ontological schema definition (src/graph_schema.py) with domain entities and relations.

    • Embedded KùzuDB Cypher Engine (src/kuzu_graph.py) for sub-millisecond local graph traversals without Docker daemons.

    • Graph generator persisting into knowledge_graph.json (src/ingest_graph.py).

    • Dual-mode OmnigraphRetriever connector: remote HTTP querying to Omnigraph daemon or local in-memory/KùzuDB relationship traversal.

    • Container deployment ready with Docker Compose (docker-compose.yml).


Universal Metadata Engine (Zero-Config)

The system features a deterministic auto-cataloging engine that supports any technical book (PostgreSQL, React, Rust, Cybersecurity, Kubernetes, etc.) without manual tagging:

flowchart LR
    A["Drop any PDFs into books/"] --> B["python src/ingest.py"]
    B --> C["1. Document Lexical Profiling\n(Assigns domain: cloud_native, databases, web, etc.)"]
    B --> D["2. Chunk Syntax Detection\n(has_code: true, code_lang: yaml, sql, rust, etc.)"]
    C & D --> E["ChromaDB + BM25 with Scalar Pre-filtering"]
  1. Auto-Profiling on Ingestion (Zero-Config): When you place PDFs in books/ and run python src/ingest.py, the system reads the table of contents (TOC) and initial pages, automatically assigning the domain (cloud_native, databases_and_storage, web_and_frontend, systems_programming, devsecops, ai_agents, mlops, general_technical), persisting it to metadata_registry.json.

  2. Chunk-Level Syntax Detection: Pure regex analysis checks for code blocks, tagging each chunk with has_code: true and its exact language (yaml | go | python | sql | rust | bash | typescript).

  3. High-Precision Filtered Retrieval: Enables CLI users, MCP agents, and HTTP clients to filter by domain and language, eliminating cross-domain noise and accelerating retrieval.

Read the detailed guide with practical examples in METADATA_SYSTEM.md.


Optional Hugging Face Authentication (HF_TOKEN)

NOTE

The system operates 100% locally and offline without requiring accounts or logins.
Embedding and reranking models run from local cache (~/.cache/huggingface/hub) under HF_HUB_OFFLINE=1.

If you ever wish to connect your personal Hugging Face account for higher download rate limits or private models:

  1. Create a free Read token at huggingface.co/settings/tokens.

  2. Set it in your environment:

    export HF_TOKEN="hf_your_token_here"

    Or via the official CLI:

    huggingface-cli login

If no token is set, warnings are automatically suppressed and execution runs silently offline.


Prerequisites

  • Python: 3.10 or higher (3.11 recommended).

  • Ollama: Running locally with your chosen model (e.g., qwen2.5:7b):

    ollama pull qwen2.5:7b

Installation & Setup

  1. Create and activate a virtual environment:

    python -m venv .venv
    source .venv/bin/activate
  2. Install dependencies:

    pip install -r requirements.txt
  3. Place your technical books or video courses (Any format / topic / vendor):

    • Copy your .pdf, .md (or book/course folders containing Markdown/*.md), .txt, .json, .jsonl, .vtt, or .srt files into the books/ folder. The system is 100% standalone, auto-extracts the publication year (publication_year), content type (video_course vs book), domain, tags, hands-on exercises (has_exercises), and chapter/section tree (sections), citing exact minute ranges (@ [MM:SS - MM:SS]) for video lessons.

  4. Run ingestion and indexing:

    python src/ingest.py

    (Subsequent runs only process newly added or modified books incrementally via SHA-256).


Running & Automated Testing WITHOUT an LLM (No Ollama Required)

You can use and test the entire ingestion, metadata WHERE-filtering, Hybrid retrieval (ChromaDB + BM25), Cross-Encoder reranking, KùzuDB GraphRAG, and MCP tools without having Ollama or any LLM installed:

1. Run the Automated Verification Suite

python tests/test_no_llm_pipeline.py

2. Query via CLI with --no-llm (--retrieve-only) and SQL-like WHERE Filters

# Retrieve top reranked sections with WHERE filters (no LLM needed):
python src/cli.py "How to serve LLMs with vLLM on Kubernetes?" \
  --no-llm \
  --domain cloud_native \
  --min-year 2025 \
  --tag kubernetes \
  --section "Chapter"

# Filter strictly by code language (yaml, python, go, bash, sql, rust):
python src/cli.py "Deployment resource limits GPU" \
  --no-llm \
  --code yaml \
  --min-year 2024

3. Direct MCP Tool Invocation (Zero-Token-Burn for 100+ Books)

python -c "
from src.mcp_server import listar_libros_y_secciones, buscar_fragmentos_secciones
print(listar_libros_y_secciones(domain='cloud_native', min_year=2025))
print(buscar_fragmentos_secciones('vLLM Kubernetes', top_k=2, domain='cloud_native', min_year=2025, tag='kubernetes'))
"

Detailed Usage Modes

The tutor can be used in three complementary modes depending on your workflow:


Mode 1: Local Console / CLI (src/cli.py)

Fast, zero-overhead terminal queries without requiring a browser or external client.

A. Direct query argument (single-line execution)

python src/cli.py "Explain how to design a reactive AI Agent"

B. Interactive Chat loop (continuous session)

Run without arguments for an interactive REPL:

python src/cli.py
=================================================================
 📚 Universal Technical AI Tutor (Interactive Console)
 Type your technical query or 'exit' / 'quit' to quit.
=================================================================

> Question:
Explain the concept of Paved Roads in Platform Engineering

[... generates technical synthesis with book citations ...]

> Question:
exit
Goodbye!

Mode 2: MCP Server - Model Context Protocol (src/mcp_server.py)

Exposes your book library as native function-calling tools to external AI agents in your terminal or IDE (such as Claude Desktop, Goose CLI, or Antigravity).

Start the server manually (stdio):

python src/mcp_server.py

Exposed Tools (two-step, token-budgeted):

  1. buscar_fragmentos_secciones(consulta, top_k=5, formato, max_tokens, domain, code_lang, libro, min_year, tag, seccion):

    • Hybrid search + reranker, no LLM. Returns pointers: [id] book (year) > chapter > section · ~N tok plus a one-line excerpt (~90 tokens per hit). formato="completo" returns the full text in the same call, within max_tokens.

  2. leer_fragmentos(ids, max_tokens=1500, vecinos=0):

    • Full text of the chosen ids. Adjacent fragments are merged, the splitter overlap is removed, and when the budget cuts the answer the remaining ids are listed. vecinos adds the fragments before/after.

  3. listar_libros_y_secciones(domain, min_year, tag, libro, incluir_secciones=False):

    • One line per book (year, domain, tags). Sections only for the book passed in libro.

  4. buscar_codigo_yaml(termino, code_lang, min_year, max_tokens): manifests, CRDs and commands, verbatim.

  5. consultar_grafo_kuzu(concepto, limite=12): knowledge-graph relations of a concept.

  6. consultar_libros_manning(pregunta, ...): synthesis by the tutor's own LLM with citations. Works with any OpenAI-compatible endpoint (LLM_BASE_URL, LLM_MODEL, optional LLM_API_KEY: vLLM, KServe, llama.cpp, LiteLLM, agentgateway, OpenRouter) or with Ollama when LLM_BASE_URL is unset.

Chunk ids are deterministic (hash of book + text), outputs are plain text without a duplicated structuredContent, and tool descriptions carry nothing dynamic, so prompt/prefix caches keep hitting.

Deployment-wide caps for small-context local models: RAG_TUTOR_DEFAULT_FORMAT=completo, RAG_TUTOR_MAX_HITS=4, RAG_TUTOR_MAX_READ_TOKENS=1200.

Run over HTTP (Open WebUI, agentgateway, Claude Code):

python -m src.mcp_server --transport streamable-http --host 127.0.0.1 --port 8766   # → http://127.0.0.1:8766/mcp

Claude Desktop / Goose CLI integration (claude_desktop_config.json):

{
  "mcpServers": {
    "rag-tutor": {
      "command": "/path/to/rag-tutor/.venv/bin/python",
      "args": [
        "/path/to/rag-tutor/src/mcp_server.py"
      ]
    }
  }
}

Mode 3: REST API with FastAPI (src/api.py)

Exposes the tutor over standard HTTP, allowing integration with Web frontends, scripts, or Open WebUI.

Start the API server:

python src/api.py

Default URL: http://localhost:8000

Interactive API Documentation (Swagger UI):

Open in your browser: 👉 Open Swagger UI (http://localhost:8000/docs) You can test the POST /chat endpoint directly from the UI.

Available Endpoints:

  • GET /health: Healthcheck verifying ChromaDB, BM25, and local Ollama model connectivity.

  • GET /mcp/status: Real-time monitoring and connection status across the MCP servers (study-cybercirujas, k8s-docs-mcp, oss-docs-mcp, rag-tutor).

  • POST /mcp/test: Live diagnostics endpoint with deterministic Kind extraction, stop-word filtering, and multi-manifest retrieval across all connected MCP servers.

  • POST /chat: Query endpoint returning grounded answers, sources, and pipeline telemetry with optional Tri-MCP enrichment (orchestrate_tri_mcp: true).

Consumption examples via cURL:

# Check status of all 3 connected MCP servers:
curl -s http://localhost:8000/mcp/status | jq

# Run diagnostics with natural language query (extracts Pod, pulls 3 canonical manifests, links CKA 3.5):
curl -s -X POST http://localhost:8000/mcp/test \
  -H "Content-Type: application/json" \
  -d '{"target": "all", "query": "three example how i can create a pod yaml definition and a theory how works"}' | jq

# Ask a question with full Tri-MCP orchestration:
curl -s -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"question": "How do in-tree ValidatingAdmissionPolicies work in Kubernetes?", "orchestrate_tri_mcp": true}'

Optional 4th MCP: oss-docs-mcp (versioned AI-infra project docs)

If the sibling oss-docs-mcp is present with its index built (uv run oss-docs sync or uv run oss-docs pull there), /chat adds the top version-pinned sections from KServe, llm-d, SGLang, agentgateway, Agent Router (ex Envoy AI Gateway) or Kubeflow only when the question names one of them — or when you force it:

# auto: "KServe" in the question → kserve@latest sections are injected with their URLs
curl -s -X POST http://localhost:8000/chat -H "Content-Type: application/json" \
  -d '{"question": "How does KServe autoscale an InferenceService with KEDA?"}' | jq .mcp_enrichment

# forced project + pinned version
curl -s -X POST http://localhost:8000/chat -H "Content-Type: application/json" \
  -d '{"question": "rate limiting by tokens", "oss_docs_project": "agentgateway", "oss_docs_version": "1.6.x"}'

# diagnostics
curl -s -X POST http://localhost:8000/mcp/test -H "Content-Type: application/json" \
  -d '{"target": "oss-docs", "query": "agentgateway MCP authentication"}' | jq

Mode 4: Open WebUI Integration (Sovereign Web Chat)

You can connect Open WebUI directly to the Tri-MCP sovereign gateway using the native Python Tools system.

1. Copy-Paste Tool Code for Open WebUI:

In Open WebUI, navigate to: Workspace ➔ Tools ➔ + (Create Tool), and paste the contents of openwebui_tool_tri_mcp.py:

"""
title: Cloud Native Tri-MCP Tutor
author: Cybercirujas
author_url: https://github.com/villadalmine/rag-tutor
git_url: https://github.com/villadalmine/rag-tutor
description: Queries the Sovereign Tri-MCP Stack (technical engineering books, official CNCF/LPI syllabi, and canonical Kubernetes YAMLs)
version: 1.3.0
license: Apache-2.0
"""
import json
import requests
from typing import Optional, Dict, Any

class Tools:
    def __init__(self):
        # Internal URL reachable from the Open WebUI Docker container
        self.gateway_url = "http://host.docker.internal:8000"

    def query_tri_mcp_tutor(
        self,
        question: str,
        domain: Optional[str] = None,
        min_year: Optional[int] = None,
    ) -> str:
        """
        MANDATORY TOOL: Queries the Sovereign Trifecta (study-cybercirujas + k8s-docs-mcp + rag-tutor).
        Always invoke this tool whenever the user asks about Kubernetes, Pods, Deployments,
        services, platform architecture, AI agents, CNCF syllabi (CKA, CKAD, CKS, CNPE), or YAML syntax.
        :param question: Exact technical question to resolve.
        :param domain: Optional domain filter (e.g. 'cloud_native', 'ai_agents', 'mlops').
        :param min_year: Optional minimum publication year (e.g. 2024 or 2025).
        :return: Grounded technical synthesis with verification badge and cited sources.
        """
        url = f"{self.gateway_url}/chat"
        payload = {
            "question": question,
            "orchestrate_tri_mcp": True,
            "domain": domain,
            "min_year": min_year,
        }
        try:
            resp = requests.post(url, json=payload, timeout=90.0)
            if resp.status_code == 200:
                data = resp.json()
                answer = data.get("answer", "")
                sources = data.get("sources", [])
                enrichment = data.get("mcp_enrichment", {})

                # Build Visual Tri-MCP Verification Badge
                badge_lines = [
                    "┌──────────────────────────────────────────────────────────────┐",
                    "│ 🛡️  SOVEREIGN MULTI-MCP VERIFICATION (LIVE TELEMETRY)        │",
                    "├──────────────────────────────────────────────────────────────┤",
                ]
                obj = enrichment.get("study_objective") or "General Platform Context"
                badge_lines.append(f"│ 🎯 Study-Cybercirujas: {obj[:46]:<46} │")
                kind = enrichment.get("k8s_kind") or "Core Resource"
                api_chk = enrichment.get("k8s_api_check") or "kubernetes.io canonical spec"
                badge_lines.append(f"│ 🛡️ K8s-Docs-MCP:      {kind} ({api_chk[:30]:<30}) │")
                retriever = data.get("retriever_engine", "omnigraph")
                llm = data.get("llm_model", "local-ollama")
                badge_lines.append(f"│ 📚 RAG-Tutor Engine:  {retriever} ({llm})                     │")
                badge_lines.append("└──────────────────────────────────────────────────────────────┘")
                badge_block = "```text\n" + "\n".join(badge_lines) + "\n```"

                sources_block = ""
                if sources:
                    sources_list = "\n".join([f"- `{s}`" for s in sources])
                    sources_block = f"\n\n### 📖 Consulted Sources:\n{sources_list}"

                return f"{badge_block}\n\n{answer}{sources_block}"
            return f"Error {resp.status_code} querying tutor: {resp.text}"
        except Exception as e:
            return f"Error connecting to RAG Tutor Gateway ({self.gateway_url}): {str(e)}"

    def check_mcp_cluster_status(self) -> str:
        """Checks the live connection status of all 3 MCP servers."""
        url = f"{self.gateway_url}/mcp/status"
        try:
            resp = requests.get(url, timeout=10.0)
            if resp.status_code == 200:
                data = resp.json()
                servers = data.get("servers", {})
                status_summary = [f"### Tri-MCP Cluster Status (Operational: {data.get('tri_mcp_operational')})\n"]
                for name, s in servers.items():
                    mode_info = f" (Mode: {s.get('mode')})" if "mode" in s else ""
                    tools_list = ", ".join(s.get("tools", []))
                    status_summary.append(f"- **{name}**: `{s.get('status')}`{mode_info} | Tools: [{tools_list}]")
                return "\n".join(status_summary)
            return f"Error {resp.status_code}: {resp.text}"
        except Exception as e:
            return f"Connection error: {str(e)}"

2. Assign the Tool to Your Model in Open WebUI:

  1. Navigate to Workspace ➔ Models ➔ + (Create Model).

  2. Configure:

    • Name: Cloud Native Tutor (Tri-MCP)

    • Base Model: Select qwen3:4b-fast or qwen2.5:7b.

    • System Prompt:

      You are a Principal Platform Architect and Senior Cloud-Native Instructor.
      You have access to the 'Cloud Native Tri-MCP Tutor' tool.
      Whenever the user asks about Kubernetes, certifications (CKA, CKAD, CKS, CNPE),
      AI agents, platform architecture, or YAML manifests, invoke 'query_tri_mcp_tutor'
      to ground your answer in official sources and prevent API hallucinations.
    • Tools: Check the Cloud Native Tri-MCP Tutor box.

  3. Save the model.

IMPORTANT

Ensure the tool is toggled ON in the chat:
In the bottom chat input bar of Open WebUI, click the Tools (Puzzle 🧩) icon and confirm Cloud Native Tri-MCP Tutor is enabled. If it is unchecked, the model will respond without invoking the tool. You can audit live queries received by the Gateway in your browser at: 👉 http://localhost:8000/mcp/logs


Execution Sequence Diagram:

sequenceDiagram
    autonumber
    actor User as Engineer (Open WebUI / CLI / IDE)
    participant UI as MCP Client / Open WebUI Tool
    participant GW as RAG Tutor Gateway (:8000)
    participant Study as study-cybercirujas (:8080)
    participant K8s as k8s-docs-mcp (SQLite FTS5)
    participant RAG as RAG Tutor Engine (Chroma + BM25 + KùzuDB)
    participant LLM as Local Ollama or Frontier LLM

    User->>UI: Technical Query + WHERE Filters (domain, min_year, tag)
    UI->>GW: POST /chat (orchestrate_tri_mcp=true)
    
    par Parallel Multi-MCP Retrieval
        GW->>Study: Search CNCF syllabus & lab objectives
        Study-->>GW: Official certification objective
    and
        GW->>K8s: Validate API version & pull canonical YAMLs
        K8s-->>GW: Verified kubernetes.io manifests
    and
        GW->>RAG: Hybrid + KùzuDB Cypher GraphRAG Retrieval
        RAG-->>GW: Top-K filtered chunks [Year, Section, Code]
    end

    GW->>GW: Cross-Encoder Reranking (ms-marco-MiniLM-L-6-v2)
    GW->>LLM: Grounded prompt (~1,000 tokens of verified evidence)
    LLM-->>GW: Synthesized response with exact citations
    GW-->>UI: Payload with Sources + Telemetry + Manifests
    UI-->>User: Grounded Answer + Tri-MCP Verification Badge
TIP

For the complete list of CLI commands,curl calls, hardware validations (GPU vs CPU), Open WebUI setup steps, and cold-start instructions, consult: 👉 CHEATSHEET_DEMO_COMMANDS.md and STRATEGIC_GUIDE_AND_USAGE.md


Technologies & Upstream Repositories

Technology

Official Repository

Role in the Project

KùzuDB

kuzudb/kuzu

Embedded C++ property graph database executing declarative Cypher queries for Phase 2 GraphRAG.

ModernRelay Omnigraph

ModernRelay/omnigraph

Lakehouse-native graph database over Lance with Git-style branching for agentic state (Phase 2).

Lance

lancedb/lance

Modern columnar format for multimodal data and high-performance vector search.

ChromaDB

chroma-core/chroma

Embedded open-source vector database for dense indexing and scalar metadata pre-filtering.

Rank-BM25

dorianbrown/rank_bm25

Okapi BM25 lexical search implementation for exact code tokens, CRDs, and keywords.

Sentence-Transformers

UKPLab/sentence-transformers

Dense embedding models (all-MiniLM-L6-v2) and Cross-Encoder rerankers (ms-marco-MiniLM-L-6-v2).

LangChain Core & Community

langchain-ai/langchain

RAG orchestration abstractions, code-aware text splitters, and document loaders.

PyMuPDF (fitz)

pymupdf/PyMuPDF

High-speed C-based text, metadata, and page extraction from PDF documents.

Model Context Protocol (MCP)

modelcontextprotocol/python-sdk

Official SDK exposing progressive Zero-Token-Burn tools to agents via MCP (MCPServer / FastMCP).

FastAPI

fastapi/fastapi

Async web framework powering the REST API and interactive Swagger documentation.

Ollama

ollama/ollama

Optional local model inference engine running on consumer hardware (CPU / GPU / Apple Silicon).

Qwen 2.5 (Alibaba)

QwenLM/Qwen2.5

Open-weights foundation models used for local agentic reasoning and technical synthesis.

uv (Astral)

astral-sh/uv

High-speed Rust-based Python package manager and resolver.


📖 Educational Technology Glossary (For Technical & Non-Technical Readers)

For a clear, accessible explanation of every technology used in this ecosystem (RAG, MCP, ChromaDB, BM25, KùzuDB, Cross-Encoder, Ollama, Qwen, ROCm, etc.) with everyday real-world analogies and architectural rationale, consult: 👉 GLOSSARY.md


AI Disclosure, Transparency & Guardrails

All educational explanations generated by rag-tutor are produced by locally executed large language models. In alignment with open educational initiatives like study-cybercirujas:

  • The system functions strictly as a study aid; original engineering books and vendor documentation are the ultimate authority.

  • The pipeline implements 4 automated mechanical guardrails: Cross-Encoder Reranking, Agentic Self-Reflection Loop, Mandatory Page Citations, and Sovereign Local Data Privacy.

  • Complies with transparency and traceability standards aligned with EU AI Act Article 50.

Read the full disclosure and policy in AI_DISCLOSURE_AND_GUARDRAILS.md.


Empirical Verification Tests & Reproducibility

All claims regarding sub-350ms pre-LLM latency, dilution mitigation across 23,343 chunks, and exact page citation fidelity have been empirically validated on local hardware.

Read the execution logs, model telemetry, and reproduction instructions in VERIFICATION_TESTS.md.


Multi-MCP Research, Architecture & Lessons Learned

For an in-depth analysis of how autonomous agents can coordinate multiple MCP servers (study-cybercirujas, k8s-docs-mcp, and rag-tutor) without tool collisions, context bloat, or hallucinations, consult RESEARCH_AND_LESSONS_LEARNED.md. It covers:

  1. The Core Multi-MCP Problem: Why free-wheeling ReAct loops hallucinate and fail in production.

  2. The Separation of Powers Contract: Semantic boundary allocation between Syllabus, Specification, and Architecture.

  3. Key Implementations: SHA-256 incremental hashing, embedded KùzuDB Cypher engine, Hugo shortcode preprocessors, and SQLite FTS5 stores.

  4. Behind-the-Scenes Hurdles: Resolving batch insert limits, UTF-8 Windows stream encoding, and deterministic OpenAPI schema validation.

  5. Research Scope Notice: Clear framing of this project as an educational proof-of-concept for sovereign information access.

For an intuitive, step-by-step 101 guide explaining how an AI agent decides which MCP to consult (e.g. answering "How does etcd work in K8s?" without querying all tools blindly), read HOW_TO_MULTI_MCP_101.md.


Real Use Cases & Terminal Outputs

To see how the engine operates in practice on real hardware, consult USE_CASES_AND_EXAMPLES.md. It documents:

  1. "How I Made It Work" Walkthrough: From clean virtualenv initialization to handling ChromaDB's 5,461-chunk batch limits with 2,000-chunk slicing during ingestion.

  2. Real Terminal Output 1: Deep K8s Internals (Mutating vs Validating Admission Controllers).

  3. Real Terminal Output 2: Agentic Self-Reflection (Golden Paths & Developer Cognitive Load with automatic literature query reformulation).

  4. Real Terminal Output 3: Systems & AI Trade-offs (Fine-Tuning vs RAG).

  5. Real Terminal Output 4: Pure Lexical Retrieval (buscar_codigo_yaml for exact manifest extraction).

  6. Real Terminal Output 5: Tri-MCP Certification Study Session paired with study-cybercirujas and k8s-docs-mcp.


This repository is an open-source technical benchmark and local study tool (licensed under Apache 2.0).

  • Zero Content Redistribution (BYOB - Bring Your Own Books): This repository does NOT host, mirror, or redistribute any copyrighted book files, PDFs, full chapters, or commercial training datasets. Users must supply their own legally acquired reference documents in their local data/ or books/ directory.

  • Index Privacy & Data Sovereignty: Vector databases (chroma_db/), lexical indexes (bm25_index.pkl), and private model caches are strictly excluded via .gitignore to prevent distributing derivative mathematical representations of private texts.

  • Nominative Fair Use of Book Titles & Citations: All book titles (Effective Platform Engineering, Core Kubernetes, GitOps and Kubernetes), publisher names (e.g. Manning Publications), and author attributions appearing in benchmark logs or citation metadata are the property of their respective copyright holders. Under international copyright law and US Fair Use principles (Circular 33, US Copyright Office), titles and short factual identifiers are not copyrightable; they are referenced strictly for bibliographic citation, scholarly attribution, and academic reproducibility.

  • Educational Scope: The system functions purely as an educational retrieval agent. The authoritative technical sources remain the original books and official documentation.


License

This project is licensed under the Apache License 2.0. See LICENSE for details.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI agents with research capabilities for local Calibre e-book libraries, including fulltext search across titles, ISBNs, and comments, plus structured excerpt retrieval from books.
      2
      GPL 3.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables coding agents to query local notes, decisions, docs, and code with hybrid retrieval (BM25 + embeddings + reranking) and get path:line citations. It provides tools like rag_query for full-corpus search and search_knowledge for project-scoped knowledge recall.
      2
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables local-first hybrid knowledge retrieval from authorized Markdown and plain-text files, combining full-text and vector search with reranking and traceable source references via a single search tool.
      1
      MIT