### Start `wr-server` OpenAI-compatible HTTP Server

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Provides commands to start the `wr-server` using default configuration or with Docker. The API documentation is available at http://localhost:8080/docs.

```bash
# Start with defaults from config.yml (wrapper.api_base = "0.0.0.0:8080")
wr-server
```

```bash
# With Docker
docker run --rm \
  --volume $(pwd)/config.yml:/app/config.yml \
  --volume $(pwd)/.env:/app/.env \
  --publish 8080:8080 \
  ghcr.io/moodlehq/wiki-rag:latest
```

--------------------------------

### Start `wr-mcp` MCP HTTP Server

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Commands to start the `wr-mcp` server using default configuration or to connect Claude Desktop by adding specific configurations to `claude_desktop_config.json`.

```bash
# Start with defaults from config.yml (mcp.api_base = "0.0.0.0:8081")
wr-mcp
```

```bash
# Connect Claude Desktop (add to claude_desktop_config.json):
# {
#   "mcpServers": {
#     "wiki-rag": {
#       "command": "wr-mcp",
#       "env": {"AUTH_TOKENS": "my-secret-token"}
#     }
#   }
# }
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/moodlehq/wiki-rag/blob/main/README.md

Install the project dependencies using pip. For development, install extra dependencies and set up pre-commit hooks.

```bash
pip install -e .
```

```bash
pip install -e .[dev]  # To install all the development dependencies.
pre-commit install     # To enable all the check (style, lint, commits, etc.)
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/moodlehq/wiki-rag/blob/main/CONTRIBUTING.md

Clone your forked repository and install development dependencies. Ensure pre-commit hooks are enabled for code style checks.

```bash
git clone https://github.com/your-username/wiki-rag.git
cd wiki-rag
pip install .[dev]
pre-commit install
```

--------------------------------

### OpenAI-Compatible Server

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

The `wr-server` CLI starts an OpenAI-compatible HTTP server that can be used with the OpenAI Python client.

```APIDOC
## OpenAI-Compatible Server

### Description
Starts an OpenAI-compatible HTTP server. This server can be used with the OpenAI Python client to interact with the RAG system.

### CLI Command
```bash
wr-server
```

### Docker Usage
```bash
docker run --rm \
  --volume $(pwd)/config.yml:/app/config.yml \
  --volume $(pwd)/.env:/app/.env \
  --publish 8080:8080 \
  ghcr.io/moodlehq/wiki-rag:latest
```

### API Docs
Available at: `http://localhost:8080/docs`
```

--------------------------------

### CLI: `wr-mcp`

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

The `wr-mcp` CLI command starts the MCP HTTP server, enabling interaction with MCP tools and resources.

```APIDOC
## CLI: `wr-mcp` — Start the MCP HTTP server

### Description
Starts the MCP HTTP server, which allows clients to interact with the MCP tools and resources.

### Command
```bash
wr-mcp
```

### Configuration Example (Claude Desktop)
To connect Claude Desktop, add the following to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "wiki-rag": {
      "command": "wr-mcp",
      "env": {"AUTH_TOKENS": "my-secret-token"}
    }
  }
}
```
```

--------------------------------

### Run Wiki-RAG with Docker Compose

Source: https://github.com/moodlehq/wiki-rag/blob/main/README.md

Starts Wiki-RAG and its dependencies using Docker Compose. Ensure config.yml and .env files are in the same directory. The data and volumes directories will be created in the current directory.

```bash
docker compose up -d
```

--------------------------------

### Run Test Suite

Source: https://github.com/moodlehq/wiki-rag/blob/main/CONTRIBUTING.md

Execute the test suite to verify that your changes have not introduced any regressions. Adjust the command based on your specific testing setup.

```bash
# Adjust this command to match your testing setup
python -m unittest discover
```

--------------------------------

### MCP Resources: Accessing Parsed Dump Data

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Provides examples of accessing parsed dump data using MCP resources like `get_pages/{start}/{number}`, `get_10_pages`, and `get_100_pages`. These serve slices of the most recent parsed JSON dump.

```python
# Resource: resource://get_pages/1/5
# Returns pages 1–5 from the latest dump as a list of page dicts.
# Each page contains: id, title, sections (with text, source, relationships),
# categories, templates, internal_links, external_links, language_links.

# Resource: resource://get_10_pages  → first 10 pages
# Resource: resource://get_100_pages → first 100 pages
```

--------------------------------

### Configure Coloured Console Logging

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Configures coloured console logging with ISO 8601 UTC timestamps by installing a `colorlog` handler. The `LOG_LEVEL` environment variable must be set before module import.

```bash
# Set before launching any wr-* command
LOG_LEVEL=DEBUG wr-search "test question"
# 2025-06-01T12:00:00.123Z DEBUG [wiki_rag.search.util] Contextualising the question: test question
# 2025-06-01T12:00:00.456Z DEBUG [wiki_rag.vector.milvus] Retrieved 15 results
```

--------------------------------

### GET /v1/models

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Lists the available models supported by the OpenAI-compatible server. It returns a list containing a single model identifier.

```APIDOC
## GET /v1/models

### Description
Retrieves a list of available models. The response includes a single model identifier, typically derived from the collection name or wrapper configuration, formatted to match the OpenAI API specification.

### Method
GET

### Endpoint
`/v1/models`

### Headers
- **Authorization** (string) - Required - Bearer token for authentication (`Bearer <token>`)

### Response
#### Success Response (200)
- **object** (string) - The type of the response object, usually "list".
- **data** (array) - An array of model objects.
  - **id** (string) - The unique identifier for the model.
  - **object** (string) - The type of the model object, usually "model".
  - **created** (integer) - Timestamp of model creation.
  - **owned_by** (string) - The owner of the model.

### Request Example
```bash
curl -s http://localhost:8080/v1/models \
  -H "Authorization: Bearer my-secret-token" | python3 -m json.tool
```

### Response Example
```json
{
  "object": "list",
  "data": [
    {
      "id": "moodle-docs",
      "object": "model",
      "created": 1748800000,
      "owned_by": "Moodle Docs"
    }
  ]
}
```
```

--------------------------------

### Build LangGraph RAG State Machine with Python

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Assembles the five-node RAG pipeline: query_rewrite, hyde_rewrite, retrieve, optimise, and generate. Routes to END for chitchat. Requires configuration and context setup.

```python
import wiki_rag.vector as vector
from wiki_rag.config import load_config
from wiki_rag.search.util import build_context_schema, build_graph
from wiki_rag.vector import load_vector_store

cfg = load_config(command="search")
vector.store = load_vector_store(cfg.index_vendor)

context = build_context_schema(cfg, stream=False)
graph = build_graph(context)

# Non-streaming invocation
import asyncio

response = asyncio.run(
    graph.ainvoke(
        input={"question": "How do I install Moodle on Ubuntu?", "history": []},
        context=context,
    )
)
print(response["answer"])
# "To install Moodle on Ubuntu, first ensure you have PHP 8.x and a supported
#  database (MySQL/PostgreSQL) installed. Then clone the repository into your
#  web root... [source links]"
```

--------------------------------

### Download Milvus Standalone Docker Compose

Source: https://github.com/moodlehq/wiki-rag/blob/main/README.md

Downloads the Milvus standalone Docker Compose file using wget or curl. This file is needed for the all-in-one Docker Compose setup.

```bash
wget https://github.com/milvus-io/milvus/releases/download/v2.6.2/milvus-standalone-docker-compose.yml -O milvus-standalone.yml
```

```bash
curl https://github.com/milvus-io/milvus/releases/download/v2.6.2/milvus-standalone-docker-compose.yml -o milvus-standalone.yml
```

--------------------------------

### MCP Tool: `retrieve` for Raw Vector Search Results

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Illustrates how to use the `retrieve` MCP tool to get raw vector search results from the vector store. This is useful for custom post-processing pipelines.

```python
# Via MCP client (e.g., Claude Desktop or any MCP-compatible client)
# Tool: retrieve
# Input: [{"role": "user", "content": "How do I backup a Moodle course?"}]
# Output:
# {
#   "vector_search": [
#     {
#       "distance": 0.87,
#       "doc_id": "...",
#       "page_id": 4321,
#       "title": "Course backup",
#       "text": "To back up a Moodle course, navigate to...",
#       "source": "https://docs.moodle.org/Course_backup"
#     },
#     ...
#   ]
# }
```

--------------------------------

### MCP Resources: Page Data Access

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Provides access to parsed dump data through resources like `get_10_pages`, `get_100_pages`, and `get_pages/{start}/{number}`.

```APIDOC
## MCP Resources: Page Data Access

### Description
Serve slices of the most recent parsed JSON dump. Useful for inspecting content, building datasets, or populating other systems.

### Resources
- **`resource://get_10_pages`**: Returns the first 10 pages from the latest dump.
- **`resource://get_100_pages`**: Returns the first 100 pages from the latest dump.
- **`resource://get_pages/{start}/{number}`**: Returns a specified range of pages. For example, `resource://get_pages/1/5` returns pages 1 through 5.

### Page Data Structure
Each page object contains: `id`, `title`, `sections` (with `text`, `source`, `relationships`), `categories`, `templates`, `internal_links`, `external_links`, `language_links`.
```

--------------------------------

### FastAPI Authentication Dependency

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Example of using `validate_authentication` as a FastAPI dependency for global token validation. Configurable via environment variables for local tokens and remote service URLs.

```python
# The validation is applied globally as a FastAPI dependency:
# app = FastAPI(..., dependencies=[Depends(validate_authentication)])
#
# Token sources (configure in .env):
#   AUTH_TOKENS="token-abc,token-xyz,token-123"       # local list

```

--------------------------------

### Clone Repository and Set Up Environment

Source: https://github.com/moodlehq/wiki-rag/blob/main/README.md

Clone the Wiki-RAG repository and set up a Python virtual environment for local development.

```bash
git clone https://github.com/moodlehq/wiki-rag.git
cd wiki-rag
```

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows use `venv\Scripts\activate`
```

--------------------------------

### Initialize OpenAI Client and Generate Completion

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Demonstrates how to initialize the OpenAI client with a custom base URL and API key, and then use it to generate a chat completion.

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="my-secret-token",
)
response = client.chat.completions.create(
    model="moodle-docs",
    messages=[{"role": "user", "content": "What is competency-based education in Moodle?"}],
)
print(response.choices[0].message.content)
```

--------------------------------

### Instantiate Vector Store using `load_vector_store`

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Demonstrates how to dynamically import and instantiate a vector backend by name using `load_vector_store`. Currently, only 'milvus' is supported.

```python
import wiki_rag.vector as vector
from wiki_rag.config import load_config
from wiki_rag.vector import load_vector_store

cfg = load_config(command="index")
vector.store = load_vector_store("milvus")   # uses cfg.milvus.url and MILVUS_TOKEN
```

--------------------------------

### CLI: Full and Incremental Data Loading

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Command-line interface for loading Moodle wiki data. Use `wr-load` for a full load, `wr-load --incremental` for incremental loads, and `wr-load --incremental --force-save` to ensure saving even if no changes are detected.

```bash
# Full load — fetches all pages and saves a dated JSON dump
wr-load

# Incremental load — only re-fetches pages changed since the latest dump
wr-load --incremental

# Incremental load from a specific base dump
wr-load --incremental --base-json data/moodle-docs-2025-05-01-08-00.json

# Force save even when no changes are detected
wr-load --incremental --force-save

```

--------------------------------

### CLI for Indexing Moodle Documentation

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Command-line interface for initiating full or incremental indexing of Moodle documentation. Use `--full` to force a complete reindex, enabling a blue/green swap.

```bash
# Auto-detect latest dump and index (incremental if dump is incremental)
wr-index

# Force full reindex even if the dump is incremental (blue/green swap)
wr-index --full
```

--------------------------------

### Run Wiki-RAG Server Command

Source: https://github.com/moodlehq/wiki-rag/blob/main/README.md

Use `wr-server` to launch a web service that interacts with the RAG system using OpenAI API endpoints. Supports streaming and token-based authentication.

```bash
# wr-server: A comprehensive and secure web service (documented with OpenAPI) that allows users to interact with the RAG system using the OpenAI API (`v1/models` and `v1/chat/completions` endpoints) as if it were a large language model (LLM). Protected with bearer tokens (local list via `AUTH_TOKENS` and/or remote delegation via `AUTH_URL`). Supports streaming responses.
```

--------------------------------

### MCP Tool: `optimise` for POP + POC Optimized Context

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Shows how to use the `optimise` MCP tool, which runs retrieve and optimize graph stages to return deduplicated, reranked context strings and formatted source links.

```python
# Tool: optimise
# Input: [{"role": "user", "content": "What are Moodle activity completion conditions?"}]
# Output:
# {
#   "context": [
#     "Activity completion / Introduction\n\nActivity completion allows...",
#     "Activity completion / Completion conditions\n\nConditions include..."
#   ],
#   "sources": [
#     "[https://docs.moodle.org/Activity_completion|Activity completion: Introduction]",
#     "[https://docs.moodle.org/Activity_completion#Conditions|Activity completion: Completion conditions]"
#   ]
# }
```

--------------------------------

### wr-load CLI

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Command-line interface for performing full and incremental loading of MediaWiki data.

```APIDOC
## CLI: wr-load

### Description
Performs full and incremental loading of MediaWiki data.

### Usage

- **Full load**: Fetches all pages and saves a dated JSON dump.
  ```bash
  wr-load
  ```

- **Incremental load**: Re-fetches only pages changed since the latest dump.
  ```bash
  wr-load --incremental
  ```

- **Incremental load from a specific base dump**:
  ```bash
  wr-load --incremental --base-json data/moodle-docs-2025-05-01-08-00.json
  ```

- **Force save even when no changes are detected**:
  ```bash
  wr-load --incremental --force-save
  ```
```

--------------------------------

### Run Wiki-RAG Load Command

Source: https://github.com/moodlehq/wiki-rag/blob/main/README.md

Use `wr-load` to parse Mediawiki pages and store extracted content and metadata in a JSON file. Supports incremental updates.

```bash
# wr-load: Will parse all the configured pages in the source Mediawiki site, extracting contents and other important metadata. All the generated information will be stored into a JSON file in the `data` directory. Supports `--incremental` mode to only re-fetch changed pages since a previous dump.
```

--------------------------------

### Moodle RAG CLI Tool

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Command-line interface for querying the Moodle RAG system. Supports simple questions, streaming output, and multi-word queries by joining arguments.

```bash
# Simple question
wr-search "How do I create a quiz in Moodle?"

# Streaming output
wr-search --stream "What are the system requirements for Moodle 4.x?"

# Multi-word question (all args joined)
wr-search How do I enrol students in a course
```

--------------------------------

### MCP Prompts: Exporting RAG Prompt Templates

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Shows how to export system and user prompt templates using MCP prompts like `get_system_prompt` and `get_user_prompt`. These templates include placeholders for customization.

```python
# Prompt: get_system_prompt
# Parameters: task_def="Moodle documentation", kb_name="Moodle Docs", kb_url="https://docs.moodle.org"
# Returns the raw system prompt string with placeholders filled.

# Prompt: get_user_prompt
# Parameters: question="How do I...", context="...", sources="..."
# Returns the formatted user message string.
```

--------------------------------

### Run Wiki-RAG Search Command

Source: https://github.com/moodlehq/wiki-rag/blob/main/README.md

Use `wr-search` as a CLI utility to perform searches against the RAG system directly from the command line.

```bash
# wr-search: A tiny CLI utility to perform searches against the RAG system from the command line.
```

--------------------------------

### Run Wiki-RAG MCP Command

Source: https://github.com/moodlehq/wiki-rag/blob/main/README.md

Use `wr-mcp` to access Wiki-RAG components like prompts, resources, and tools via the MCP Protocol. Supports the same authentication as `wr-server`.

```bash
# wr-mcp: A complete built-in MCP server that allows you to access to various parts of Wiki-RAG like prompts (system and use prompt with placeholders), resources (access to the source parsed documents) and tools (retrieve, optimise and generate) using the [MCP Protocol](https://modelcontextprotocol.io/). Uses the same authentication schema as `wr-server`.
```

--------------------------------

### Vector Store Abstraction: `load_vector_store(name)`

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

The `load_vector_store` function dynamically imports and instantiates a vector backend by name, with `milvus` being the currently supported option.

```APIDOC
## Vector Store Abstraction — `BaseVector`

### `load_vector_store(name)` — Instantiate a vector backend by name

#### Description
Dynamically imports `wiki_rag.vector.{name}` and instantiates `{Name}Vector(cfg)`. Currently, `"milvus"` is the only shipped backend. Extending to new backends requires only implementing `BaseVector`.

#### Usage Example
```python
import wiki_rag.vector as vector
from wiki_rag.config import load_config
from wiki_rag.vector import load_vector_store

cfg = load_config(command="index")
vector.store = load_vector_store("milvus")   # uses cfg.milvus.url and MILVUS_TOKEN
```
```

--------------------------------

### Copy Configuration Template

Source: https://github.com/moodlehq/wiki-rag/blob/main/README.md

Copy the template file to create your own configuration file. Edit `config.yml` for non-secret settings and `.env` for secrets.

```bash
cp config.yml.template config.yml
```

```bash
cp dotenv.template .env
```

--------------------------------

### List Available Models via curl

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Fetches the list of available models from the OpenAI-compatible HTTP server. Requires a valid Authorization header.

```bash
curl -s http://localhost:8080/v1/models \
  -H "Authorization: Bearer my-secret-token" | python3 -m json.tool
```

--------------------------------

### CLI - `wr-search`

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Command-line interface for querying the RAG system. Supports simple questions, streaming output, and multi-word queries.

```APIDOC
## `wr-search` CLI

### Description
The `wr-search` command-line tool allows users to query the RAG system directly from their terminal.

### Usage

**Simple question:**
```bash
wr-search "How do I create a quiz in Moodle?"
```

**Streaming output:**
```bash
wr-search --stream "What are the system requirements for Moodle 4.x?"
```

**Multi-word question (all arguments joined):**
```bash
wr-search How do I enrol students in a course
```
```

--------------------------------

### MCP Tool: `generate` for Full RAG Answer Generation

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Demonstrates the `generate` MCP tool, which executes the complete RAG pipeline (query rewrite, HyDE, retrieve, optimise, generate) to produce an LLM-generated answer.

```python
# Tool: generate
# Input: [{"role": "user", "content": "How do I create a rubric in Moodle?"}]
# Output:
# {"result": "To create a rubric in Moodle:\n1. Go to Site administration...\n\nSee also: [Rubrics](https://...)"}
```

--------------------------------

### Python SDK - Streaming RAG

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Demonstrates how to use the RAG pipeline programmatically with streaming output, suitable for integration into applications like FastAPI.

```APIDOC
## Streaming RAG Usage

### Description
This example shows how to consume the RAG pipeline's output in a streaming fashion, handling both custom messages (like chitchat) and token-by-token LLM responses.

### Language
Python

### Usage
```python
import asyncio
from langchain_core.messages import AIMessageChunk

async def stream_rag(question: str):
    async for mode, info in graph.astream(
        input={"question": question, "history": []},
        context=context,
        stream_mode=["custom", "messages"],
    ):
        # Chitchat shortcut from query_rewrite node
        if mode == "custom" and isinstance(info, dict) and info.get("type") == "chitchat":
            print(info["content"], end="", flush=True)

        # Token-by-token output from generate node
        if mode == "messages":
            message, metadata = info[0], info[1]
            if (
                isinstance(message, AIMessageChunk)
                and metadata.get("langgraph_node") == "generate"
                and message.content
            ):
                print(message.content, end="", flush=True)

asyncio.run(stream_rag("What are Moodle activity completion settings?"))
```
```

--------------------------------

### Load and Validate Configuration

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Loads configuration from YAML, .env files, and defaults. Exits if required fields for a command are missing. Secrets are read exclusively from environment variables.

```python
from wiki_rag.config import load_config

cfg = load_config(command="search")

print(cfg.mediawiki.url)               # "https://docs.moodle.org"
print(cfg.openai_model)                # "gpt-4o-mini"
print(cfg.embedding_model)             # "text-embedding-3-small"
print(cfg.embedding_dimensions)        # 1536
print(cfg.search.hyde_enabled)         # False
print(cfg.milvus.url)                  # "http://localhost:19530"
print(cfg.auth_tokens)                 # ["tok1", "tok2"]
```

```yaml
# config.yml (non-secret settings):
# openai:
#   api_base: "https://api.openai.com/v1"
#   model: "gpt-4o-mini"
#   max_completion_tokens: 1536
#   temperature: 0.05
#   top_p: 0.85
# sites:
#   - url: "https://docs.moodle.org"
#     namespaces: [0, 4, 12]
#     excluded:
#       categories: ["Deprecated"]
#       wikitext: ["\\{\{stub\\}\"]
#     keep_templates: []
# collection:
#   name: "moodle-docs"
# index:
#   vendor: "milvus"
# embedding:
#   model: "text-embedding-3-small"
#   dimensions: 1536
# search:
#   product: "Moodle"
#   task_def: "Moodle user documentation"
#   kb_name: "Moodle Docs"
#   distance_cutoff: 0.4
#   contextualisation:
#     model: "gpt-4o-mini"
#   hyde:
#     enabled: false
#     passages: 1
# wrapper:
#   api_base: "0.0.0.0:8080"
#   chat_max_turns: 10
#   chat_max_tokens: 1536
# mcp:
#   api_base: "0.0.0.0:8081"
# milvus:
#   url: "http://localhost:19530"
```

```env
# .env (secrets only):
# OPENAI_API_KEY="sk-..."
# AUTH_TOKENS="token-abc,token-xyz"
# AUTH_URL="http://auth-service/key/info"   # optional remote token check
# MILVUS_TOKEN="user:password"              # optional
```

--------------------------------

### Run Wiki-RAG Index Command

Source: https://github.com/moodlehq/wiki-rag/blob/main/README.md

Use `wr-index` to create or incrementally update the vector index in Milvus with extracted information. Use `--full` to force a full reindex.

```bash
# wr-index: In charge of creating (or incrementally updating) the collection in the vector index (Milvus) with all the information extracted in the previous step. Automatically uses incremental mode for incremental dumps; use `--full` to force a full reindex.
```

--------------------------------

### Generate Configuration File

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Generates a `config.yml` file populated with settings from an existing `.env` file, useful for users upgrading from older configurations.

```bash
# Run once after upgrading from a .env-only setup
python scripts/generate-config.py
# Writes config.yml with all non-secret settings from .env
# Then edit .env to keep only the secrets listed in dotenv.template
```

--------------------------------

### Run Wiki-RAG Cleanup Script

Source: https://github.com/moodlehq/wiki-rag/blob/main/README.md

Execute the `wr-cleanup.sh` Bash script to prune old dump files. Use `--help` for full usage instructions.

```bash
# ./scripts/wr-cleanup.sh --help for full usage.
```

--------------------------------

### MCP Prompts: Export Prompt Templates

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Exposes system and user prompt templates via `get_system_prompt` and `get_user_prompt` for inspection or customization.

```APIDOC
## MCP Prompts: Export Prompt Templates

### Description
Expose the system and user prompt templates with placeholders so MCP clients can inspect or customise them.

### Prompts
- **`get_system_prompt`**
  - **Parameters**: `task_def` (string), `kb_name` (string), `kb_url` (string)
  - **Returns**: The raw system prompt string with placeholders filled.

- **`get_user_prompt`**
  - **Parameters**: `question` (string), `context` (string), `sources` (string)
  - **Returns**: The formatted user message string.
```

--------------------------------

### Create and Insert into Vector Collection

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Demonstrates creating a new vector collection and inserting data in batches. Ensure the embedding dimension matches your model.

```python
vector.store.create_collection("my-collection", embedding_dimension=1536)
vector.store.insert_batch("my-collection", [{"id": "...", "dense_vector": [...], ...}])
```

--------------------------------

### Blue/Green Collection Swap with Python

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Replaces the existing production collection with a newly indexed temporary collection, providing zero-downtime updates. This involves creating a temporary schema, indexing into it, and then swapping.

```python
from wiki_rag.index.util import (
    create_temp_collection_schema,
    replace_previous_collection,
    index_pages,
)

create_temp_collection_schema("moodle-docs_temp", embedding_dimension=1536)
index_pages(pages, "moodle-docs_temp", ...)
replace_previous_collection("moodle-docs", "moodle-docs_temp")
# "moodle-docs" now points to the freshly indexed data
```

--------------------------------

### Stream RAG Pipeline with LangGraph

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Demonstrates streaming output from the RAG pipeline, handling both chitchat shortcuts and token-by-token LLM responses. Requires LangGraph and asyncio.

```python
import asyncio
from langchain_core.messages import AIMessageChunk

async def stream_rag(question: str):
    async for mode, info in graph.astream(
        input={"question": question, "history": []},
        context=context,
        stream_mode=["custom", "messages"],
    ):
        # Chitchat shortcut from query_rewrite node
        if mode == "custom" and isinstance(info, dict) and info.get("type") == "chitchat":
            print(info["content"], end="", flush=True)

        # Token-by-token output from generate node
        if mode == "messages":
            message, metadata = info[0], info[1]
            if (
                isinstance(message, AIMessageChunk)
                and metadata.get("langgraph_node") == "generate"
                and message.content
            ):
                print(message.content, end="", flush=True)

asyncio.run(stream_rag("What are Moodle activity completion settings?"))
```

--------------------------------

### Run Wiki-RAG Docker Container

Source: https://github.com/moodlehq/wiki-rag/blob/main/README.md

Runs the Wiki-RAG container in detached mode. Requires mounting configuration files and setting environment variables like OPENAI_API_KEY and MILVUS_URL. The data directory will be created in the current directory.

```bash
docker run --rm --detach \
    --volume $(pwd)/data:/app/data \
    --volume $(pwd)/config.yml:/app/config.yml \
    --volume $(pwd)/.env:/app/.env \
    --env MILVUS_URL=http://milvus-standalone:19530 \
    --network milvus \
    --publish 8080:8080 \
    --env OPENAI_API_KEY=YOUR_OPENAI_API_KEY \
    --env LOG_LEVEL=info \
    --name wiki-rag \
    wiki-rag:latest
```

--------------------------------

### MCP Tool: optimise

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

The `optimise` MCP tool runs retrieve and optimise graph stages to return deduplicated, reranked context strings and formatted source links.

```APIDOC
## MCP Tool: `optimise(messages)`

### Description
Runs the retrieve and optimise graph stages. Returns deduplicated, reranked context strings and formatted source links, ready for injection into an LLM prompt.

### Tool Name
`optimise`

### Input
- **messages** (list of dict): A list of message objects, typically containing a user query.

### Output Example
```json
{
  "context": [
    "Activity completion / Introduction\n\nActivity completion allows...",
    "Activity completion / Completion conditions\n\nConditions include..."
  ],
  "sources": [
    "[https://docs.moodle.org/Activity_completion|Activity completion: Introduction]",
    "[https://docs.moodle.org/Activity_completion#Conditions|Activity completion: Completion conditions]"
  ]
}
```
```

--------------------------------

### Push Changes to Fork

Source: https://github.com/moodlehq/wiki-rag/blob/main/CONTRIBUTING.md

Push your committed changes to your forked repository on origin.

```bash
git push origin feature/your-feature-name
```

--------------------------------

### Build LangGraph Context Schema with Python

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Creates the immutable ContextSchema TypedDict for LangGraph, resolving model fallback chains for embedding, contextualisation, and HyDE. This serves as the single source of truth for graph node configuration.

```python
from wiki_rag.search.util import build_context_schema
from wiki_rag.config import load_config

cfg = load_config(command="search")
context = build_context_schema(cfg, stream=True)

print(context["llm_model"])
# "gpt-4o-mini"
print(context["contextualisation_model"])
# "gpt-4o-mini" (fallback)
print(context["hyde_enabled"])
# False
print(context["wrapper_model_name"])
# "moodle-docs" (from collection_name)
```

--------------------------------

### MCP Tool: generate

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

The `generate` MCP tool executes the full RAG pipeline, including query rewrite, HyDE, retrieve, optimise, and generation, to produce an LLM-generated answer.

```APIDOC
## MCP Tool: `generate(messages)`

### Description
Runs the complete RAG pipeline: query rewrite → HyDE → retrieve → optimise → generate. Returns the LLM-generated answer string.

### Tool Name
`generate`

### Input
- **messages** (list of dict): A list of message objects, typically containing a user query.

### Output Example
```json
{
  "result": "To create a rubric in Moodle:\n1. Go to Site administration...\n\nSee also: [Rubrics](https://...)"
}
```
```

--------------------------------

### Create a New Branch

Source: https://github.com/moodlehq/wiki-rag/blob/main/CONTRIBUTING.md

Create a new branch for your feature or bugfix to keep changes organized.

```bash
git checkout -b feature/your-feature-name
```

--------------------------------

### Enumerate MediaWiki Pages

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Retrieves a list of pages from a MediaWiki site using the API. Supports rate limiting to avoid server overload. Returns page IDs, titles, and namespaces.

```python
from wiki_rag.load.util import get_mediawiki_pages_list

pages = get_mediawiki_pages_list(
    mediawiki_url="https://docs.moodle.org",
    namespaces=[0, 4],          # Main + Project namespaces
    user_agent="MyBot/1.0",
    chunk=500,                   # Pages per API call
    enable_rate_limiting=True,
)
# Returns:
# [
#   {"pageid": 1234, "title": "Installing Moodle", "ns": 0},
#   {"pageid": 5678, "title": "Moodle:Community portal", "ns": 4},
#   ...
# ]
print(f"Found {len(pages)} pages")
```

--------------------------------

### RAG Chat Completions (Streaming SSE)

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Initiates a chat completion request with Server-Sent Events streaming enabled. Useful for real-time responses.

```bash
# Streaming (SSE)
curl -s -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer my-secret-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moodle-docs",
    "messages": [{"role": "user", "content": "Explain Moodle gradebook aggregation"}],
    "stream": true
  }'
```

--------------------------------

### Fetch and Parse MediaWiki Pages

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Use this function to retrieve wikitext, categories, templates, links, and section structure from MediaWiki pages. It applies exclusion rules and cleans the text. Ensure to set `enable_rate_limiting=True` in production.

```python
from wiki_rag.load.util import get_mediawiki_parsed_pages

exclusions = {
    "categories": ["Deprecated", "Stubs"],
    "wikitext": ["\\{\\{delete\\\\}""],  # regex patterns
}

parsed = get_mediawiki_parsed_pages(
    mediawiki_url="https://docs.moodle.org",
    pages=[{"pageid": 1234, "title": "Installing Moodle", "ns": 0}],
    user_agent="MyBot/1.0",
    exclusions=exclusions,
    keep_templates=["Note", "Warning"],  # keep these template blocks
    enable_rate_limiting=False,          # set True in production
)
# Each page dict:
# {
#   "id": 1234,
#   "title": "Installing Moodle",
#   "sections": [
#     {
#       "id": UUID("..."),
#       "anchor": "",
#       "title": "Installing Moodle",
#       "source": "https://docs.moodle.org/Installing_Moodle",
#       "text": "Moodle can be installed on...",
#       "level": 1,
#       "index": 0,
#       "page_id": 1234,
#       "doc_id": UUID("..."),
#       "doc_title": "Installing Moodle",
#       "doc_hash": UUID("..."),
#       "parent": None,
#       "children": [UUID("..."), UUID("...")],
#       "previous": [],
#       "next": [],
#       "relations": [],
#       "all_links": ["https://docs.moodle.org/System_requirements"],
#       "wiki_links": ["System requirements"],
#     },
#     ...
#   ],
#   "categories": ["Installation", "Administration"],
#   "templates": ["Note", "Warning"],
#   "internal_links": ["System requirements", "Upgrading"],
#   "external_links": ["https://php.net"],
#   "language_links": ["es:Instalación de Moodle"],
# }
```

--------------------------------

### Manage Vector Collections

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Provides functions to compact an existing collection and drop an old one. Compacting can improve performance.

```python
vector.store.compact_collection("my-collection")
vector.store.drop_collection("my-collection-old")
```

--------------------------------

### Pull Wiki-RAG Docker Image

Source: https://github.com/moodlehq/wiki-rag/blob/main/README.md

Pulls the latest Wiki-RAG Docker image from GitHub Container Registry. Specify a tag for a specific version.

```bash
docker pull ghcr.io/moodlehq/wiki-rag:latest  # or specify a tag
```

--------------------------------

### POST /v1/chat/completions

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Generates chat completions using the RAG pipeline. Supports standard OpenAI request formats, including streaming via Server-Sent Events.

```APIDOC
## POST /v1/chat/completions

### Description
This endpoint provides RAG-backed chat completions. It accepts a request body similar to the OpenAI API, processes messages by stripping system prompts and applying history limits, and then invokes the LangGraph pipeline. Streaming output is supported.

### Method
POST

### Endpoint
`/v1/chat/completions`

### Headers
- **Authorization** (string) - Required - Bearer token for authentication (`Bearer <token>`)
- **Content-Type** (string) - Required - `application/json`

### Request Body
- **model** (string) - Required - The identifier of the model to use (e.g., `moodle-docs`).
- **messages** (array) - Required - A list of message objects, each with `role` (`user` or `assistant`) and `content`.
- **temperature** (number) - Optional - Controls randomness. Lower values make output more deterministic.
- **max_completion_tokens** (integer) - Optional - The maximum number of tokens to generate in the completion.
- **stream** (boolean) - Optional - If true, enables Server-Sent Events streaming.

### Request Example (Non-streaming)
```bash
curl -s -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer my-secret-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moodle-docs",
    "messages": [
      {"role": "user", "content": "How do I reset a student password in Moodle?"}
    ],
    "temperature": 0.05,
    "max_completion_tokens": 512,
    "stream": false
  }' | python3 -m json.tool
```

### Response (Non-streaming)
#### Success Response (200)
- **id** (string) - Unique identifier for the completion.
- **object** (string) - Type of the object, e.g., `chat.completion`.
- **created** (integer) - Timestamp of creation.
- **model** (string) - The model used for the completion.
- **choices** (array) - A list of completion choices.
  - **index** (integer) - Index of the choice.
  - **message** (object) - The generated message.
    - **role** (string) - Role of the message sender (e.g., `assistant`).
    - **content** (string) - The text content of the message.

### Response Example (Non-streaming)
```json
{
  "id": "...",
  "object": "chat.completion",
  "created": 1748800000,
  "model": "moodle-docs",
  "choices": [{"index": 0, "message": {"role": "assistant", "content": "To reset..."}}]
}
```

### Request Example (Streaming SSE)
```bash
curl -s -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer my-secret-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moodle-docs",
    "messages": [{"role": "user", "content": "Explain Moodle gradebook aggregation"}],
    "stream": true
  }'
```

### Response Example (Streaming SSE)
```
data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"The "}}]}
data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"gradebook"}}]}
...
data: [DONE]
```

### Request Example (Multi-turn conversation)
```bash
curl -s -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer my-secret-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moodle-docs",
    "messages": [
      {"role": "user",      "content": "What is a Moodle course?"},
      {"role": "assistant", "content": "A Moodle course is a space..."},
      {"role": "user",      "content": "How do I enrol students in one?"}
    ]
  }'
```
```

--------------------------------

### Incremental Indexing of Pages with Python

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Performs an in-place incremental update of the live collection by deleting stale sections and re-embedding changed pages. The collection remains queryable during the process.

```python
from wiki_rag.index.util import index_pages_incremental

summary = index_pages_incremental(
    pages=incremental_pages,        # from incremental dump
    collection_name="moodle-docs",
    embedding_model="text-embedding-3-small",
    embedding_dimension=1536,
    embedding_api_base="https://api.openai.com/v1",
    embedding_api_key="sk-…",
)
# summary = {"deleted": 3, "updated": 12, "created": 5, "skipped": 4200, "sections_indexed": 89}
print(summary)
```

--------------------------------

### Index All Page Sections with Python

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Embeds and inserts all non-deleted page sections into a vector store collection. Requires pre-loaded page information and configuration.

```python
from wiki_rag.index.util import index_pages
import wiki_rag.vector as vector
from wiki_rag.vector import load_vector_store
from wiki_rag.config import load_config

cfg = load_config(command="index")
vector.store = load_vector_store(cfg.index_vendor)

pages = [...]  # from load_parsed_information()

total_pages, total_sections = index_pages(
    pages=pages,
    collection_name="moodle-docs",
    embedding_model="text-embedding-3-small",
    embedding_dimension=1536,
    embedding_api_base="https://api.openai.com/v1",
    embedding_api_key="sk-…",
)
print(f"Indexed {total_pages} pages, {total_sections} sections")
```

--------------------------------

### Save Parsed Pages to JSON Dump

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Persists parsed page data into a structured JSON file with a metadata header and site information. Ensure the `timestamp` is timezone-aware and microseconds are removed. The `output_file` path should follow the naming convention `{collection_name}-YYYY-MM-DD-HH-MM.json`.

```python
from datetime import UTC, datetime
from pathlib import Path
from wiki_rag.load.util import save_parsed_pages

save_parsed_pages(
    parsed_pages=parsed,                      # list of page dicts from get_mediawiki_parsed_pages
    output_file=Path("data/moodle-docs-2025-06-01-12-00.json"),
    timestamp=datetime.now(UTC).replace(microsecond=0),
    url="https://docs.moodle.org",
    dump_type="full",                         # "full" or "incremental"
    base_dump=None,                           # name of base dump for incremental
)
# Output JSON structure:
# {
#   "meta": {"timestamp": "2025-06-01T12:00:00+00:00", "num_sites": 1},
#   "sites": [{
#     "site_url": "https://docs.moodle.org",
#     "timestamp": "2025-06-01T12:00:00+00:00",
#     "dump_type": "full",
#     "base_dump": null,
#     "num_pages": 4200,
#     "pages": [...] 
#   }]
# }

```

--------------------------------

### RAG Chat Completions (Multi-turn)

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

Sends a multi-turn conversation history for chat completions. The server manages history limits.

```bash
# Multi-turn conversation
curl -s -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer my-secret-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moodle-docs",
    "messages": [
      {"role": "user",      "content": "What is a Moodle course?"},
      {"role": "assistant", "content": "A Moodle course is a space..."},
      {"role": "user",      "content": "How do I enrol students in one?"}
    ]
  }'
```

--------------------------------

### MCP Tool: retrieve

Source: https://context7.com/moodlehq/wiki-rag/llms.txt

The `retrieve` MCP tool performs a raw hybrid vector search, returning top retrieved sections without further processing.

```APIDOC
## MCP Tool: `retrieve(messages)`

### Description
Performs a raw hybrid vector search and returns the top retrieved sections from the vector store. This is useful for building custom post-processing pipelines.

### Tool Name
`retrieve`

### Input
- **messages** (list of dict): A list of message objects, typically containing a user query.

### Output Example
```json
{
  "vector_search": [
    {
      "distance": 0.87,
      "doc_id": "...",
      "page_id": 4321,
      "title": "Course backup",
      "text": "To back up a Moodle course, navigate to...",
      "source": "https://docs.moodle.org/Course_backup"
    },
    ...
  ]
}
```
```

--------------------------------

### Commit Changes with Conventional Commits

Source: https://github.com/moodlehq/wiki-rag/blob/main/CONTRIBUTING.md

Commit your changes using the conventional commits syntax for clear and consistent commit messages.

```bash
git commit -m "feat(scope): description of your feature/fix  # Conventional commits syntax."
```