chromadb-skills-vector-search

name	chromadb-skills-vector-search
version	2.0.0
description	Búsqueda semántica de skills usando ChromaDB local + qwen3-embedding (NaN API). Indexa 190+ skills como vectores 4096-dim y consulta por similitud para cargar solo los relevantes.
tags	["chromadb","embeddings","skills","vector-search","mastermind","qwen3","nan"]

ChromaDB Skills Vector Search

Resumen

Sistema de búsqueda semántica de skills usando ChromaDB local (puerto 8000 en Hermes VM) y el modelo qwen3-embedding de NaN API. Indexa 190+ skills como vectores de 4096 dimensiones y permite consultarlos por similitud de contenido.

Estado actual: ✅ 190 skills indexados, funcionando en localhost:8000

Arquitectura

Petición del usuario
  ↓
Mastermind extrae palabras clave / intención
  ↓
Script consultar-skills.py → embedding (qwen3-embedding) → query ChromaDB local
  ↓
Top-5 skills más relevantes con scores de similitud (0.0 - 1.0)
  ↓
Mastermind carga SOLO esos skills con skill_view()
  ↓
Ejecuta la tarea con contexto preciso

Componentes

ChromaDB Server (local)

• URL: http://localhost:8000
• Colección: mastermind-skills
• Datos persistentes: /hermes-home/chromadb-data/
• Versión: 1.5.9
• Arranque: python3 -c "from chromadb.server.fastapi import FastAPI; from chromadb.config import Settings; import uvicorn; server = FastAPI(Settings(persist_directory='/hermes-home/chromadb-data', is_persistent=True)); uvicorn.run(server.app(), host='0.0.0.0', port=8000)"

Scripts

Script	Ruta	Función
indexar-skills.py	/hermes-home/scripts/indexar-skills.py	Indexar todos los skills en ChromaDB
consultar-skills.py	/hermes-home/scripts/consultar-skills.py	Consultar skills por similitud semántica

Modelo de Embeddings

• Modelo: qwen3-embedding vía api.nan.builders/v1/embeddings
• Dimensiones: 4096
• API Key: NAN_API (variable de entorno del sistema)
• Rate limit: 60 req/min, 3 paralelo

Uso

Indexar skills

cd /hermes-home/scripts && NAN_API="$NAN_API" python3 indexar-skills.py

Re-indexar desde cero

cd /hermes-home/scripts && NAN_API="$NAN_API" python3 indexar-skills.py --reset

Consultar skills (modo humano)

cd /hermes-home/scripts && NAN_API="$NAN_API" python3 consultar-skills.py "generar informe del mercado eléctrico"

Consultar skills (modo JSON — para Mastermind)

cd /hermes-home/scripts && NAN_API="$NAN_API" python3 consultar-skills.py "texto" --json

Desde Mastermind (flujo integrado)

import subprocess, json, os

# 1. Consultar ChromaDB
result = subprocess.run(
    ["python3", "/hermes-home/scripts/consultar-skills.py", query_text, "--json"],
    capture_output=True, text=True, timeout=30,
    env={**os.environ, "NAN_API": os.environ.get("NAN_API", "")}
)
skills = json.loads(result.stdout)["results"]

# 2. Filtrar por score mínimo
relevantes = [s for s in skills if s["score"] > 0.5]

# 3. Cargar top-3 skills
for s in relevantes[:3]:
    skill_view(name=s["name"])

Formato de datos en ChromaDB

Cada skill se guarda con:

• id: nombre del skill (único)
• embedding: vector 4096-dim desde qwen3-embedding
• metadata: name, category, tags, version, description
• document: texto combinado (nombre + descripción + tags + secciones relevantes)

Mantenimiento

Re-indexación automática

• Cron semanal: domingo 04:00 UTC
• Trigger manual: después de crear/actualizar un skill

Cuándo re-indexar

• Después de crear un skill nuevo
• Después de actualizar un skill existente
• Si se detectan skills con score bajo en consultas donde deberían aparecer

Pitfalls

• Rate limit NaN: 60 req/min. Si hay muchos skills nuevos, indexar en lotes con sleep(1.5) entre calls
• ChromaDB caído tras reinicio: Si la VM se reinicia, ChromaDB no arranca solo. Solución: systemd unit o script de autostart
• Embedding fallido: Si qwen3-embedding falla (429), reintentar con sleep(3). Si falla 3 veces, saltar ese skill
• Memoria: ChromaDB usa ~500MB RAM con 200 skills. En MicroVM de 2GB va justo pero funciona
• No duplicar IDs: Si un skill ya existe, se sobrescribe (add con mismo id = upsert)
• Fallback: Si ChromaDB no responde, Koldedebe cargar skills por el método tradicional (snapshot completo)

Referencias

• Scripts: /hermes-home/scripts/indexar-skills.py, /hermes-home/scripts/consultar-skills.py
• Datos: /hermes-home/chromadb-data/
• API NaN: https://api.nan.builders/v1/embeddings
• Modelo: qwen3-embedding
• Skill relacionado: mastermind-orchestration