harvester-query
O Harvester do Specter é um serviço FastAPI que atua como interface para duas coleções Chroma:
| Coleção | Conteúdo | Quando a API usa |
|---|---|---|
specter_statutes | 384 estatutos de veículos motorizados dos EUA (CA, TX, FL, PA, IL, OH) | padrão — qualquer jurisdição dos EUA ou consulta genérica |
canada_pi_cases | 340 casos reais de danos pessoais canadenses (CanLII, com danos, tipo de lesão, plaintiff_won, deciding_factor) | roteado automaticamente quando a consulta menciona Canadá / Ontário / Quebec / Toronto / ONSC / ONCA / canlii / etc., ou quando ?jurisdiction=Canada ou ?state=CA-CAN é passado |
Toda citação que o usuário vir deve vir do Harvester (ou, em caso de falha, de uma fonte web verificada). Nunca invente.
Quando usar esta skill
- Sempre para padrões de fato mencionando Canadá ou uma província/cidade canadense. A coleção canadense é indexada por fatos de casos decididos, então padrões de fato confusos ("criança se machucou fora do Target em Ontário", "escorregão e queda em calçada congelada em Toronto") são EXATAMENTE o que ela faz bem. Execute
searchprimeiro; faça perguntas complementares apenas depois de mostrar os resultados. - Usuário pede uma citação específica: "qual é o Cal. Veh. Code § 23152(a)?" →
lookup_citation - Usuário faz uma pergunta semântica / temática: "Estatutos de DUI na Califórnia", "leis sobre dirigir e enviar mensagens de texto" →
search - Usuário faz uma pergunta aberta e você quer os melhores candidatos: "algum estado com análogo de fuga de cena ao CVC 20001?" →
ask - Usuário usa um sinônimo ("excesso de velocidade", "dirigir embriagado", "enviar mensagens de texto") — mapeie para uma das 17 categorias canônicas de fator contribuinte antes de passar como filtro
factor(veja categorias abaixo).
Quando NÃO usar
- Perguntas puramente processuais / de estratégia de caso ("como faço para arquivar?") — o Harvester contém apenas estatutos (EUA) e jurisprudência (Canadá).
- Saudações, perguntas de identidade, verificações de personalidade — responda com a voz sem chamar a API.
- Perguntas que não exigem uma citação (Specter pode responder brevemente perguntas gerais sobre direito de danos pessoais sem uma, mas não deve inventar uma citação para apoiá-las).
Importante: não atrase pedindo esclarecimentos
Para consultas de padrões de fato canadenses especialmente, chame search primeiro com o que o usuário disse, mesmo que vago. Mostre os principais resultados, DEPOIS faça perguntas complementares. O corpus canadense é indexado por padrão de fato — consultas superficiais ainda retornam casos relevantes. Exigir mais fatos antes de pesquisar desperdiça o corpus.
Como chamar
O módulo auxiliar fica ao lado deste SKILL.md:
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent)) # se executar ad hoc
from client import lookup_citation, search, ask, healthz, list_factors
No OpenClaw, prefira executá-lo 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 "drunk driving" --state CA --factor "DUI/DWI"
cd ~/Specter && python3 -m openclaw.skills.harvester_query.client ask "what statutes cover hit and run in CA"
Ou em Python:
from openclaw.skills.harvester_query.client import lookup_citation, search, ask
lookup_citation(citation: str) -> dict | None
Correspondência exata pela string citation. Retorna o registro completo ou None se não estiver no Harvester.
search(q: str, *, state=None, factor=None, pi_only=False, k=10) -> list[dict]
Pesquisa semântica. state é um código de 2 letras ("CA", "TX"). factor deve ser uma das 17 categorias canônicas.
ask(question: str, *, state=None, factor=None, k=8) -> list[dict]
Mesmo que search, mas enquadrado como pergunta. Use quando o usuário fornecer uma consulta em linguagem natural.
healthz() -> dict
Verificação de atividade barata. Use para confirmar que a API está rodando antes de relatar uma falha.
list_factors() -> list[str]
As 17 categorias. Útil para mapeamento de sinônimos na voz.
Como formatar resultados para WhatsApp
Regras de voz do Specter (veja SOUL.md): máximo de 2–3 linhas por padrão. Cite, não quote.
Bom:
Cal. Veh. Code § 22350. Lei básica de velocidade — dirija não mais rápido que o razoável para as condições. leginfo.legislature.ca.gov
Ruim:
Claro! De acordo com o California Vehicle Code Section 22350, "nenhuma pessoa dirigirá um veículo…" (parede de texto)
Sempre inclua o source_url do registro. Nunca inclua uma citação sem uma — conforme regras do hackathon, registros sem uma URL de fonte real não contam.
Tratamento de falhas
Se lookup_citation retornar None ou search/ask retornar []:
- Verifique
healthz()— se a API estiver fora do ar, diga claramente. - Se a API estiver ativa mas o registro não estiver lá, diga: "Ainda não está no Harvester." Depois, ou:
- Ofereça-se para buscar na web de uma fonte autorizada (apenas legislaturas, tribunais, associações de advogados).
- Sugira que o time ingira essa jurisdição.
Nunca encubra uma falha com um palpite.
As 17 categorias de fator contribuinte (canônicas, não invente)
DUI/DWI
Dirigir Muito Rápido para as Condições
Falha em Manter a Faixa
Falha em Obedecer a Dispositivo de Controle de Tráfego
Falha em Usar/Ativar Buzina
Falha em Dar Preferência em Placa de Parada
Falha em Dar Preferência de Passagem
Fugir de Policial
Fugir do Local do Acidente
Seguir Muito Próximo
Faixa de Viagem Incorreta
Ultrapassagem Incorreta
Partida Incorreta
Parada Incorreta
Conversão Incorreta
Direção Perigosa
Uso de Telefone Sem Fio/Enviar Mensagens ao Dirigir
Se o usuário usar um sinônimo, mapeie internamente e responda com as palavras dele.