harvester-query
L'API Specter's Harvester est un service FastAPI qui gère deux collections Chroma :
| Collection | Contenu | Quand l'API l'utilise |
|---|---|---|
specter_statutes | 384 lois américaines sur les véhicules à moteur (CA, TX, FL, PA, IL, OH) | par défaut — toute juridiction américaine ou requête générique |
canada_pi_cases | 340 affaires canadiennes réelles de préjudices corporels (CanLII, avec dommages, type de blessure, plaintiff_won, deciding_factor) | aiguillage automatique lorsque la requête mentionne Canada / Ontario / Québec / Toronto / ONSC / ONCA / canlii / etc., ou lorsque ?jurisdiction=Canada ou ?state=CA-CAN est passé |
Chaque citation que l'utilisateur voit doit provenir du Harvester (ou, en cas d'absence, d'une source web vérifiée). Ne jamais inventer.
Quand utiliser cette compétence
- Toujours pour les schémas factuels mentionnant le Canada ou une province/ville canadienne. La collection Canada est indexée sur les faits des affaires jugées, donc les schémas factuels complexes ("enfant blessé devant Target en Ontario", "glissade sur un trottoir glacé à Toronto") sont EXACTEMENT ce qu'elle traite le mieux. Lancez
searchd'abord ; posez des questions de suivi seulement après avoir montré les résultats. - L'utilisateur demande une citation spécifique : "qu'est-ce que le Cal. Veh. Code § 23152(a) ?" →
lookup_citation - L'utilisateur pose une question sémantique/thématique : "lois DUI en Californie", "lois sur l'envoi de SMS en conduisant" →
search - L'utilisateur pose une question ouverte et vous voulez les meilleures candidates : "un état a-t-il une analogie au délit de fuite avec le CVC 20001 ?" →
ask - L'utilisateur utilise un synonyme ("excès de vitesse", "conduite en état d'ivresse", "texto") — mappez-le à l'une des 17 catégories canoniques de facteurs contributifs avant de le passer comme filtre
factor(voir les catégories ci-dessous).
Quand ne PAS l'utiliser
- Questions purement procédurales/stratégiques de dossier ("comment déposer ?") — le Harvester ne contient que des lois (États-Unis) et de la jurisprudence (Canada).
- Salutations, questions d'identité, vérifications de personnalité — répondez sans appeler l'API.
- Questions qui ne nécessitent pas de citation (Specter peut répondre brièvement à des questions générales sur la forme de la loi en matière de préjudices corporels sans citation, mais ne doit pas inventer une citation pour les étayer).
Important : ne pas bloquer derrière une clarification
Pour les requêtes de schémas factuels canadiens surtout, appelez search d'abord avec ce que l'utilisateur a dit, même si c'est vague. Affichez les meilleurs résultats, PUIS posez des questions de suivi. Le corpus Canada est indexé par schéma factuel — des requêtes vagues renvoient quand même des affaires pertinentes. Exiger plus de faits avant de chercher gaspille le corpus.
Comment appeler
Le module d'aide se trouve à côté de ce SKILL.md :
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent)) # si exécution ad hoc
from client import lookup_citation, search, ask, healthz, list_factors
Dans OpenClaw, privilégiez l'exécution via 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 "conduite en état d'ivresse" --state CA --factor "DUI/DWI"
cd ~/Specter && python3 -m openclaw.skills.harvester_query.client ask "quelles lois couvrent le délit de fuite en CA"
Ou depuis Python :
from openclaw.skills.harvester_query.client import lookup_citation, search, ask
lookup_citation(citation: str) -> dict | None
Correspondance exacte par chaîne citation. Retourne l'enregistrement complet ou None s'il n'est pas dans le Harvester.
search(q: str, *, state=None, factor=None, pi_only=False, k=10) -> list[dict]
Recherche sémantique. state est un code à 2 lettres ("CA", "TX"). factor doit être l'une des 17 catégories canoniques.
ask(question: str, *, state=None, factor=None, k=8) -> list[dict]
Identique à search mais formulé comme une question. Utilisez-le lorsque l'utilisateur vous donne une requête en langage naturel.
healthz() -> dict
Vérification de bon fonctionnement peu coûteuse. Utilisez-la pour confirmer que l'API fonctionne avant de signaler une absence.
list_factors() -> list[str]
Les 17 catégories. Utile pour le mappage de synonymes dans la voix.
Comment formater les résultats pour WhatsApp
Règles vocales de Specter (voir SOUL.md) : 2–3 lignes max par défaut. Citez, ne citez pas textuellement.
Bon :
Cal. Veh. Code § 22350. Loi de base sur la vitesse — ne pas conduire plus vite que ce qui est raisonnable selon les conditions. leginfo.legislature.ca.gov
Mauvais :
Bien sûr ! Conformément à l'article 22350 du Code des véhicules de Californie, "nul ne doit conduire un véhicule…" (mur de texte)
Incluez toujours le source_url de l'enregistrement. N'incluez jamais une citation sans celui-ci — selon les règles du hackathon, les enregistrements sans URL source réelle ne comptent pas.
Gestion des absences
Si lookup_citation retourne None ou search/ask retourne [] :
- Vérifiez
healthz()— si l'API est hors service, dites-le clairement. - Si l'API fonctionne mais que l'enregistrement n'est pas là, dites : "Pas encore dans le Harvester." Ensuite, soit :
- Proposez de récupérer sur le web depuis une source officielle (législatures, tribunaux, barreaux uniquement).
- Suggérez à l'équipe d'ingérer cette juridiction.
Ne masquez jamais une absence par une supposition.
Les 17 catégories de facteurs contributifs (canoniques, n'en inventez pas)
DUI/DWI
Conduite trop rapide pour les conditions
Défaut de maintien de voie
Défaut d'obéir à un dispositif de contrôle de la circulation
Défaut d'utiliser/actionner le klaxon
Défaut de céder le passage à un panneau de cédez-le-passage
Défaut de céder le droit de passage
Fuite devant un agent de police
Fuite des lieux d'une collision
Suivi trop serré
Voie de circulation inappropriée
Dépassement inapproprié
Démarrage inapproprié
Arrêt inapproprié
Virage inapproprié
Conduite imprudente
Utilisation d'un téléphone sans fil/envoi de SMS en conduisant
Si l'utilisateur utilise un synonyme, mappez-le en interne et répondez dans ses mots.