bot/skills/hanzo-search/SKILL.md

name, description, metadata

name	description	metadata
hanzo-search	Search indexed documentation and knowledge bases via Hanzo Search. Supports fulltext search with faceted filtering and ranking. Use when a bot needs to search docs, knowledge bases, or indexed content, or when a user asks to find information across indexed sources.	bot requires primaryEnv emoji bins python3 HANZO_API_KEY 🔍

Hanzo Search -- Document Search API

Search indexed documentation and knowledge bases with fulltext retrieval and faceted filtering.

API Endpoints

Base URL: https://search.hanzo.ai

Endpoint	Method	Purpose
/indexes/{index}/search	POST	Search documents in an index
/indexes	GET	List all indexes
/indexes/{index}	GET	Get index details
/indexes/{index}/documents	GET	Browse documents in an index

Authentication

All requests require a Bearer token in the Authorization header. Set HANZO_SEARCH_KEY or HANZO_API_KEY.

Authorization: Bearer <token>

Search Documents

python3 {baseDir}/scripts/search.py --query "how to deploy" --store my-docs

Request Body (/indexes/{index}/search)

{
  "q": "how to deploy to kubernetes",
  "limit": 10,
  "offset": 0,
  "filter": "category = 'deployment'"
}

Fields

• q (required): Search query string
• limit (optional): Max results (default 10, max 100)
• offset (optional): Pagination offset (default 0)
• filter (optional): Filter expression (e.g. "category = 'deployment'")
• sort (optional): Array of sort rules (e.g. ["updated_at:desc"])
• attributesToRetrieve (optional): Array of attributes to return
• attributesToHighlight (optional): Array of attributes to highlight

Response

{
  "hits": [
    {
      "id": "doc-123",
      "title": "Kubernetes Deployment Guide",
      "url": "https://docs.example.com/deploy",
      "content": "To deploy your application to Kubernetes...",
      "category": "deployment",
      "updated_at": "2026-01-15"
    }
  ],
  "query": "how to deploy to kubernetes",
  "processingTimeMs": 12,
  "estimatedTotalHits": 42,
  "limit": 10,
  "offset": 0
}

RAG Chat over Search Results

RAG chat requires the Hanzo Cloud API layer. The chat.py script calls the /api/chat-docs endpoint which retrieves documents and generates an LLM-grounded response.

python3 {baseDir}/scripts/chat.py --query "explain the deployment process" --store my-docs

Request Body (/api/chat-docs)

{
  "query": "explain the deployment process step by step",
  "store": "my-docs",
  "mode": "hybrid",
  "limit": 5,
  "stream": true
}

Fields

• query (required): Chat question
• store (required): Search store to ground answers in
• mode (optional): Search mode for retrieval ("hybrid", "fulltext", "vector")
• limit (optional): Number of source documents to retrieve (default 5)
• stream (optional): Stream response chunks (default true)
• model (optional): LLM model for chat generation
• system_prompt (optional): Override system prompt for the chat

Streaming Response

Each line is a JSON chunk:

{"type": "source", "data": {"id": "doc-123", "title": "...", "url": "...", "score": 0.95}}
{"type": "chunk", "data": {"text": "The deployment process"}}
{"type": "chunk", "data": {"text": " involves three steps..."}}
{"type": "done", "data": {"sources_count": 5, "tokens_used": 342}}

Scripts

scripts/search.py

Search documents from the command line via Hanzo Search.

python3 {baseDir}/scripts/search.py \
  --query "search terms" \
  --store "index-name" \
  --limit 10 \
  --token "$HANZO_API_KEY"

scripts/chat.py

RAG chat over search results (requires Hanzo Cloud API layer).

python3 {baseDir}/scripts/chat.py \
  --query "your question" \
  --store "store-name" \
  --limit 5 \
  --token "$HANZO_API_KEY"

Billing

Each search query is billed per the Hanzo Search pricing tier. RAG chat queries include both the search cost and the LLM generation cost. Usage is tracked automatically through the bot gateway.

Environment Variables

HANZO_SEARCH_KEY=...                                  # Search API key
HANZO_API_KEY=...                                  # Fallback API key
HANZO_SEARCH_BASE_URL=https://search.hanzo.ai      # Override search API base URL
HANZO_CHAT_BASE_URL=https://search.hanzo.ai        # Override RAG chat API base URL