mirror of
https://github.com/jessefreitas/omni-token-economy.git
synced 2026-04-26 04:13:49 +00:00
Jesse Freitas
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>
60 lines
3 KiB
Markdown
60 lines
3 KiB
Markdown
# 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`](https://github.com/jessefreitas/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: true` e retorna métricas de economia real (bytes, tokens estimados, %).
|
|
- **Zero efeito colateral** — funções puras. Input in, output out. Sem mutação.
|
|
|
|
## Regra cardinal
|
|
|
|
1. Toda nova função em TS **precisa** de contraparte em Python (e vice-versa).
|
|
2. Testes espelham a API dos dois lados — se um teste passa em TS mas falha em Py, bug de paridade.
|
|
3. Nenhum PR merged sem benchmark atualizado mostrando impacto em ≥1 dataset real.
|
|
4. Classe de dados manipulados: interna. Se alguma função for manipular dado sensível (ex: secret), vai pela API `compactSecret` com whitelist obrigatória.
|
|
5. **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`](https://github.com/jessefreitas/skills_transformers/blob/main/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) — `compactSecret` evita 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.
|