omni-token-economy/README.md

omni-token-economy

Biblioteca universal de compactação de tokens para aplicações LLM. Zero lock-in de backend.

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

# TypeScript / Node.js
npm install @omniforge/omni-token-economy

# Python
pip install omni-token-economy

Uso rápido

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

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 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:

{
  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/ para rodar em datasets próprios.

Compliance

Segue baseline de ISO 27001 + cyber OmniForge — ver 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.