VectorGov SDK

Busca semântica em legislação brasileira em 3 linhas de Python.

Acesse leis, decretos e instruções normativas com chunks prontos para alimentar qualquer LLM (OpenAI, Claude, Gemini, Ollama, LangChain, MCP).

Novidades:

• 0.19.6 — ⚠️ BREAKING: vg.store_response() removido (endpoint descontinuado). Use result.query_id direto em vg.feedback() (CHANGELOG)
• 0.19.5 — to_context() e builders XML/markdown usam citation no formato jurídico
• 0.19.4 — campo citation em todos os Result types (Art. 75 da Lei 14.133/2021) — pronto para LLMs
• 0.19.2 — créditos em todos os 8 endpoints pagos
• 0.19.0 — IDs internos de implementação removidos do response público

⚡ Quickstart (2 minutos)

pip install vectorgov
export VECTORGOV_API_KEY=vg_sua_chave

from vectorgov import VectorGov

vg = VectorGov()  # lê VECTORGOV_API_KEY da env

result = vg.search("Quando o ETP pode ser dispensado?")

for hit in result:
    label = hit.citation or hit.source  # citation é o formato jurídico (0.19.4+)
    print(f"[{hit.score:.0%}] {label}")
    print(hit.text[:200], "...\n")

[97%] Art. 18 da Lei 14.133/2021
Art. 18. A fase preparatória do processo licitatório é caracterizada pelo planejamento ...

[92%] Art. 14 da IN 58/2022
Art. 14. A elaboração do ETP: I - é facultada nas hipóteses dos incisos I, II, VII e VIII ...

Próximo passo: passar para o seu LLM (3 linhas):

from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=result.to_messages(query="Quando o ETP pode ser dispensado?"),
)
print(response.choices[0].message.content)

🤖 Para LLMs e agentes: este README + a single-page LLM reference foram desenhados para serem alimentados a agentes via curl. O campo hit.citation (formato jurídico brasileiro Art. 75 da Lei 14.133/2021) é o identificador que o seu agente deve usar nas respostas.

🌳 Qual método usar?

graph TD
    A[Quero buscar legislação] --> B{Sei a referência exata?<br/>Ex: 'Art. 75 da Lei 14.133'}
    B -->|Sim| C[vg.lookup<br/>📌 referência legal]
    B -->|Não| D{Que tipo de busca?}
    D -->|Linguagem natural<br/>'O que é ETP?'| E{Preciso de análise<br/>jurídica completa?}
    D -->|Texto literal<br/>'dispensa de licitação'| F[vg.grep<br/>🔍 ripgrep exato]
    D -->|Sigla/termo curado<br/>'ETP', 'PCA'| G[vg.filesystem_search<br/>📚 índice curado]
    E -->|Não, só os artigos| H{Quero também os<br/>artigos relacionados<br/>via grafo?}
    E -->|Sim, com Juiz LLM| I[vg.smart_search<br/>⚖️ análise premium 💰💰]
    H -->|Sim| J[vg.hybrid<br/>🕸️ semântica + grafo]
    H -->|Não, só os mais relevantes| K[vg.search<br/>🎯 semântica simples]
    H -->|Quero máxima cobertura| L[vg.merged<br/>🌊 dual-path RRF]

🧭 Decisão por caso de uso: veja a Cheat Sheet — 1 página com decision tree completa, comparações e padrões idiomáticos.

📋 Os 22 métodos do SDK

🔍 Busca (8)

🤖 Function Calling (4) — para agentes LLM

📊 Tokens, Feedback & Prompts (4)

📚 Documentos (2)

🛡️ Auditoria & Compliance (3)

🛠️ Utilitário (1)

📖 Reference técnica completa: cada método com assinatura, parâmetros, retorno, exemplos e exceções em docs/api/methods.md.

🍳 Receitas comuns

Receita 1 — Passar para o ChatGPT em 3 linhas

from vectorgov import VectorGov
from openai import OpenAI

vg = VectorGov()
result = vg.search("Quais os critérios de julgamento na licitação?")

response = OpenAI().chat.completions.create(
    model="gpt-4o-mini",
    messages=result.to_messages(query="Critérios de julgamento"),
)
print(response.choices[0].message.content)

Receita 2 — Filtrar por norma específica

result = vg.search(
    "credenciamento",
    document_id_filter="LEI-14133-2021",
    top_k=10,
)

Receita 3 — Resolver referência legal

r = vg.lookup("Art. 75 da Lei 14.133")
print(r.match.citation)         # 'Art. 75 da Lei 14.133/2021'
print(r.stitched_text)          # caput + parágrafos + incisos consolidados

Receita 4 — Function calling automático (Claude)

from anthropic import Anthropic

client = Anthropic()
tools = [vg.to_anthropic_tool()]

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "Como funciona dispensa de licitação?"}],
)

# Se Claude chamou a tool, executa
for block in response.content:
    if block.type == "tool_use":
        result_text = vg.execute_tool_call(block)
        print(result_text)

Receita 5 — Rastreabilidade total (citation + evidence)

result = vg.search("contratação direta")
for hit in result:
    print(f"📜 {hit.citation}")
    print(f"   Score: {hit.score:.2%}")
    print(f"   📄 Trecho destacado: {hit.evidence_url}")
    print(f"   📥 PDF original:     {hit.document_url}")
    print()

Receita 6 — Limitar contexto por orçamento de tokens

stats = vg.estimate_tokens(
    result,
    query="Critérios de julgamento",
    system_prompt=vg.get_system_prompt("detailed"),
)
print(f"Total: {stats.total_tokens} tokens")

if stats.total_tokens > 100_000:
    context = result.to_context(max_chars=20_000)
else:
    context = result.to_context()

Receita 7 — Auditoria de uso

stats = vg.get_audit_stats(days=7)
print(f"Eventos últimos 7 dias: {stats.total_events}")
print(f"Bloqueados (security):  {stats.blocked_count}")

critical = vg.get_audit_logs(severity="critical", limit=10)
for log in critical.logs:
    print(f"{log.timestamp} [{log.event_type}] {log.action_taken}")

🍳 Mais receitas: docs/cheat-sheet.md tem 10 padrões idiomáticos completos.

🔌 Integrações

Instalação com extras

# Tudo de uma vez
pip install 'vectorgov[all]'

# Ou apenas o que precisa
pip install 'vectorgov[langchain]'
pip install 'vectorgov[mcp]'

📖 Documentação completa

🔑 Obter sua API key

1. Acesse https://vectorgov.io/dashboard
2. Crie uma conta (free) ou faça login
3. Vá em API Keys → Criar nova chave
4. Configure em sua máquina:

export VECTORGOV_API_KEY=vg_sua_chave_aqui

🆓 Plano free: 100 chamadas/dia em todos os endpoints pagos. Para volume maior ou smart_search ilimitado, veja planos.

🤝 Suporte

• 🐛 GitHub Issues
• 📧 Email: contato@vectorgov.io
• 📚 Documentação completa (mkdocs)
• 💬 Discord da comunidade

📜 Licença

MIT. Veja LICENSE.