5fc3ea3d2d
Biblioteca universal de compactação de tokens para aplicações LLM. Zero lock-in de backend — funciona com qualquer dict/object + regras declarativas. Core API (paridade TS ↔ Python): - compactRecord / compact_record — remove redundância via regras declarativas - compactRecords / compact_records — map em lista - compressContext / compress_context — adaptive: top-N verbatim + summary pro resto - compactSecret / compact_secret — whitelist only, valor NUNCA sai (A.8.12) - estimateTokens, detectRedundancy, compactTimestamp — helpers Testes: 27 TS (vitest) + 27 Py (pytest). Fixtures sanitizadas — todos os valores de teste usam placeholders FAKE_TEST_TOKEN_DO_NOT_USE obviamente fake. Regra cardinal #5 (CLAUDE.md): fixtures jamais contêm credencial real. Compliance ISO 27001 / OmniForge baseline: - A.8.10 (exclusão de info desnecessária) — função primária - A.8.11 (mascaramento) — compact_secret whitelist-only - A.8.12 (prevenção de vazamento) — impossível retornar valor de secret - A.8.25/28/29 (dev seguro, codificação, testes) — SDD + TDD + paridade Stack: - TypeScript: Node 24+, ESM, vitest — zero runtime deps - Python: 3.11+, pytest, hatchling — zero runtime deps - CI: lint + test × (3.11, 3.12, 3.13) + gitleaks + CodeQL + benchmark Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
3 KiB
3 KiB
omni-token-economy — instruções para Claude
Biblioteca utilitária universal de compactação de tokens para aplicações LLM. Projeto OmniForge, segue o padrão do marketplace skills_transformers.
Escopo e filosofia
- Universal — zero acoplamento a MCP, backend ou schema específico. Aceita qualquer dict/objeto + regras declarativas.
- Paridade TS ↔ Python — toda função da API pública existe nas duas linguagens com assinatura equivalente.
- Telemetria embutida — cada função aceita
telemetry: truee retorna métricas de economia real (bytes, tokens estimados, %). - Zero efeito colateral — funções puras. Input in, output out. Sem mutação.
Regra cardinal
- Toda nova função em TS precisa de contraparte em Python (e vice-versa).
- Testes espelham a API dos dois lados — se um teste passa em TS mas falha em Py, bug de paridade.
- Nenhum PR merged sem benchmark atualizado mostrando impacto em ≥1 dataset real.
- Classe de dados manipulados: interna. Se alguma função for manipular dado sensível (ex: secret), vai pela API
compactSecretcom whitelist obrigatória. - Fixtures de teste jamais contêm credencial/token real. Sempre usar valores obviamente fake (
FAKE_TEST_TOKEN_DO_NOT_USE,sk-fake-xxx, etc.).
Stack
- TypeScript: Node.js 24+, ESM only, vitest para testes.
- Python: 3.11+, pytest, pyproject.toml / uv.
- Zero runtime deps — lib deve ser instalável em qualquer ambiente sem puxar lixo.
Estrutura
omni-token-economy/
├── src/
│ ├── ts/ # TypeScript
│ └── py/omni_token_economy/ # Python package
├── tests/
│ ├── ts/ # vitest
│ └── py/ # pytest
│ └── fixtures/ # datasets reais (sanitizados)
├── benchmarks/ # scripts de medição com datasets
├── docs/
│ ├── API.md # referência da API pública (TS+Py)
│ ├── compliance.md # adesão ISO/cyber
│ └── benchmarks.md # resultados publicados
└── .github/workflows/ # CI (lint, test TS, test Py, benchmark)
Compliance
Este projeto segue shared/compliance-baseline.md do marketplace.
Controles ISO especialmente relevantes:
- A.8.10 (exclusão de informação desnecessária) — função primária da lib.
- A.8.12 (prevenção de vazamento) —
compactSecretevita exposição de valor; fixtures de teste proibidas de conter secret real. - A.8.28 (codificação segura) — funções puras, sem eval, sem deserialização insegura.
- A.8.29 (testes de segurança) — CI inclui gitleaks e CodeQL.
Estilo
- PT-BR nas docs de usuário (README, docs/).
- Inglês técnico no código (nomes, comentários, mensagens de erro).
- Conventional Commits.
- Sem emoji em código ou commit — docs podem usar com moderação.