harvester-query
Specter's Harvester es un servicio FastAPI que sirve como interfaz para dos colecciones Chroma:
| Colección | Contenido | Cuándo la usa la API |
|---|---|---|
specter_statutes | 384 estatutos de vehículos motorizados de EE. UU. (CA, TX, FL, PA, IL, OH) | por defecto — cualquier jurisdicción de EE. UU. o consulta genérica |
canada_pi_cases | 340 casos reales canadienses de lesiones personales (CanLII, con daños, tipo de lesión, plaintiff_won, factor decisivo) | enrutado automáticamente cuando la consulta menciona Canadá / Ontario / Quebec / Toronto / ONSC / ONCA / canlii / etc., o cuando se pasa ?jurisdiction=Canada o ?state=CA-CAN |
Toda citación que el usuario vea debe provenir del Harvester (o, en caso de ausencia, de una fuente web verificada). Nunca inventes.
Cuándo usar esta habilidad
- Siempre para patrones de hecho que mencionen Canadá o una provincia/ciudad canadiense. La colección de Canadá está indexada por hechos de casos decididos, por lo que los patrones de hecho confusos ("niño se lastimó afuera de Target en Ontario", "resbalón y caída en una acera helada en Toronto") son EXACTAMENTE para lo que es buena. Ejecuta
searchprimero; haz preguntas de seguimiento solo después de mostrar los resultados. - El usuario solicita una citación específica: "¿cuál es el Cal. Veh. Code § 23152(a)?" →
lookup_citation - El usuario hace una pregunta semántica/temática: "estatutos de DUI en California", "leyes sobre enviar mensajes de texto mientras se conduce" →
search - El usuario hace una pregunta abierta y tú quieres los mejores candidatos: "¿algún estado con un análogo de atropello y fuga al CVC 20001?" →
ask - El usuario usa un sinónimo ("exceso de velocidad", "conducir ebrio", "enviar mensajes de texto") — tradúcelo a una de las 17 categorías canónicas de factores contribuyentes antes de pasarlo como filtro
factor(ver categorías a continuación).
Cuándo NO usarla
- Preguntas puramente procesales o de estrategia de caso ("¿cómo presento una demanda?") — el Harvester solo contiene estatutos (EE. UU.) y jurisprudencia (Canadá).
- Saludos, preguntas de identidad, verificaciones de persona — responde con tu voz sin llamar a la API.
- Preguntas que no requieren una citación (Specter puede responder brevemente preguntas generales sobre derecho de lesiones personales sin una, pero no debe inventar una citación para respaldarlas).
Importante: no retrases con aclaraciones
Para consultas de patrones de hecho canadienses en particular, llama a search primero con lo que el usuario haya dicho, incluso si es vago. Muestra los mejores resultados, LUEGO haz preguntas de seguimiento. El corpus canadiense está indexado por patrón de hecho: las consultas ligeras aún devuelven casos relevantes. Exigir más hechos antes de buscar desperdicia el corpus.
Cómo llamar
El módulo auxiliar se encuentra junto a este SKILL.md:
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent)) # si se ejecuta ad hoc
from client import lookup_citation, search, ask, healthz, list_factors
En OpenClaw, es preferible ejecutarlo mediante exec:
cd ~/Specter && python3 -m openclaw.skills.harvester_query.client lookup "Cal. Veh. Code § 23152(a)"
cd ~/Specter && python3 -m openclaw.skills.harvester_query.client search "conducir ebrio" --state CA --factor "DUI/DWI"
cd ~/Specter && python3 -m openclaw.skills.harvester_query.client ask "¿qué estatutos cubren atropello y fuga en CA?"
O desde Python:
from openclaw.skills.harvester_query.client import lookup_citation, search, ask
lookup_citation(citation: str) -> dict | None
Coincidencia exacta por cadena citation. Devuelve el registro completo o None si no está en el Harvester.
search(q: str, *, state=None, factor=None, pi_only=False, k=10) -> list[dict]
Búsqueda semántica. state es un código de 2 letras ("CA", "TX"). factor debe ser una de las 17 categorías canónicas.
ask(question: str, *, state=None, factor=None, k=8) -> list[dict]
Igual que search pero formulado como pregunta. Úsalo cuando el usuario te haga una consulta en lenguaje natural.
healthz() -> dict
Verificación de estado económica. Úsalo para confirmar que la API está funcionando antes de reportar una ausencia.
list_factors() -> list[str]
Las 17 categorías. Útil para el mapeo de sinónimos en voz.
Cómo formatear resultados para WhatsApp
Reglas de voz de Specter (ver SOUL.md): máximo 2–3 líneas por defecto. Cita, no cites textualmente.
Bueno:
Cal. Veh. Code § 22350. Ley de velocidad básica — no conduzcas más rápido de lo razonable para las condiciones. leginfo.legislature.ca.gov
Malo:
¡Por supuesto! De conformidad con la Sección 22350 del Código de Vehículos de California, "ninguna persona conducirá un vehículo…" (muro de texto)
Siempre incluye el source_url del registro. Nunca incluyas una citación sin uno — según las reglas del hackathon, los registros sin una URL de fuente real no cuentan.
Manejo de ausencias
Si lookup_citation devuelve None o search/ask devuelve []:
- Verifica
healthz()— si la API está caída, dilo claramente. - Si la API está funcionando pero el registro no está, di: "Todavía no está en el Harvester." Luego, ya sea:
- Ofrece buscar en la web desde una fuente autorizada (solo legislaturas, tribunales, colegios de abogados).
- Sugiere que el equipo ingrese esa jurisdicción.
Nunca disimules una ausencia con una suposición.
Las 17 categorías de factores contribuyentes (canónicas, no inventes)
DUI/DWI
Conducir demasiado rápido para las condiciones
Falta de mantenimiento del carril
Falta de obedecer un dispositivo de control de tráfico
Falta de usar/activar la bocina
Falta de ceder el paso en una señal de ceda el paso
Falta de ceder el derecho de paso
Huir de un oficial de policía
Huir de la escena de una colisión
Seguir demasiado de cerca
Carril de viaje inadecuado
Adelantamiento inadecuado
Arranque inadecuado
Parada inadecuada
Giro inadecuado
Conducción temeraria
Uso de un teléfono inalámbrico/enviar mensajes de texto mientras se conduce
Si el usuario usa un sinónimo, tradúcelo internamente y responde con sus palabras.