108 lines
3.5 KiB
Markdown
108 lines
3.5 KiB
Markdown
# Skills
|
|
|
|
haiku.rag exposes its RAG capabilities as [haiku.skills](https://github.com/ggozad/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`](rag.md) | Search, retrieve, and answer questions from the knowledge base |
|
|
| [`rag-analysis`](analysis.md) | Computational analysis via code execution |
|
|
|
|
## Discovery
|
|
|
|
Skills are registered as Python entrypoints under `haiku.skills`. They are discovered automatically by `haiku.skills`:
|
|
|
|
```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.
|
|
```
|
|
|
|
## Usage
|
|
|
|
```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
|
|
|
|
skill = create_skill(db_path=db_path, config=config)
|
|
toolset = SkillToolset(skills=[skill])
|
|
|
|
agent = Agent(
|
|
"openai-chat: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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```python
|
|
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](../cli.md#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`.
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
from pydantic_ai.ui.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](../apps.md#web-application) for a complete implementation.
|