Sem dependências
A biblioteca usa só a biblioteca padrão, então adotá-la nunca arrasta uma dependência transitiva para um serviço.
Código: supportops_toolkit/__init__.py
Descartado: Embrulhar uma biblioteca de validação popular.
Toolkit de IA para produção
A camada chata de segurança que impede um agente de machucar a produção.
fixtures verificadas, qualidade não afirmadaÚltima verificação: 2026-10-29 · Commit 22eb0c2
Resumo
- Problema
- Uma chamada de ferramenta precisa de schema, limite e caminho de recusa antes de um modelo agir sobre ela.
- Meu papel
- Projetei a biblioteca e a suíte adversarial.
- Stack
- Python (standard library only)
- Resultado
- O gate fake travado passa: 82 unit tests plus fixture and adversarial checks.
Schemas de tools, retries seguros, limites de passos e tempo, evals code-first, suíte adversarial e helpers de custo, só com a biblioteca padrão do Python. Separa o que está provado do que não está: fixtures testam lógica de controle e nunca são apresentadas como qualidade de modelo.
Veja rodando
O demo ao vivo roda este sistema contra um modelo real e mostra cada passo.
Como funciona
O fluxo inteiro. Aperte tocar ou próximo para percorrer.
Versão em texto deste diagrama
- Chamada de ferramenta P02. Uma chamada chega com argumentos vindos de um modelo.
- depois Guardrails
- Guardrails P02. A entrada é filtrada antes de qualquer execução.
- depois Limites de passos e tempo
- Limites de passos e tempo P02. Um orçamento de passos, tokens e segundos é consumido e aplicado.
- depois Evals code-first
- Evals code-first P02. As checagens rodam como código, contra fixtures e uma suíte adversarial.
- depois Helpers de custo
- Helpers de custo P02. Helpers de roteamento, cache e streaming para custo.
Decisões
Limites são consumidos, não sugeridos
Passos, tokens e segundos são consumidos de um só orçamento, e um orçamento esgotado levanta erro.
Código: supportops_toolkit/guardrails.py
Descartado: Registrar um aviso quando um limite é ultrapassado.
Resultados
Medido
| Métrica | Valor | Modo | Fonte |
|---|---|---|---|
| Gate fake travado Fixtures testam lógica de controle, não qualidade de modelo. | 82 unit tests plus fixture and adversarial checks | fake: lógica de controle | .planning/phases/016-accounted-local-operation/VERIFY.mdCommit 5b91e73 · 2026-10-29 · Exit code 0 |
Não medido, então não afirmado
- Qualidade de modelo. Os evals rodam sobre fixtures.
- Cobertura adversarial contra um modelo real.
Galeria de falhas
- O que aconteceu
- A primeira conclusão real devolveu um erro de requisição inválida e não foi repetida.
- Causa
- A causa exata não foi estabelecida, porque o corpo da resposta não foi retido de propósito.
- O que mudou
- A requisição agora define o teto de tokens de conclusão e esforço de raciocínio baixo, um teste de regressão confere os dois, e uma avaliação real corretiva passou.
- O que aconteceu
- Um teste de lock lia um arquivo de lease em uso no Windows e falhava.
- Causa
- O Windows impede a leitura de um arquivo que outro processo possui.
- O que mudou
- O teste lê metadados saneados depois de o lease ser liberado, e ainda prova que a aquisição concorrente é bloqueada.
Valide você mesmo
git clone https://github.com/DiegoVSouza/supportops-ai-toolkit.git
cd supportops-ai-toolkit
uv sync --locked && uv run --locked python scripts/check_full.pyEsperado: O gate completo passa com fixtures e a suíte adversarial.
O que eu faria diferente
Eu adicionaria uma tabela de classificação de retry neutra a provedor, com um teste por linha, para cada regra de retry ser uma decisão visível.