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>
134 lines
4.2 KiB
Markdown
134 lines
4.2 KiB
Markdown
# omni-token-economy
|
|
|
|
> Biblioteca universal de compactação de tokens para aplicações LLM. **Zero lock-in de backend.**
|
|
|
|
[](https://github.com/jessefreitas/omni-token-economy/actions/workflows/ci.yml)
|
|
[](LICENSE)
|
|
|
|
## Por que existe
|
|
|
|
Sessões longas de Claude Code / aplicações LLM desperdiçam tokens com **redundância semântica**: `summary` que repete `content`, timestamps em microssegundo quando minuto basta, tags `project:xxx` quando o campo `project` já existe, metadata de IDs internos que o modelo nunca usa.
|
|
|
|
Esta biblioteca aplica 5 técnicas comprovadas para remover esse ruído **sem perder significado**:
|
|
|
|
| Técnica | Ganho típico |
|
|
|---|---|
|
|
| Redundância campo-a-campo (overlap ≥60% entre summary e content) | 15-25% |
|
|
| Precisão temporal calibrada ao uso (microssegundo → minuto) | 5-10% |
|
|
| Whitelist de metadata para dados sensíveis (secrets) | 40-70% |
|
|
| Adaptive compression top-N (primeiros K verbatim, resto vira summary) | 50-85% |
|
|
| Drop de campos redundantes por schema | 20-35% |
|
|
|
|
**Combinado:** 25-55% de redução média em chamadas que manipulam dados estruturados.
|
|
|
|
## Instalação
|
|
|
|
```bash
|
|
# TypeScript / Node.js
|
|
npm install @omniforge/omni-token-economy
|
|
|
|
# Python
|
|
pip install omni-token-economy
|
|
```
|
|
|
|
## Uso rápido
|
|
|
|
### TypeScript
|
|
|
|
```typescript
|
|
import { compactRecord, compressContext, compactSecret, estimateTokens } from '@omniforge/omni-token-economy';
|
|
|
|
// Trim de resposta de API antes de passar para o agente
|
|
const slim = compactRecord(apiResponse, {
|
|
redundantPairs: [['summary', 'content'], ['title', 'name']],
|
|
dropFields: ['internal_id', 'updated_at_ms'],
|
|
timestampFields: ['created_at'],
|
|
timestampPrecision: 'minute',
|
|
});
|
|
|
|
// Comprimir lista grande adaptativamente
|
|
const { items, compressed, metrics } = compressContext(searchResults, {
|
|
maxTokens: 3000,
|
|
keepFullFirst: 5,
|
|
summaryField: 'description',
|
|
contentField: 'body',
|
|
telemetry: true,
|
|
});
|
|
console.log(`Economia: ${metrics.reductionPercent}%`);
|
|
|
|
// Metadata de secret — nunca o valor
|
|
const safeView = compactSecret(credential, {
|
|
whitelist: ['key', 'description', 'category', 'rotated_at'],
|
|
});
|
|
|
|
// Estimar tokens antes de enviar
|
|
const tokens = estimateTokens(longText); // ≈ chars / 3
|
|
```
|
|
|
|
### Python
|
|
|
|
```python
|
|
from omni_token_economy import compact_record, compress_context, compact_secret, estimate_tokens
|
|
|
|
slim = compact_record(api_response, rules={
|
|
"redundant_pairs": [("summary", "content"), ("title", "name")],
|
|
"drop_fields": ["internal_id", "updated_at_ms"],
|
|
"timestamp_fields": ["created_at"],
|
|
"timestamp_precision": "minute",
|
|
})
|
|
|
|
result = compress_context(
|
|
search_results,
|
|
max_tokens=3000,
|
|
keep_full_first=5,
|
|
summary_field="description",
|
|
content_field="body",
|
|
telemetry=True,
|
|
)
|
|
print(f"Economia: {result.metrics.reduction_percent}%")
|
|
```
|
|
|
|
## API
|
|
|
|
Ver [docs/API.md](docs/API.md) para referência completa.
|
|
|
|
| Função | Para quê |
|
|
|---|---|
|
|
| `compactRecord(obj, rules)` | Remove redundância de 1 objeto dict/record |
|
|
| `compactRecords(list, rules)` | Aplica em lista |
|
|
| `compressContext(items, opts)` | Compressão adaptativa top-N + summary |
|
|
| `compactSecret(obj, opts)` | Whitelist de metadata para dado sensível |
|
|
| `estimateTokens(text)` | Estimativa rápida: chars / 3 |
|
|
| `detectRedundancy(a, b)` | Overlap de palavras (0.0-1.0) |
|
|
| `isRedundant(short, long, threshold)` | True se `short` é coberto por `long` |
|
|
|
|
## Telemetria
|
|
|
|
Toda função aceita `{ telemetry: true }` e retorna métricas de economia:
|
|
|
|
```typescript
|
|
{
|
|
bytesBefore: 1240,
|
|
bytesAfter: 582,
|
|
tokensBefore: 413,
|
|
tokensAfter: 194,
|
|
tokensSaved: 219,
|
|
reductionPercent: 53.0
|
|
}
|
|
```
|
|
|
|
Com agregação em dashboard, dá para medir ganho real por dev/time/mês.
|
|
Ver [`benchmarks/`](benchmarks/) para rodar em datasets próprios.
|
|
|
|
## Compliance
|
|
|
|
Segue baseline de ISO 27001 + cyber OmniForge — ver [`docs/compliance.md`](docs/compliance.md).
|
|
|
|
Destaques:
|
|
- **A.8.12** — `compactSecret` nunca retorna valor de secret (só metadata), prevenindo vazamento acidental.
|
|
- **A.8.10** — redução de informação desnecessária é uma das funções primárias.
|
|
- Zero log de input com PII.
|
|
|
|
## Licença
|
|
|
|
[MIT](LICENSE).
|