haiku.rag

https://ggozad.github.io/haiku.rag/
Admin
haiku.rag is an opinionated, agentic retrieval-augmented generation (RAG) system powered by LanceDB,...
Tokens:39,724
Snippets:529
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Skill Generation and Installation Example

Source: https://ggozad.github.io/haiku.rag/cli

Example workflow for generating a custom skill, installing it, and using it with haiku-skills.

```bash
# Generate a skill with specific tools and custom preamble
haiku-rag create-skill \
  --name medic \
  --db /path/to/medic.lancedb \
  --tools search,cite \
  --config-file /path/to/haiku.rag.yaml \
  --description "Military medic knowledge base" \
  --preamble "You are a military medic expert."

# Install the generated package
uv pip install -e ./medic-skill

# Use with haiku-skills
haiku-skills chat --use-entrypoints --skill medic
```

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

### Install and run a custom skill

Source: https://ggozad.github.io/haiku.rag/skills/custom

Install the generated package in editable mode and verify its availability before starting a chat session.

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

haiku-skills list --use-entrypoints
# recipes — Recipe and cooking knowledge base

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

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

### Start the development environment

Source: https://ggozad.github.io/haiku.rag/apps

Use Docker Compose to build and start the application services in the background.

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

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

### Install and Configure Cohere Reranking

Source: https://ggozad.github.io/haiku.rag/configuration/providers

Install the required extra and configure the provider settings with the API key.

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

```yaml
reranking:
  model:
    provider: cohere
    name: rerank-v3.5
```

```bash
export CO_API_KEY=your-api-key
```

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

### Initialize and run haiku.rag

Source: https://ggozad.github.io/haiku.rag/overview

Commands to install the package, pull required models, initialize the environment, add a document, and start 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
```

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

### Install a custom skill locally

Source: https://ggozad.github.io/haiku.rag/skills/custom

Use the uv package manager to install the skill in editable mode.

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

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

### Install and Configure Zero Entropy Reranking

Source: https://ggozad.github.io/haiku.rag/configuration/providers

Install the required extra and configure the provider settings with the API key.

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

```yaml
reranking:
  model:
    provider: zeroentropy
    name: zerank-1  # Currently the only available model
```

```bash
export ZEROENTROPY_API_KEY=your-api-key
```

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

### Setup Development Environment

Source: https://ggozad.github.io/haiku.rag/development

Commands to clone the repository and synchronize dependencies using uv.

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

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

### Install Full Package

Source: https://ggozad.github.io/haiku.rag/installation

Installs the full haiku.rag package including all features and dependencies.

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

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

### Install and Configure Jina AI Reranking (Local Mode)

Source: https://ggozad.github.io/haiku.rag/configuration/providers

Install the local jina extra and configure the provider for local inference.

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

```yaml
reranking:
  model:
    provider: jina-local
    name: jinaai/jina-reranker-v3
```

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

### Install Slim Package

Source: https://ggozad.github.io/haiku.rag/installation

Installs the slim version of the package with optional extras for specific functionality.

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

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

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

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

### Install Ingester Package

Source: https://ggozad.github.io/haiku.rag/ingester

Install the ingester component using pip with either the slim or full package options.

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

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

### Configure WebDAV Source

Source: https://ggozad.github.io/haiku.rag/ingester

Example configuration for a WebDAV source using basic authentication.

```yaml
ingester:
  sources:
    - type: webdav
      id: nextcloud
      base_url: https://nextcloud.example.com/remote.php/dav/files/alice/Documents/
      username: alice
      password: ${NEXTCLOUD_APP_PASSWORD}
      ignore_patterns: ["**/Trash/**"]
      poll_interval_s: 600
```

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

### Complete configuration example

Source: https://ggozad.github.io/haiku.rag/configuration

A full reference for all configurable parameters including storage, ingestion, vector database, reranking, search, and processing options.

```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 cross-encoder, 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: 5000     # 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
```

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

### Install Inspector Dependencies

Source: https://ggozad.github.io/haiku.rag/tuning

Command to install the required TUI extra for the inspector functionality.

```bash
pip install haiku.rag-slim[tui]
```

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

### Launch interactive chat session

Source: https://ggozad.github.io/haiku.rag/cli

Start a multi-turn chat session with optional database path and enabled skills. Requires the tui extra installed via pip.

```bash
haiku-rag chat
haiku-rag chat --db /path/to/database.lancedb

# Enable analysis skill (code execution)
haiku-rag chat -s rag -s analysis
```

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

### Configure VoyageAI Embedding Provider

Source: https://ggozad.github.io/haiku.rag/configuration/providers

Installation and configuration for VoyageAI, including API key setup.

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

```yaml
embeddings:
  model:
    provider: voyageai
    name: voyage-3.5
    vector_dim: 1024
```

```bash
export VOYAGE_API_KEY=your-api-key
```

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

### Configure OpenAI-Compatible Servers

Source: https://ggozad.github.io/haiku.rag/configuration/providers

Examples for connecting to vLLM or LM Studio using the OpenAI provider interface.

```yaml
# vLLM example
embeddings:
  model:
    provider: openai
    name: mixedbread-ai/mxbai-embed-large-v1
    vector_dim: 512
    base_url: http://localhost:8000/v1

# LM Studio example
embeddings:
  model:
    provider: openai
    name: text-embedding-qwen3-embedding-4b
    vector_dim: 2560
    base_url: http://localhost:1234/v1
```

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

### Run docling-serve via Docker

Source: https://ggozad.github.io/haiku.rag/remote-processing

Commands to start the docling-serve container with or without the debugging web UI enabled.

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

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

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

### Install and Configure Cross-Encoder Reranking

Source: https://ggozad.github.io/haiku.rag/configuration/providers

Install the cross-encoder extra and configure a HuggingFace model for in-process reranking.

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

```yaml
reranking:
  model:
    provider: cross-encoder
    name: mixedbread-ai/mxbai-rerank-base-v2
```

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

### Configure Metadata Provider

Source: https://ggozad.github.io/haiku.rag/ingester

Example configuration for attaching a custom metadata provider to a source.

```yaml
    - type: webdav
      id: handbook
      base_url: https://dav.example.com/remote.php/dav/files/svc
      metadata_provider: example-provider
```

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

### CLI Usage Examples

Source: https://ggozad.github.io/haiku.rag/cli

Basic usage patterns for the haiku-rag CLI including global and per-command options.

```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 add -h
```

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

### Configure a plugin source

Source: https://ggozad.github.io/haiku.rag/ingester

Example YAML configuration for a custom source using the plugin type.

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

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

### View Ingester Service Logs

Source: https://ggozad.github.io/haiku.rag/ingester

Example output showing standard service logging via Rich handler.

```text
INFO     Ingester running: 4 worker(s), 1 source(s)
INFO     API listening on 127.0.0.1:8765
INFO     Swept local-docs: 142 upsert, 0 delete, 8 unchanged
INFO     Processing upsert file:///.../a.md (job 5d9a...)
INFO     Job 5d9a... succeeded in 0.34s: file:///.../a.md
```

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

### Configure Multimodal Embedding Providers

Source: https://ggozad.github.io/haiku.rag/configuration/providers

Configuration examples for multimodal support in vLLM, VoyageAI, and Cohere.

```yaml
embeddings:
  model:
    provider: vllm
    name: Qwen/Qwen3-VL-Embedding-8B
    vector_dim: 4096
    base_url: http://localhost:8000/v1
    multimodal: true
```

```yaml
embeddings:
  model:
    provider: voyageai
    name: voyage-multimodal-3
    vector_dim: 1024
    multimodal: true
```

```yaml
embeddings:
  model:
    provider: cohere
    name: embed-v4.0
    vector_dim: 1536
    multimodal: true
```

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

### List discovered skills

Source: https://ggozad.github.io/haiku.rag/skills

Verify installed skills registered via Python entry points.

```bash
haiku-skills list --use-entrypoints
# rag — Search, retrieve and analyze documents using RAG.
# rag-analysis — Analyze documents using code execution in a sandboxed interpreter.
```

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

### GET /sources

Source: https://ggozad.github.io/haiku.rag/ingester

Retrieves a list of configured data sources.

```APIDOC
## GET /sources

### Description
Lists all configured sources. Requires Authorization header if a token is configured.

### Method
GET

### Endpoint
http://localhost:8765/sources
```

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

### GET /config

Source: https://ggozad.github.io/haiku.rag/ingester

Retrieves the full effective configuration as YAML.

```APIDOC
## GET /config

### Description
Retrieves the full effective configuration (defaults filled in) as YAML, with secrets redacted.

### Method
GET

### Endpoint
/config
```

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

### Start MCP Server via CLI

Source: https://ggozad.github.io/haiku.rag/mcp

Commands to launch the MCP server using different transport protocols and configuration options.

```bash
# Default streamable HTTP transport on 127.0.0.1:8001
haiku-rag mcp

# Custom port
haiku-rag mcp --port 9000

# Bind to all interfaces (e.g. inside a container)
haiku-rag mcp --host 0.0.0.0 --port 8001

# stdio transport (for Claude Desktop)
haiku-rag mcp --stdio

# Read-only mode (excludes write tools)
haiku-rag --read-only mcp --stdio
```

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

### Configure Remote Storage Backends

Source: https://ggozad.github.io/haiku.rag/configuration/storage

Configuration examples for various remote storage providers using the lancedb settings block.

```yaml
# LanceDB Cloud
lancedb:
  uri: db://your-database-name
  api_key: your-api-key
  region: us-west-2  # optional

# Amazon S3
lancedb:
  uri: s3://my-bucket/my-table
  storage_options:
    region: us-east-1

# Amazon S3 with explicit credentials
lancedb:
  uri: s3://my-bucket/my-table
  storage_options:
    aws_access_key_id: YOUR_ACCESS_KEY
    aws_secret_access_key: YOUR_SECRET_KEY
    region: us-east-1

# S3-compatible (SeaweedFS, Tigris, etc.)
lancedb:
  uri: s3://my-bucket/my-table
  storage_options:
    endpoint: http://localhost:8333
    aws_access_key_id: YOUR_ACCESS_KEY
    aws_secret_access_key: YOUR_SECRET_KEY
    region: us-east-1
    allow_http: "true"

# Azure Blob Storage
lancedb:
  uri: az://my-container/my-table

# Google Cloud Storage
lancedb:
  uri: gs://my-bucket/my-table

# HDFS
lancedb:
  uri: hdfs://namenode:port/path/to/table
```

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

### Configure WebDAV with Bearer Token

Source: https://ggozad.github.io/haiku.rag/ingester

Example configuration for a WebDAV source using a bearer token in the headers.

```yaml
    - type: webdav
      id: kdrive
      base_url: https://kdrive.infomaniak.com/app/drive/123/
      headers:
        Authorization: Bearer ${KDRIVE_TOKEN}
```

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

### Configure Additional Pydantic AI Providers

Source: https://ggozad.github.io/haiku.rag/configuration/providers

Examples for configuring other supported providers like Google Gemini, Groq, and Mistral.

```yaml
# Google Gemini
qa:
  model:
    provider: gemini
    name: gemini-1.5-flash

# Groq
qa:
  model:
    provider: groq
    name: llama-3.3-70b-versatile

# Mistral
qa:
  model:
    provider: mistral
    name: mistral-small-latest
```

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

### Set File Size Limit

Source: https://ggozad.github.io/haiku.rag/ingester

Example configuration for enforcing a maximum file size on a file system source.

```yaml
    - type: fs
      root: /data/docs
      max_file_size: 104857600        # 100 MB
```

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

### Compare document structure

Source: https://ggozad.github.io/haiku.rag/skills/analysis

Example of agent-generated code to iterate through documents and compare structural elements.

```python
from pathlib import Path
import json

for doc_id in ["doc-a-id", "doc-b-id"]:
    toc = json.loads(Path(f'/documents/{doc_id}/toc.json').read_text())
    print(f"\n=== {toc['title']} ===")
    for node in toc['tree']:
        if 'experiment' in node['title'].lower():
            print(f"  {node['title']} (pages {node['page_numbers']})")
            await cite(node['chunk_ids'])
```

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

### Enable remote services in docling-serve

Source: https://ggozad.github.io/haiku.rag/remote-processing

Command to start the container with outbound remote service calls enabled, required for VLM picture description.

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

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

### Initialize Database

Source: https://ggozad.github.io/haiku.rag/cli

Creates a new database with configured settings. All other commands require an existing database.

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

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

### Initialize Database via Python

Source: https://ggozad.github.io/haiku.rag/configuration/storage

Asynchronous client initialization for local databases.

```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:
    ...
```

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

### Initialize Database via CLI

Source: https://ggozad.github.io/haiku.rag/configuration/storage

Commands to initialize a database in the default location or at a custom path.

```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
```

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

### Initialize Document Toolset

Source: https://ggozad.github.io/haiku.rag/tools

Creates a toolset for document browsing, retrieval, and summarization.

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

docs = create_document_toolset(config)
```

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

### Initialize and migrate queue database

Source: https://ggozad.github.io/haiku.rag/ingester

Manually prepare the SQLite queue database and apply schema migrations.

```bash
haiku-ingester queue init             # create the DB and schema
haiku-ingester queue migrate          # apply pending schema changes
```

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

### Initialize configuration file

Source: https://ggozad.github.io/haiku.rag/configuration

Generates a default haiku.rag.yaml file in the current directory.

```bash
haiku-rag init-config
```

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

### View Settings

Source: https://ggozad.github.io/haiku.rag/cli

Display the current configuration settings.

```bash
haiku-rag settings
```

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

### GET /api/info

Source: https://ggozad.github.io/haiku.rag/apps

Retrieves database statistics.

```APIDOC
## GET /api/info

### Description
Database statistics.

### Method
GET

### Endpoint
/api/info
```

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

### Get Document

Source: https://ggozad.github.io/haiku.rag/cli

Retrieve a specific document by its ID.

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

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

### Initialize Search Toolset

Source: https://ggozad.github.io/haiku.rag/tools

Creates a hybrid search toolset with context expansion capabilities.

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

search = create_search_toolset(config)
```

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

### GET /health

Source: https://ggozad.github.io/haiku.rag/apps

Performs a health check on the service.

```APIDOC
## GET /health

### Description
Health check.

### Method
GET

### Endpoint
/health
```

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

### Run benchmarks with pre-built database

Source: https://ggozad.github.io/haiku.rag/benchmarks

Execute a benchmark run using a specific database and configuration file while skipping database updates.

```bash
evaluations run orb_multimodal_nemotron --skip-db --config configs/orb_multimodal_nemotron.yaml
```

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

### GET /api/documents

Source: https://ggozad.github.io/haiku.rag/apps

Retrieves a list of all available documents.

```APIDOC
## GET /api/documents

### Description
List all documents.

### Method
GET

### Endpoint
/api/documents
```

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

### GET /health

Source: https://ggozad.github.io/haiku.rag/ingester

Checks the health status of the Ingester service.

```APIDOC
## GET /health

### Description
Returns the health status of the service.

### Method
GET

### Endpoint
http://localhost:8765/health
```

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

### GET /jobs

Source: https://ggozad.github.io/haiku.rag/ingester

Retrieves a filtered list of ingestion jobs.

```APIDOC
## GET /jobs

### Description
Retrieves a filtered list of ingestion jobs based on status, source_id, uri, limit, and offset.

### Method
GET

### Endpoint
/jobs

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter by job status
- **source_id** (string) - Optional - Filter by source ID
- **uri** (string) - Optional - Filter by URI
- **limit** (integer) - Optional - Limit the number of results
- **offset** (integer) - Optional - Offset for pagination
```

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

### Initialize PostgreSQL queue schema

Source: https://ggozad.github.io/haiku.rag/ingester

Apply the schema to the configured PostgreSQL database.

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

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

### Configure environment variables

Source: https://ggozad.github.io/haiku.rag/apps

Create a .env file in the app directory to define API keys, database paths, and optional service URLs.

```text
# 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
```

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

### GET /jobs

Source: https://ggozad.github.io/haiku.rag/ingester

Retrieves a list of ingestion jobs, optionally filtered by status.

```APIDOC
## GET /jobs

### Description
Lists ingestion jobs. Supports filtering by status.

### Method
GET

### Endpoint
http://localhost:8765/jobs

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter jobs by status (e.g., 'dead')
```

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

### Initialize database

Source: https://ggozad.github.io/haiku.rag/tutorial

Initialize the LanceDB database in the default or a custom location.

```bash
haiku-rag init
```

```bash
haiku-rag init --db /tmp/test.lancedb
```

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

### GET /api/visualize/{chunk_id}

Source: https://ggozad.github.io/haiku.rag/apps

Retrieves visual grounding images for a specific chunk.

```APIDOC
## GET /api/visualize/{chunk_id}

### Description
Visual grounding images (base64).

### Method
GET

### Endpoint
/api/visualize/{chunk_id}

### Parameters
#### Path Parameters
- **chunk_id** (string) - Required - The ID of the chunk to visualize
```

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

### Custom Picture Description Prompt

Source: https://ggozad.github.io/haiku.rag/configuration/prompts

Example of a custom prompt for VLM image descriptions.

```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.
```

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

### GET /stats

Source: https://ggozad.github.io/haiku.rag/ingester

Retrieves rolling throughput statistics, worker occupancy, and queue metrics.

```APIDOC
## GET /stats

### Description
Retrieves rolling throughput (5m / 30m / 1h succeeded), worker occupancy, oldest queued age, and per-source DLQ/backlog metrics.

### Method
GET

### Endpoint
/stats
```

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

### Configure Minimum Ingester Source

Source: https://ggozad.github.io/haiku.rag/ingester

Define a basic filesystem source in the haiku.rag.yaml configuration file.

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

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

### Ask questions

Source: https://ggozad.github.io/haiku.rag/cli

Query the RAG system to get answers based on indexed documents.

```bash
haiku-rag ask "Who is the author of haiku.rag?"
```

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

### Define application configuration

Source: https://ggozad.github.io/haiku.rag/apps

Mount a haiku.rag.yaml file to specify model provider and name settings.

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

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

### Implement a basic custom document pipeline

Source: https://ggozad.github.io/haiku.rag/custom-pipelines

Demonstrates the manual sequence of converting, chunking, embedding, and importing a document using the client primitives.

```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 = await 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",
    )
```

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

### Configure Nginx Reverse Proxy

Source: https://ggozad.github.io/haiku.rag/ingester

Example Nginx configuration to serve the control plane under a sub-path.

```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;
}
```

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

### Minimal configuration file

Source: https://ggozad.github.io/haiku.rag/configuration

A basic configuration template defining the production environment and required embedding and QA models.

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

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

qa:
  model:
    provider: ollama
    name: gpt-oss
    enable_thinking: true
```

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

### Aggregate corpus data

Source: https://ggozad.github.io/haiku.rag/skills/analysis

Example of agent-generated code to search for documents and cite top hits.

```python
hits = await search("security vulnerability", limit=50)

doc_ids = {h['document_id'] for h in hits}
print(f"{len(doc_ids)} documents mention security vulnerabilities")

# Cite the top hit per document
seen = set()
for hit in hits:
    if hit['document_id'] not in seen:
        seen.add(hit['document_id'])
        await cite(hit['chunk_id'])
```

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

### Initialize Analysis Skill

Source: https://ggozad.github.io/haiku.rag/skills/analysis

Use create_skill to instantiate the analysis skill, optionally providing a database path or configuration.

```python
from haiku.rag.skills.analysis import create_skill

skill = create_skill(db_path="my.lancedb")
```

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

### Retrieve PDF Attachments

Source: https://ggozad.github.io/haiku.rag/configuration/processing

Example of querying for documents linked to a parent PDF via metadata.

```python
# After ingesting a PDF with two attachments:
parent = await client.create_document_from_source("/path/to/parent.pdf")
children = await client.list_documents(
    filter=f"metadata LIKE '%\"parent_uri\": \"{parent.uri}\"%'"
)
# children: 2 Documents, each with parent.uri in metadata.parent_uri,
# URIs like file:///path/to/parent.pdf#attachment=memo.pdf

```

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

### Run benchmarks with custom configuration

Source: https://ggozad.github.io/haiku.rag/benchmarks

Override default configuration and database paths during an evaluation run.

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

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

### GET /database

Source: https://ggozad.github.io/haiku.rag/ingester

Retrieves a LanceDB snapshot including version, row counts, and index status.

```APIDOC
## GET /database

### Description
Retrieves a LanceDB snapshot including stored version, embeddings, per-table row counts/sizes, vector index status, pending migrations, and package versions.

### Method
GET

### Endpoint
/database
```

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

### Programmatic Configuration

Source: https://ggozad.github.io/haiku.rag/configuration/prompts

Configure prompts using the AppConfig class in Python.

```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.",
    )
)
```

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

### Configure domain preamble

Source: https://ggozad.github.io/haiku.rag/skills/rag

Define a domain-specific preamble in the configuration file to guide model terminology.

```yaml
prompts:
  domain_preamble: |
    The knowledge base contains the operations manual for the Helios solar array.
    "The array" or unqualified specs refer to Helios. Terminology like "string"
    refers to a series-connected panel chain, not text.
```

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

### Create Skill Package

Source: https://ggozad.github.io/haiku.rag/cli

Generate a standalone, pip-installable skill package with an embedded LanceDB database.

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

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

### Register entry point in pyproject.toml

Source: https://ggozad.github.io/haiku.rag/ingester

How to register the source factory in the package metadata.

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

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

### Convert documents using client.convert()

Source: https://ggozad.github.io/haiku.rag/custom-pipelines

Demonstrates converting local files, URLs, plain text, and HTML content into a DoclingDocument.

```python
# From local file
docling_doc = await client.convert("report.pdf")
docling_doc = await client.convert(Path("/absolute/path/to/file.docx"))

# From URL (downloads and converts)
docling_doc = await client.convert("https://example.com/paper.pdf")

# From plain text (parsed as markdown by default)
docling_doc = await client.convert("# Title\n\nYour text content here")

# From HTML text (use format parameter to preserve structure)
html_content = "<h1>Title</h1><p>Paragraph</p><ul><li>Item</li></ul>"
docling_doc = await client.convert(html_content, format="html")

# From file:// URI
docling_doc = await client.convert("file:///path/to/document.md")
```

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

### Define VCR Test

Source: https://ggozad.github.io/haiku.rag/development

Example of an asynchronous test using the VCR decorator and a temporary database 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
```

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

### GET /health

Source: https://ggozad.github.io/haiku.rag/ingester

Retrieves the liveness status of the service, including queue counts and active worker/poller counts.

```APIDOC
## GET /health

### Description
Returns the liveness status of the service, including queue counts and active worker/poller counts. The status field will be either "ok" or "degraded".

### Method
GET

### Endpoint
/health
```

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

### Pre-download Models

Source: https://ggozad.github.io/haiku.rag/installation

Downloads required runtime models including Docling, tokenizer models, and Ollama models.

```bash
haiku-rag download-models
```

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

### Build and Run Full Docker Image

Source: https://ggozad.github.io/haiku.rag/installation

Builds the full Docker image locally and runs it with volume mounts for configuration and data.

```bash
docker build -f docker/Dockerfile -t haiku-rag .
docker run -p 8001:8001 \
  -v /path/to/haiku.rag.yaml:/app/haiku.rag.yaml \
  -v /path/to/data:/data \
  haiku-rag
```

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

### Add Documents from Directory

Source: https://ggozad.github.io/haiku.rag/cli

Recursively add all supported files from a specified directory.

```bash
haiku-rag add-src /path/to/documents/
```

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

### Manage Haiku RAG database connections

Source: https://ggozad.github.io/haiku.rag/python

Use asynchronous context managers to handle database lifecycle. Ensure databases are initialized before opening in read-write mode.

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

# Create a new database
async with HaikuRAG("path/to/database.lancedb", create=True) as client:
    # Your code here
    pass

# Open an existing database (will fail if database doesn't exist)
async with HaikuRAG("path/to/database.lancedb") as client:
    # Your code here
    pass

# Open in read-only mode (blocks writes)
async with HaikuRAG("path/to/database.lancedb", read_only=True) as client:
    results = await client.search("query")  # Read operations work
    # await client.create_document(...)  # Would raise ReadOnlyError
```

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

### Configure PostgreSQL queue

Source: https://ggozad.github.io/haiku.rag/ingester

Point the ingester to a PostgreSQL database server using a SQLAlchemy async URL.

```yaml
ingester:
  queue:
    dburi: postgresql+asyncpg://haiku:secret@db:5432/haiku_rag
```

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

### GET /sources

Source: https://ggozad.github.io/haiku.rag/ingester

Lists configured pollers, their last-poll time, circuit breaker state, and last skip reason.

```APIDOC
## GET /sources

### Description
Lists configured pollers, their last-poll time, circuit breaker state, and last skip reason.

### Method
GET

### Endpoint
/sources
```

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

### Register Metadata Provider Entry Point

Source: https://ggozad.github.io/haiku.rag/ingester

Configuration for registering the metadata provider in the package's pyproject.toml.

```toml
# in the provider package's pyproject.toml
[project.entry-points."haiku.rag.metadata_providers"]
example-provider = "example_pkg:Provider"
```

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

### Read document section in depth

Source: https://ggozad.github.io/haiku.rag/skills/analysis

Example of agent-generated code to parse a table of contents and extract specific section text.

```python
from pathlib import Path
import json

doc_id = "..."  # from a prior search or list_documents
toc = json.loads(Path(f'/documents/{doc_id}/toc.json').read_text())

section = next(n for n in toc['tree'] if n['title'].startswith('5'))
start, end = section['item_range']
lines = Path(f'/documents/{doc_id}/items.jsonl').read_text().splitlines()[start:end]

for line in lines:
    print(json.loads(line)['text'])

await cite(section['chunk_ids'])
```

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

### Expose skills via MCP

Source: https://ggozad.github.io/haiku.rag/skills

Run the MCP server to make skill tools available to external clients like Claude Desktop.

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

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

### Download evaluation databases

Source: https://ggozad.github.io/haiku.rag/benchmarks

Manage local evaluation databases by downloading them from HuggingFace.

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

# Download all datasets
evaluations download all

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

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

### Execute Tests

Source: https://ggozad.github.io/haiku.rag/development

Command to run the test suite using uv.

```bash
uv run pytest
```

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

### YAML Configuration for Prompts

Source: https://ggozad.github.io/haiku.rag/configuration/prompts

Define domain context and VLM prompts in the configuration file.

```yaml
prompts:
  # Domain context prepended to skill instructions
  domain_preamble: |
    This knowledge base contains technical documentation for the Helios solar panel
    system, including installation manuals, maintenance procedures, and safety guidelines.
    Questions about "the system" or unqualified specs refer to the Helios panel.

  # VLM prompt for image description during conversion (optional)
  picture_description: null  # Uses default prompt
```

```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.
```

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

### Generate Configuration File

Source: https://ggozad.github.io/haiku.rag/cli

Create a default YAML configuration file at the specified path or in the current directory.

```bash
haiku-rag init-config [output_path]
```

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

### Add Documents from Text

Source: https://ggozad.github.io/haiku.rag/cli

Add document content directly from the command line with optional titles and metadata.

```bash
haiku-rag add "Your document content here"

# Set a title
haiku-rag add "Your document content here" --title "My Document"

# Attach metadata (repeat --meta for multiple entries)
haiku-rag add "Your document content here" --meta author=alice --meta topic=notes
```

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

### create_skill(db_path, config)

Source: https://ggozad.github.io/haiku.rag/skills/analysis

Initializes the Analysis skill with the specified database path and configuration.

```APIDOC
## create_skill(db_path?, config?)

### Description
Initializes the Analysis skill for the RAG system.

### Parameters
- **db_path** (str) - Optional - Path to LanceDB database. Defaults to HAIKU_RAG_DB env var or config default.
- **config** (AppConfig) - Optional - AppConfig instance. Defaults to get_config().
```

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

### Configure Filesystem Source

Source: https://ggozad.github.io/haiku.rag/ingester

Configure advanced filesystem source options including polling intervals and file pattern filtering.

```yaml
ingester:
  sources:
    - type: fs
      id: local-docs                          # optional; auto-derives from root
      root: /Users/you/docs
      poll_interval_s: 300
      delete_orphans: true
      ignore_patterns: ["**/.git/**", "**/node_modules/**"]
      include_patterns: ["*.md", "*.pdf"]    # optional whitelist
```

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

### Generate a custom skill

Source: https://ggozad.github.io/haiku.rag/skills/custom

Use the create-skill command to initialize a new skill package with a specific database, tools, and preamble.

```bash
haiku-rag create-skill \
  --name recipes \
  --db /path/to/recipes.lancedb \
  --tools search,cite \
  --description "Recipe and cooking knowledge base" \
  --preamble "You are a culinary expert helping with recipes and cooking techniques."
```

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

### Manage database tags

Source: https://ggozad.github.io/haiku.rag/cli

Commands for creating, listing, and deleting logical snapshots of the database state.

```bash
# Tag the current state, e.g. at deploy time or after an ingestion run
haiku-rag tag create release-1

# List tags with the versions they point to
haiku-rag tag list

# Delete a tag, releasing its versions for cleanup
haiku-rag tag delete release-1
```

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

### Initialize a RAG-enabled agent

Source: https://ggozad.github.io/haiku.rag/skills

Create a skill toolset and attach it to a Pydantic AI agent to enable knowledge base querying.

```python
from haiku.rag.skills.rag import create_skill
from haiku.skills.agent import SkillToolset
from haiku.skills.prompts import build_system_prompt
from pydantic_ai import Agent

rag = create_skill(db_path="my.lancedb")
toolset = SkillToolset(skills=[rag])

agent = Agent(
    "openai-chat:gpt-4o",
    instructions=build_system_prompt(toolset.skill_catalog),
    toolsets=[toolset],
)

result = await agent.run("What does the knowledge base say about X?")
print(result.output)
```

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

### Run retrieval and QA benchmarks

Source: https://ggozad.github.io/haiku.rag/tuning

Commands for executing benchmarks with options to optimize performance during iterative development.

```bash
# Run retrieval + QA benchmarks
evaluations run <dataset>

# Skip database rebuild when only changing search/reranking/prompt settings
evaluations run <dataset> --skip-db

# Limit test cases for faster iteration
evaluations run <dataset> --limit 50
```

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

### Configure OpenAI-Compatible Servers

Source: https://ggozad.github.io/haiku.rag/configuration/providers

Use the openai provider with a custom base_url for local inference servers like vLLM or LM Studio.

```yaml
# vLLM example
qa:
  model:
    provider: openai
    name: Qwen/Qwen3-4B
    base_url: http://localhost:8002/v1

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

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

### create_search_toolset(config, expand_context=True, base_filter=None, tool_name="search", on_results=None)

Source: https://ggozad.github.io/haiku.rag/tools

Provides a hybrid search toolset with context expansion capabilities for agents.

```APIDOC
## create_search_toolset

### Description
Provides hybrid search with context expansion.

### Parameters
- **config** (AppConfig) - Required - Configuration object.
- **expand_context** (bool) - Optional (Default: True) - Expand results with surrounding chunks.
- **base_filter** (str) - Optional (Default: None) - SQL WHERE clause applied to all searches.
- **tool_name** (str) - Optional (Default: "search") - Name of the tool exposed to the agent.
- **on_results** (callable) - Optional (Default: None) - Callback (list[SearchResult]) -> None invoked with results.
```

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

### Basic Model Configuration

Source: https://ggozad.github.io/haiku.rag/configuration/providers

Standard configuration block for defining provider, model name, temperature, and token limits.

```yaml
qa:
  model:
    provider: ollama
    name: gpt-oss
    temperature: 0.3
    max_tokens: 500
```

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

### Initialize RAG skill

Source: https://ggozad.github.io/haiku.rag/skills/rag

Create a RAG skill instance by specifying the database path.

```python
from haiku.rag.skills.rag import create_skill

skill = create_skill(db_path="my.lancedb")
```

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

### Chat with documents

Source: https://ggozad.github.io/haiku.rag/tutorial

Launch the interactive TUI or perform a single query via the CLI.

```bash
haiku-rag chat
```

```bash
haiku-rag ask "Who wrote haiku.rag?"
```

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

### Implement Metadata Provider Class

Source: https://ggozad.github.io/haiku.rag/ingester

Implementation of a metadata provider class that extracts folder and byte information.

```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)),
        }
```

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

### Add Documents from File or URL

Source: https://ggozad.github.io/haiku.rag/cli

Import documents from local paths or remote URLs, with support for custom titles and metadata.

```bash
haiku-rag add-src /path/to/document.pdf
haiku-rag add-src https://example.com/article.html

# Optionally set a human‑readable title stored in the DB schema
haiku-rag add-src /mnt/data/doc1.pdf --title "Q3 Financial Report"

# Optionally attach metadata (repeat --meta). Values use JSON parsing if possible:
# numbers, booleans, null, arrays/objects; otherwise kept as strings.
haiku-rag add-src /mnt/data/doc1.pdf --meta source=manual --meta page_count=12 --meta published=true
```
Tokens:
Raw