### Quick Start Docker Compose Setup

Source: https://github.com/ggozad/haiku.rag/blob/main/examples/docker/README.md

Use this snippet to quickly set up and start the haiku.rag services. It creates necessary directories, copies a configuration file, and launches the services in detached mode.

```bash
mkdir -p data docs

cp haiku.rag.yaml.example haiku.rag.yaml

docker compose up -d
```

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

### Copy Example Configuration File

Source: https://github.com/ggozad/haiku.rag/blob/main/examples/docker/README.md

Copy the example configuration file to be used by the Docker containers. This file must exist before starting the services.

```bash
cp haiku.rag.yaml.example haiku.rag.yaml
```

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

### Install and Run haiku.rag

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/overview.md

Installs haiku.rag, pulls necessary Ollama models, initializes the project, adds a PDF source, and starts the chat interface.

```bash
uv pip install haiku.rag

ollama pull qwen3-embedding:4b
ollama pull gpt-oss

haiku-rag init
haiku-rag add-src ~/Documents/some-paper.pdf
haiku-rag chat
```

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

### Start Development Environment

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/apps.md

Navigate to the app directory and start the development environment using Docker Compose.

```bash
cd app
docker compose -f docker-compose.dev.yml up -d --build
```

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

### Install Jina Local Extra

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/configuration/providers.md

Install the jina extra for haiku.rag-slim for local inference.

```bash
uv pip install haiku.rag-slim[jina]
```

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

### Install MixedBread AI Extra

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/configuration/providers.md

Install the mxbai extra for haiku.rag-slim if you are not using the full package.

```bash
uv pip install haiku.rag-slim[mxbai]
```

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

### Apply Haiku.rag Database Migrations (Example Output)

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/cli.md

Example output showing the migrations applied during the 'haiku-rag migrate' command.

```bash
Applied 4 migration(s):
  - 0.20.0: Add 'docling_document_json' and 'docling_version' columns
  - 0.23.1: Add content_fts column for contextualized FTS search
  - 0.25.0: Compress docling_document with gzip
  - 0.38.0: Split docling_document pages into separate column and re-compress with zstd
Migration completed successfully.
```

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

### Install Haiku.rag Slim Package

Source: https://github.com/ggozad/haiku.rag/blob/main/README.md

Installs the minimal Haiku.rag package with fewer dependencies. Install only the extras you need.

```bash
pip install haiku.rag-slim
```

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

### Install and List Custom Skills

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/skills/custom.md

After generating a custom skill, install it using pip and then list available skills to confirm it has been registered.

```bash
uv pip install -e ./recipes-skill

haiku-skills list --use-entrypoints
```

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

### Set up Environment Variables

Source: https://github.com/ggozad/haiku.rag/blob/main/app/README.md

Copy the example environment file and edit it with your API keys and database path. This is a required step before running the application.

```bash
cp .env.example .env
# Edit .env with your API keys and database path
```

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

### Install Zero Entropy Extra

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/configuration/providers.md

Install the zeroentropy extra for haiku.rag-slim if you are not using the full package.

```bash
uv pip install haiku.rag-slim[zeroentropy]
```

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

### Install haiku.rag-slim with Common Combinations

Source: https://github.com/ggozad/haiku.rag/blob/main/haiku_rag_slim/README.md

Install haiku.rag-slim with specific combinations of extras, such as document processing, an Anthropic model provider, and the MixedBread AI reranker, or document processing, Groq provider, and Logfire.

```bash
# Common combinations
uv pip install haiku.rag-slim[docling,anthropic,mxbai]
uv pip install haiku.rag-slim[docling,groq,logfire]
```

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

### Install Slim haiku.rag Package (Minimal)

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/installation.md

Install the slim package of haiku.rag with minimal dependencies using uv pip.

```bash
# Minimal installation (no document processing)
uv pip install haiku.rag-slim
```

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

### Install Cohere Extra

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/configuration/providers.md

Install the cohere extra for haiku.rag-slim if you are not using the full package.

```bash
uv pip install haiku.rag-slim[cohere]
```

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

### Plugin Source Configuration Example

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/ingester.md

Example configuration for a custom plugin source, specifying the plugin type, ID, and options.

```yaml
- type: plugin
  id: api-docs
  plugin: git
  options:
    owner: acme
    repo: api
    branch: main
    token: ${SCM_TOKEN}
```

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

### Clone Repository and Install Dependencies

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/development.md

Clone the haiku.rag repository and install project dependencies using uv.

```bash
git clone https://github.com/ggozad/haiku.rag.git
cd haiku.rag
uv sync
```

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

### Environment Configuration Example

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/apps.md

Create a .env file in the app directory to configure API keys, database paths, and optional settings like Ollama base URL or Logfire token.

```bash
# API Keys (at least one required)
ANTHROPIC_API_KEY=your-anthropic-key
OPENAI_API_KEY=your-openai-key

# Database path
DB_PATH=/path/to/your/haiku.rag.lancedb

# Optional: Ollama base URL (if using local models)
OLLAMA_BASE_URL=http://localhost:11434

# Optional: Logfire for observability
LOGFIRE_TOKEN=your-logfire-token
```

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

### Registering a Custom Source Entry Point

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/ingester.md

Example of how to register a custom source factory using a project's `pyproject.toml` file.

```toml
# in the source package's pyproject.toml
[project.entry-points."haiku.rag.sources"]
git = "example_pkg:build_git_source"
```

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

### Install Ollama Models

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/tutorial.md

Download the necessary Ollama models for embedding and answering. Ensure Ollama is installed and running.

```bash
ollama pull qwen3-embedding:4b
ollama pull gpt-oss
```

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

### Global CLI Options Example

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/cli.md

Demonstrates how to use global options like --config, --read-only, --before, and --version with Haiku.rag commands.

```bash
haiku-rag --config /path/to/config.yaml list
haiku-rag --config /path/to/config.yaml list --db /path/to/custom.db
haiku-rag --read-only search "query"
haiku-rag --before "2025-01-15" search "query"
haiku-rag add -h
```

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

### Run docling-serve Manually with Docker

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/remote-processing.md

This command starts the docling-serve Docker container, exposing port 5001 for remote processing. It's a quick way to get the service running for testing or development.

```bash
docker run -p 5001:5001 quay.io/docling-project/docling-serve
```

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

### Install Ingester Package

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/ingester.md

Install the ingester service using pip. Choose the 'slim' version for core functionality or the full package for all features.

```bash
pip install 'haiku.rag-slim[ingester]'
# or, for the full package:
pip install 'haiku.rag[ingester]'
```

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

### Install Slim haiku.rag Package with Specific Providers

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/installation.md

Install the slim package with specific providers like document processing and embedding/reranking services using uv pip.

```bash
# With specific providers
uv pip install haiku.rag-slim[docling,voyageai,mxbai]
```

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

### Install Haiku.rag with VoyageAI Extras

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/configuration/providers.md

If using the haiku.rag-slim package, install VoyageAI support using pip.

```bash
uv pip install haiku.rag-slim[voyageai]
```

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

### Install Cross-Encoder Extra

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/configuration/providers.md

Install the cross-encoder extra for haiku.rag-slim to use sentence-transformers.

```bash
uv pip install haiku.rag-slim[cross-encoder]
```

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

### Start Development Server

Source: https://github.com/ggozad/haiku.rag/blob/main/app/README.md

Launch the development environment with hot reloading using a specific Docker Compose file. This is useful for local development and testing.

```bash
docker compose -f docker-compose.dev.yml up -d --build
```

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

### Basic Custom Pipeline Example

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/custom-pipelines.md

This example demonstrates a basic custom pipeline by composing the convert, chunk, and embed_chunks primitives, followed by importing the document. It shows how to handle document processing steps individually.

```python
from haiku.rag.client import HaikuRAG
from haiku.rag.embeddings import embed_chunks

async with HaikuRAG("database.lancedb", create=True) as client:
    # 1. Convert source to DoclingDocument
    docling_doc = await client.convert("path/to/document.pdf")

    # 2. Chunk the document
    chunks = await client.chunk(docling_doc)

    # 3. Generate embeddings
    embedded_chunks = embed_chunks(chunks, client.embedder)

    # 4. Store the document with chunks
    doc = await client.import_document(
        docling_document=docling_doc,
        chunks=embedded_chunks,
        uri="file:///path/to/document.pdf",
        title="My Document",
    )
```

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

### Start the Application

Source: https://github.com/ggozad/haiku.rag/blob/main/app/README.md

Use Docker Compose to start the haiku.rag application in detached mode. This command brings up all necessary services.

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

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

### Install Slim haiku.rag Package with Document Processing

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/installation.md

Install the slim package with document processing enabled using uv pip.

```bash
# With document processing
uv pip install haiku.rag-slim[docling]
```

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

### Set API Keys and Start Docker Compose

Source: https://github.com/ggozad/haiku.rag/blob/main/examples/docker/README.md

Export necessary API keys as environment variables and start the Docker Compose services in detached mode.

```bash
export OPENAI_API_KEY=your-key-here
export ANTHROPIC_API_KEY=your-key-here
docker compose up -d
```

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

### Install and Use Generated Skill

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/cli.md

Installs the generated skill package using uv pip and then enables its use with `haiku-skills` by specifying entry points.

```bash
uv pip install -e ./medic-skill

haiku-skills chat --use-entrypoints --skill medic
```

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

### Haiku.rag Configuration File Example

Source: https://github.com/ggozad/haiku.rag/blob/main/docker/README.md

Example configuration file for haiku.rag. Specifies production environment, embedding model (Ollama nomic-embed-text), and QA model (Ollama qwen3).

```yaml
# haiku.rag.yaml
environment: production

embeddings:
  model:
    provider: ollama
    name: nomic-embed-text
    vector_dim: 768

qa:
  model:
    provider: ollama
    name: qwen3
```

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

### Install Full haiku.rag Package

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/installation.md

Install the full package of haiku.rag using uv pip. This includes all features and extras.

```bash
uv pip install haiku.rag
```

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

### Configure LLM and Embedding Models

Source: https://github.com/ggozad/haiku.rag/blob/main/app/README.md

Copy the example configuration file and edit it to specify your preferred LLM and embedding models. This file controls the AI's behavior.

```bash
cp haiku.rag.yaml.example haiku.rag.yaml
# Edit haiku.rag.yaml to configure your models
```

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

### Haiku.rag Configuration Example

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/apps.md

Mount a haiku.rag.yaml file in the app directory for full configuration, specifying the QA model provider and name.

```yaml
# app/haiku.rag.yaml
qa:
  model:
    provider: anthropic
    name: claude-sonnet-4-20250514
```

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

### Example Domain Preamble for Acme Corp

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/configuration/prompts.md

Provides an example of a `domain_preamble` for Acme Corp's cloud platform documentation, clarifying terminology.

```yaml
prompts:
  domain_preamble: |
    This knowledge base contains product documentation, API references,
    and troubleshooting guides for Acme Corp's cloud platform.
    "Deployment" refers to Acme's managed deployment service, not general CI/CD.
```

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

### Complete Haiku Rag Configuration Example

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/configuration/index.md

A comprehensive configuration example for Haiku Rag, detailing settings for storage, ingester sources, Lancedb, embeddings, reranking, QA, search, document processing, and external providers.

```yaml
# haiku.rag.yaml
environment: production

storage:
  data_dir: ""  # Empty = use default platform location
  vacuum_retention_seconds: 86400

ingester:
  sources:
    - type: fs
      id: local-docs
      root: /path/to/documents
      ignore_patterns: []  # Gitignore-style patterns to exclude
      include_patterns: []  # Gitignore-style patterns to include
      delete_orphans: true

lancedb:
  uri: ""  # Empty for local, or db://, s3://, az://, gs://
  api_key: ""
  region: ""

embeddings:
  model:
    provider: ollama
    name: qwen3-embedding:4b
    vector_dim: 2560

reranking:
  model:
    provider: ""  # Empty to disable, or mxbai, cohere, zeroentropy, vllm
    name: ""

qa:
  model:
    provider: ollama
    name: gpt-oss
    enable_thinking: true
    temperature: 0.3
  max_searches: 3

search:
  limit: 10                    # Default number of results to return
  max_context_chars: 10000     # Maximum characters in expanded context
  vector_index_metric: cosine  # cosine, l2, or dot
  vector_refine_factor: 30

doctor:
  duplicates:                    # Near-duplicate document detection (doctor command)
    similarity_threshold: 0.97   # cosine cutoff on document embedding centroids
    min_chunks: 3                # documents with fewer chunks are excluded

prompts:
  domain_preamble: ""  # Prepended to skill instructions

processing:
  converter: docling-local  # docling-local or docling-serve
  chunker: docling-local    # docling-local or docling-serve
  chunker_type: hybrid      # hybrid or hierarchical
  chunk_size: 256
  chunking_tokenizer: "Qwen/Qwen3-Embedding-0.6B"
  chunking_merge_peers: true
  chunking_use_markdown_tables: false
  auto_title: false              # Auto-generate titles on ingestion
  title_model:
    provider: ollama
    name: gpt-oss
    enable_thinking: false
    temperature: 0.3
    max_tokens: 100
  conversion_options:
    do_ocr: true
    force_ocr: false
    ocr_lang: []
    do_table_structure: true
    table_mode: accurate
    table_cell_matching: true
    images_scale: 2.0

providers:
  ollama:
    base_url: http://localhost:11434

  docling_serve:
    base_url: http://localhost:5001
    api_key: ""
    timeout: 300
```

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

### Run MCP Server Binding to All Interfaces

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/cli.md

Starts the MCP server and binds it to all available network interfaces (0.0.0.0), useful for containerized or trusted LAN environments.

```bash
haiku-rag mcp --host 0.0.0.0
```

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

### Serve Ingester Continuously

Source: https://github.com/ggozad/haiku.rag/blob/main/README.md

Starts the Haiku.rag ingester service to continuously ingest data from configured sources.

```bash
haiku-ingester serve
```

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

### Expose Skill via MCP Server

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/skills/index.md

This command-line instruction starts the Haiku-rag MCP server, which exposes skill tools (search, ask, analyze) over the Message Communication Protocol. This allows MCP-aware clients to interact with the skills.

```bash
haiku-rag mcp --stdio
```

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

### Start MCP Server Binding to All Interfaces

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/mcp.md

Starts the MCP server using the streamable HTTP transport and binds it to all available network interfaces (0.0.0.0). This is useful for running the server inside containers or when it needs to be accessible from other machines on the network.

```bash
haiku-rag mcp --host 0.0.0.0 --port 8001
```

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

### Create Document Test

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/development.md

Example of creating a document using HaikuRAG client within an async test marked for VCR recording. Requires a temporary database path fixture.

```python
import pytest
from haiku.rag.client import HaikuRAG


@pytest.mark.asyncio
@pytest.mark.vcr()
async def test_my_feature(temp_db_path):
    async with HaikuRAG(temp_db_path, create=True) as client:
        doc = await client.create_document("Test content", uri="test://doc")
        assert doc.id is not None
```

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

### Run Haiku Ingester Service

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/ingester.md

Examples of running the Haiku Ingester service with different command-line flags to control its behavior, such as disabling the API, specifying a database path, or binding the API to a specific host and port.

```bash
haiku-ingester serve
```

```bash
haiku-ingester serve --no-api
```

```bash
haiku-ingester serve --db /path.lancedb
```

```bash
haiku-ingester serve --host 0.0.0.0
```

```bash
haiku-ingester serve --port 9000
```

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

### Combine RAG and Analysis Skills

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/skills/index.md

This example shows how to create and combine both the RAG and RAG-analysis skills within a single SkillToolset for an agent. Both skills will use the same database path.

```python
from haiku.rag.skills.rag import create_skill as create_rag_skill
from haiku.rag.skills.analysis import create_skill as create_analysis_skill

rag = create_rag_skill(db_path="my.lancedb")
analysis = create_analysis_skill(db_path="my.lancedb")
toolset = SkillToolset(skills=[rag, analysis])
```

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

### Create Document Toolset

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/tools.md

Instantiates the `create_document_toolset` for document browsing and retrieval. This toolset allows listing, getting, and summarizing documents. A `base_filter` can be applied to list operations.

```python
from haiku.rag.tools import create_document_toolset

docs = create_document_toolset(config)
```

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

### Download Pre-built Evaluation Databases

Source: https://github.com/ggozad/haiku.rag/blob/main/evaluations/README.md

Download pre-built evaluation databases from HuggingFace. Use 'wix', 'all', or specify other dataset names. The --force option can be used to overwrite existing databases.

```bash
evaluations download wix
evaluations download all
evaluations download wix --force
```

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

### Download Pre-built Evaluation Datasets

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/benchmarks.md

Download pre-built evaluation datasets to speed up the benchmarking process. Use '--force' to overwrite existing files.

```bash
# Download a specific dataset
evaluations download wix

# Download all datasets
evaluations download all

# Force re-download (overwrite existing)
evaluations download wix --force
```

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

### Initialize and Migrate Ingester Queue

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/ingester.md

Create the ingester's SQLite queue database and apply any pending schema changes.

```bash
haiku-ingester queue init
haiku-ingester queue migrate
```

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

### Initialize Local Haiku.rag Database (CLI)

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/configuration/storage.md

Use the `haiku-rag init` command to create a new local database. Specify a custom path with the `--db` flag or use the default location.

```bash
# Create in default location (see Configuration File Locations below)
haiku-rag init

# Create at custom path
haiku-rag init --db /path/to/database.lancedb
```

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

### HaikuRAG Client Initialization and Document Indexing

Source: https://github.com/ggozad/haiku.rag/blob/main/README.md

Demonstrates how to initialize the HaikuRAG client and index documents from local files and URLs.

```APIDOC
## HaikuRAG Client Initialization and Document Indexing

### Description
Initializes the HaikuRAG client and indexes documents from various sources.

### Method
Asynchronous context manager for HaikuRAG client.

### Endpoint
N/A (Python API)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from haiku.rag.client import HaikuRAG

async with HaikuRAG("knowledge.lancedb", create=True) as rag:
    await rag.create_document_from_source("paper.pdf")
    await rag.create_document_from_source("https://arxiv.org/pdf/1706.03762")
```

### Response
#### Success Response (200)
Client is ready for operations.

#### Response Example
None
```

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

### Integration Test Example

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/development.md

Example of an integration test that requires local services and is marked with `@pytest.mark.integration`. This test will be skipped in CI.

```python
@pytest.mark.integration
@pytest.mark.asyncio
async def test_pdf_visualization(temp_db_path):
    # Test code that needs local PDF processing
    pass
```

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

### Build and Run Local Docker Images

Source: https://github.com/ggozad/haiku.rag/blob/main/examples/docker/README.md

Commands to build the local `haiku.rag-slim` image, run services using it, and switch back to the published image.

```bash
docker compose build
docker compose up -d
docker compose pull
```

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

### Custom Picture Description Prompt Example

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/configuration/prompts.md

An example of a custom `picture_description` prompt tailored for search indexing, focusing on factual content.

```yaml
prompts:
  picture_description: |
    Describe this image for a document search system.
    Focus on: image type, main content, any text, key visual elements.
    Be concise and factual.
```

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

### Initialize Local Haiku.rag Database (Python)

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/configuration/storage.md

Create a new local database using the `HaikuRAG` client in Python. Set `create=True` and provide a custom path or use the default.

```python
# Create at custom path
async with HaikuRAG("/path/to/database.lancedb", create=True) as client:
    ...

# Create in default location
async with HaikuRAG(create=True) as client:
    ...
```

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

### Environment Variable Substitution in Configuration

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/configuration/index.md

Demonstrates how to reference environment variables within the configuration file for dynamic values like database credentials. Supports direct substitution, default values, and literal dollar signs.

```yaml
ingester:
  queue:
    dburi: postgresql+asyncpg://haiku:${POSTGRES_PASSWORD}@db:5432/haiku_rag
```

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

### Start MCP Server with Custom HTTP Port

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/mcp.md

Starts the MCP server using the streamable HTTP transport on a specified custom port. Use this when the default port 8001 is unavailable or needs to be changed.

```bash
haiku-rag mcp --port 9000
```

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

### Programmatic Prompt Configuration

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/configuration/prompts.md

Configures `domain_preamble` and `picture_description` programmatically using `AppConfig` and `PromptsConfig`.

```python
from haiku.rag.config import AppConfig
from haiku.rag.config.models import PromptsConfig

config = AppConfig(
    prompts=PromptsConfig(
        domain_preamble="This knowledge base contains Acme Corp product documentation and API references.",
        picture_description="Describe this image for search indexing.",
    )
)
```

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

### Start MCP Server in Read-only Mode with stdio Transport

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/mcp.md

Starts the MCP server in read-only mode using the stdio transport. This configuration disables write operations, making only search and query tools available.

```bash
haiku-rag --read-only mcp --stdio
```

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

### Start MCP Server with Default HTTP Transport

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/mcp.md

Starts the MCP server using the default streamable HTTP transport, binding to localhost on port 8001. This is the standard way to run the server for most use cases.

```bash
haiku-rag mcp
```

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

### Configure Document Processing with Docling-Serve

Source: https://github.com/ggozad/haiku.rag/blob/main/examples/docker/README.md

Set up Haiku.rag to use the 'haiku.rag-slim' Docker image with docling-serve for document processing and chunking.

```yaml
processing:
  converter: docling-serve
  chunker: docling-serve

providers:
  docling_serve:
    base_url: http://docling-serve:5001
```

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

### Get Configuration

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/ingester.md

Retrieves the full effective configuration of the ingester, with secrets redacted.

```APIDOC
## GET /config

### Description
Returns the complete effective configuration of the ingester service, including default values filled in. Sensitive information such as authentication tokens will be redacted.

### Method
GET

### Endpoint
/config

### Parameters
None

### Response
#### Success Response (200)
- The ingester's configuration in YAML format.

#### Response Example
```yaml
ingester:
  api:
    enabled: true
    host: 127.0.0.1
    port: 8765
    auth_token: "********"
    root_path: ""
  # ... other configuration ...
```
```

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

### Get Job by ID

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/ingester.md

Retrieves details for a specific job using its unique identifier.

```APIDOC
## GET /jobs/{id}

### Description
Retrieves the detailed information for a single job identified by its unique ID.

### Method
GET

### Endpoint
/jobs/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the job.

### Response
#### Success Response (200)
- A job object containing all details for the specified job.

#### Response Example
```json
{
  "id": "job-abc",
  "status": "queued",
  "source_id": "source-123",
  "uri": "http://example.com/doc1",
  "created_at": "2023-10-27T09:00:00Z",
  "attempts": 0
}
```
```

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

### Get Document by ID

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/cli.md

Retrieves a specific document from the database using its unique identifier.

```bash
haiku-rag get 3f4a...   # document ID
```

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

### Chat with a Custom Skill

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/skills/custom.md

Initiate a chat session specifically with the custom skill you have generated and installed.

```bash
haiku-skills chat --use-entrypoints --skill recipes
```

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

### Run Benchmarks with Custom Configuration

Source: https://github.com/ggozad/haiku.rag/blob/main/evaluations/README.md

Run benchmarks using a custom configuration file. Specify the path to your YAML configuration file using the --config option.

```bash
evaluations run wix --config /path/to/haiku.rag.yaml
```

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

### Start Interactive Chat

Source: https://github.com/ggozad/haiku.rag/blob/main/README.md

Initiates an interactive, multi-turn chat session with memory using the Haiku.rag CLI.

```bash
haiku-rag chat
```

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

### Haiku CLI: ask

Source: https://github.com/ggozad/haiku.rag/blob/main/README.md

Command to ask a question against the Haiku.rag knowledge base and get an answer with citations.

```APIDOC
## Haiku CLI: ask

### Description
Asks a question against the Haiku.rag knowledge base and returns an answer with citations.

### Method
CLI Command

### Endpoint
N/A (CLI Command)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
haiku-rag ask "What datasets were used for evaluation?"
```

### Response
#### Success Response (200)
Answer and citations are displayed.

#### Response Example
None
```

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

### Run One-Shot Batch Build

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/ingester.md

Execute a single discovery sweep and ingest changes. Use `--db` to specify a different database file.

```bash
haiku-ingester run-batch
haiku-ingester run-batch --db rag.lancedb
```

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

### Run MCP Server in Read-Only Mode

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/cli.md

Starts the MCP server in read-only mode, disabling write tool access.

```bash
haiku-rag --read-only mcp
```

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

### Get Statistics

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/ingester.md

Retrieves various statistics about the ingester's performance, including throughput, worker occupancy, and queue age.

```APIDOC
## GET /stats

### Description
Provides performance metrics for the ingester, including rolling throughput over different time windows (5m, 30m, 1h), worker utilization, the age of the oldest queued job, and per-source DLQ and backlog counts.

### Method
GET

### Endpoint
/stats

### Parameters
None

### Response
#### Success Response (200)
- An object containing various statistical metrics.

#### Response Example
```json
{
  "throughput_5m_succeeded": 120,
  "throughput_30m_succeeded": 110,
  "throughput_1h_succeeded": 105,
  "worker_occupancy": 0.75,
  "oldest_queued_age_seconds": 300,
  "per_source_dlq_counts": {
    "source-123": 5,
    "source-456": 2
  },
  "per_source_backlog_counts": {
    "source-123": 50,
    "source-456": 10
  }
}
```
```

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

### Configure Benchmark Run

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/benchmarks.md

Specify custom configuration and database paths for running benchmarks. This allows for fine-grained control over the evaluation environment.

```bash
evaluations run wix --config /path/to/haiku.rag.yaml --db /path/to/custom.lancedb
```

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

### Get Database Info

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/ingester.md

Retrieves information about the LanceDB snapshot, including stored version, embeddings, row counts, and index status.

```APIDOC
## GET /database

### Description
Fetches details about the current LanceDB snapshot. This includes the stored version, information about embeddings, row counts and sizes per table, vector index status, pending database migrations, and package versions.

### Method
GET

### Endpoint
/database

### Parameters
None

### Response
#### Success Response (200)
- An object containing detailed information about the LanceDB instance.

#### Response Example
```json
{
  "stored_version": "1.2.3",
  "embeddings_info": {
    "model": "text-embedding-ada-002",
    "dimension": 1536
  },
  "tables": {
    "documents": {
      "row_count": 10000,
      "size_bytes": 52428800
    }
  },
  "vector_index_status": "healthy",
  "pending_migrations": 0,
  "package_versions": {
    "haiku-rag": "0.1.0",
    "lancedb": "0.5.0"
  }
}
```
```

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

### Run docling-serve with Web UI Enabled

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/remote-processing.md

Enables the web UI for debugging by setting the DOCLING_SERVE_ENABLE_UI environment variable. This is useful for inspecting the service's status and operations.

```bash
docker run -p 5001:5001 -e DOCLING_SERVE_ENABLE_UI=true quay.io/docling-project/docling-serve
```

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

### Configure Filesystem Source

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/ingester.md

Configure the ingester to monitor a local filesystem directory for changes. Supports pattern matching and orphan deletion.

```yaml
ingester:
  sources:
    - type: fs
      id: local-docs
      root: /Users/you/docs
      delete_orphans: true
```

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

### Nginx Reverse Proxy Configuration

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/ingester.md

Example Nginx configuration to serve the ingester control plane under a sub-path, handling redirects and proxying requests.

```nginx
# Redirect the bare prefix to the trailing-slash form so the dashboard's
# <base href> resolves correctly.
location = /ingester {
    return 308 /ingester/;
}

location /ingester/ {
    rewrite ^/ingester/?(.*)$ /$1 break;
    proxy_pass http://127.0.0.1:8765;
}
```

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

### Initialize Queue Schema on Database Server

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/ingester.md

Initialize the schema for the ingester queue when using an external database server.

```bash
haiku-ingester queue init
```

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

### Python Metadata Provider Implementation

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/ingester.md

Example implementation of a custom metadata provider in Python. This provider extracts collection, folder, and byte size from the fetched result.

```python
# example_pkg/__init__.py
from urllib.parse import urlparse

from haiku.rag.ingester.sources import FetchResult


class Provider:
    async def __call__(
        self, source_id: str, uri: str, result: FetchResult
    ) -> dict:
        path = urlparse(uri).path
        return {
            "collection": source_id,
            "folder": path.rsplit("/", 1)[0] or "/",
            "bytes": str(len(result.body)),
        }
```

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

### Initialize Haiku.rag Database

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/cli.md

Creates a new Haiku.rag database. This command must be run before any other commands that interact with the database.

```bash
haiku-rag init [--db /path/to/your.lancedb]
```

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

### Configure OpenAI-Compatible Server (LM Studio)

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/configuration/providers.md

Use the 'openai' provider with a custom base URL for LM Studio inference servers. Ensure the server supports tool calling and the base URL includes '/v1'.

```yaml
# LM Studio example
qa:
  model:
    provider: openai
    name: gpt-oss-20b
    base_url: http://localhost:1234/v1
    enable_thinking: false
```

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

### Python API: Index and Search Documents

Source: https://github.com/ggozad/haiku.rag/blob/main/README.md

Demonstrates using the HaikuRAG Python client to create a database, index documents from a local file and a URL, and perform a search.

```python
from haiku.rag.client import HaikuRAG

async with HaikuRAG("knowledge.lancedb", create=True) as rag:
    # Index documents
    await rag.create_document_from_source("paper.pdf")
    await rag.create_document_from_source("https://arxiv.org/pdf/1706.03762")

    # Search — returns chunks with provenance
    results = await rag.search("self-attention")
    for result in results:
        print(f"{result.score:.2f} | p.{result.page_numbers} | {result.content[:100]}")
```

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

### Create a Standalone Skill Package

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/cli.md

Generates a pip-installable Python package for a skill, embedding a specified LanceDB database.

```bash
haiku-rag create-skill --name myskill --db /path/to/database.lancedb
```

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

### Configure Multiple docling-serve Instances

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/configuration/processing.md

Use a list of base URLs for round-robin job distribution across multiple docling-serve instances. This is useful for load balancing.

```yaml
providers:
  docling_serve:
    base_url:
      - http://gpu-1:5001
      - http://cpu-1:5001
      - http://cpu-2:5001
```

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

### Run Evaluation with Pre-built Database

Source: https://github.com/ggozad/haiku.rag/blob/main/docs/benchmarks.md

Run a benchmark evaluation while skipping the database update by using the '--skip-db' flag. This is useful when using pre-built databases.

```bash
evaluations run wix --skip-db
```