bot/skills/hanzo-vector/SKILL.md

name, description, metadata

name	description	metadata
hanzo-vector	Direct vector similarity search via Hanzo Vector (Qdrant). Store embeddings with metadata, search by similarity, manage collections, and build RAG pipelines. Use when a bot needs to store or query vector embeddings, perform semantic similarity search, or manage vector collections.	bot requires primaryEnv emoji bins python3 HANZO_API_KEY 🧮

Hanzo Vector -- Similarity Search Engine

Direct vector operations on Hanzo's managed Qdrant instance. Store embeddings, search by similarity, manage collections, and build RAG pipelines.

Endpoint

Qdrant REST API at https://vector.hanzo.ai (standard HTTPS port 443 via K8s ingress, or internal at vector.hanzo.svc:6333).

Authentication

Pass the API key as the api-key header or via the Qdrant client's api_key parameter.

api-key: <token>

Collections

Create a Collection

python3 {baseDir}/scripts/vector.py collection create \
  --name documents \
  --dimension 384 \
  --distance cosine

List Collections

python3 {baseDir}/scripts/vector.py collection list

Delete a Collection

python3 {baseDir}/scripts/vector.py collection delete --name documents

Collection Info

python3 {baseDir}/scripts/vector.py collection info --name documents

Store Embeddings

Upsert Points

python3 {baseDir}/scripts/vector.py upsert \
  --collection documents \
  --input points.json

Input JSON format:

{
  "points": [
    {
      "id": 1,
      "vector": [0.1, 0.2, 0.3, ...],
      "payload": {
        "text": "Hello world",
        "category": "greeting",
        "source": "docs"
      }
    }
  ]
}

Or pipe from stdin:

echo '{"points": [...]}' | python3 {baseDir}/scripts/vector.py upsert \
  --collection documents \
  --input -

Search by Similarity

python3 {baseDir}/scripts/vector.py search \
  --collection documents \
  --vector "[0.1, 0.2, 0.3, ...]" \
  --limit 10

Search with Filters

python3 {baseDir}/scripts/vector.py search \
  --collection documents \
  --vector "[0.1, 0.2, ...]" \
  --filter '{"must": [{"key": "category", "match": {"value": "tech"}}]}' \
  --limit 10

Filter Syntax

Qdrant filter conditions:

{
  "must": [
    { "key": "category", "match": { "value": "tech" } },
    { "key": "year", "range": { "gte": 2024 } }
  ],
  "should": [{ "key": "author", "match": { "value": "hanzo" } }],
  "must_not": [{ "key": "status", "match": { "value": "draft" } }]
}

Scripts Reference

scripts/vector.py

Unified CLI for all vector operations.

Collection Management

# Create collection
python3 {baseDir}/scripts/vector.py collection create \
  --name <name> --dimension <dim> --distance <cosine|euclid|dot>

# List collections
python3 {baseDir}/scripts/vector.py collection list

# Get collection info
python3 {baseDir}/scripts/vector.py collection info --name <name>

# Delete collection
python3 {baseDir}/scripts/vector.py collection delete --name <name>

Point Operations

# Upsert points from JSON file or stdin
python3 {baseDir}/scripts/vector.py upsert \
  --collection <name> --input <file.json or ->

# Search by vector
python3 {baseDir}/scripts/vector.py search \
  --collection <name> --vector "<json array>" --limit 10

# Search with filter
python3 {baseDir}/scripts/vector.py search \
  --collection <name> --vector "<json array>" \
  --filter '<json filter>' --limit 10

# Get points by ID
python3 {baseDir}/scripts/vector.py get \
  --collection <name> --ids "1,2,3"

# Delete points by ID
python3 {baseDir}/scripts/vector.py delete \
  --collection <name> --ids "1,2,3"

# Count points
python3 {baseDir}/scripts/vector.py count --collection <name>

Common Options

All commands accept:

--host       Qdrant host (default: $HANZO_VECTOR_HOST or https://vector.hanzo.ai)
--port       Qdrant port (only for non-standard ports; HTTPS uses standard 443)
--api-key    API key (default: $HANZO_API_KEY)
--format     Output: text, json (default: text)

RAG Pipeline Example

Generate embeddings with the Hanzo API, store in vector DB, and search:

from hanzoai import Hanzo

# 1. Generate embedding
ai = Hanzo(api_key="...")
embedding = ai.embeddings.create(
    model="text-embedding-3-small",
    input="What is Hanzo MCP?"
).data[0].embedding

# 2. Search vector DB
# python3 {baseDir}/scripts/vector.py search \
#   --collection knowledge --vector "<embedding>" --limit 5

Billing

Vector operations are billed per query (search) and per batch (upsert). Collection management operations are free. Usage is tracked automatically through the bot gateway.

Environment Variables

HANZO_API_KEY=...                             # API key for authentication
HANZO_VECTOR_HOST=https://vector.hanzo.ai     # Qdrant host (standard HTTPS, no port needed)
HANZO_VECTOR_PORT=                            # Only set for non-standard ports (e.g. 6333 for direct access)