Skip to content

Skills

haiku.rag exposes its RAG capabilities as haiku.skills skills. Skills are self-contained units that bundle tools, instructions, and state — they can be composed into any pydantic-ai agent via SkillToolset.

Available Skills

Skill Description
rag Search, retrieve, and answer questions from the knowledge base
rag-analysis Computational analysis via code execution

Discovery

Skills are registered as Python entrypoints under haiku.skills. They are discovered automatically by haiku.skills:

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

Usage

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

skill = create_skill(db_path=db_path, config=config)
toolset = SkillToolset(skills=[skill])

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

result = await agent.run("What documents do we have?")

Generating Custom Skills

Use create-skill to generate a standalone skill package with an embedded database:

haiku-rag create-skill \
  --name recipes \
  --db /path/to/recipes.lancedb \
  --tools search,cite \
  --description "Recipe knowledge base" \
  --preamble "You are a recipe expert."

This generates a pip-installable package (recipes-skill/) that bundles the database and registers as a haiku.skills entry point. After installing (uv pip install -e ./recipes-skill), the skill is automatically discovered:

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

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

Since each generated skill is self-contained with its own database and instructions, you can generate multiple skills for different domains and run them together. The agent sees each skill's description and routes questions to the appropriate knowledge base automatically.

Generated skills also expose visualize_chunk() for rendering visual grounding. Use chunk IDs from citations or search results in state:

from my_skill import visualize_chunk

images = await visualize_chunk(chunk_id)
# Returns list of PIL Images with highlighted bounding boxes

See CLI: Create Skill for all options.

Database Path Resolution

Both skills resolve the database path in the same order:

  1. db_path argument passed to create_skill()
  2. HAIKU_RAG_DB environment variable
  3. Config default (config.storage.data_dir / "haiku.rag.lancedb")

State Management

Each skill manages its own state under a dedicated namespace. State is automatically synced via the AG-UI protocol when using AGUIAdapter.

rag_state = toolset.get_namespace("rag")
analysis_state = toolset.get_namespace("analysis")

See the individual skill pages for state model details.

AG-UI Streaming

For web applications, use pydantic-ai's AGUIAdapter to stream tool calls, text, and state deltas:

from pydantic_ai.ag_ui import AGUIAdapter

adapter = AGUIAdapter(agent=agent, run_input=run_input)
event_stream = adapter.run_stream()
sse_event_stream = adapter.encode_stream(event_stream)

See the Web Application for a complete implementation.