sandeco-token-reduce

sandeco-token-reduce

Comprime tokens removendo os menos relevantes de um texto, preservando o significado semantico. Usa o modelo XLM-RoBERTa da Microsoft (LLMLingua-2) rodando localmente (CPU ou GPU).

Estrutura

sandeco-token-reduce/
├── SKILL.md          ← este arquivo
├── scripts/
│   ├── setup.py      ← inicializacao (cria .venv, instala libs, baixa modelo)
│   └── compress.py   ← compressao de texto (requer init)
└── .venv/            ← criado pelo setup.py (NAO distribuir)

IMPORTANTE: Fluxo de inicializacao

A skill precisa ser inicializada antes do primeiro uso. O .venv NAO e distribuido junto com a skill — cada usuario precisa rodar o init uma vez.

Antes de qualquer operacao de compressao:

1. Verifique se o .venv existe dentro do diretorio desta skill
2. Se NAO existir, informe ao usuario que a skill precisa ser inicializada e execute o setup:

python "<skill-dir>/scripts/setup.py"

O setup faz 4 coisas automaticamente:

• Cria o ambiente virtual .venv
• Atualiza o pip
• Instala llmlingua e anthropic
• Baixa o modelo LLMLingua-2 (~1 GB) do HuggingFace

Avise o usuario que a primeira execucao pode levar alguns minutos por causa do download do modelo.

3. Se o .venv JA existir, pule direto para a compressao.

Quando o usuario pedir para "inicializar", "configurar" ou "init" a skill:

Execute o setup.py diretamente, mesmo que o .venv ja exista (ele e idempotente).

Como comprimir

Depois de inicializado, use o script compress.py com o Python do venv.

O Python do venv esta em:

• Windows: <skill-dir>/.venv/Scripts/python.exe
• Unix: <skill-dir>/.venv/bin/python

So comprimir (texto direto)

"<venv-python>" "<skill-dir>/scripts/compress.py" --text "texto longo aqui" --rate 0.4

Comprimir a partir de arquivo

"<venv-python>" "<skill-dir>/scripts/compress.py" --file caminho/para/arquivo.txt --rate 0.4

Comprimir e salvar resultado em arquivo

"<venv-python>" "<skill-dir>/scripts/compress.py" --file entrada.txt --rate 0.4 --output comprimido.txt

Comprimir e enviar ao Claude com uma pergunta

"<venv-python>" "<skill-dir>/scripts/compress.py" --file entrada.txt --rate 0.4 --ask "Resuma este texto"

Saida JSON (para consumo programatico)

"<venv-python>" "<skill-dir>/scripts/compress.py" --file entrada.txt --rate 0.4 --json

Parametros do compress.py

Guia de taxas de compressao

• 0.5 — Compressao leve, maxima fidelidade
• 0.4 — Equilibrio padrao (recomendado para a maioria dos casos)
• 0.33 — Compressao moderada
• 0.2 — Compressao agressiva para textos muito longos

Quando o usuario nao especificar uma taxa, use 0.4.

Formato da saida JSON

Quando --json e usado:

{
  "compression": {
    "compressed_prompt": "texto comprimido...",
    "origin_tokens": 312,
    "compressed_tokens": 124,
    "ratio": 2.52,
    "saving": 188,
    "rate_requested": 0.4
  },
  "claude": {
    "answer": "resposta do Claude...",
    "model": "claude-sonnet-4-6",
    "input_tokens": 150,
    "output_tokens": 200
  }
}

O campo claude so aparece quando --ask e usado.

Notas tecnicas

• Modelo HuggingFace: microsoft/llmlingua-2-xlm-roberta-large-meetingbank
• Cache do modelo: ~/.cache/huggingface/ (baixado uma vez pelo setup, reusado sempre)
• force_tokens preserva: \n, ., ,, ?, !, :, negacoes PT (nao, sem, nenhum, nunca, nem, nenhuma)
• force_reserve_digit=True protege qualquer token com digitos (IDs como RF-01, valores como 1000ms)
• GPU e detectada automaticamente se torch + CUDA estiver disponivel; caso contrario usa CPU
• A variavel ANTHROPIC_API_KEY precisa estar definida no ambiente para usar --ask

Pre-processamento automatico

Antes de comprimir, o texto passa por strip_markdown() que remove:

• Separadores ---
• Grid de tabelas |---|---|
• Marcadores **bold** (mantem texto)
• Prefixos ## de headers (mantem texto)
• Checkboxes - [ ]
• Code fences ```
• Linhas vazias multiplas (colapsa para uma)

Isso reduz ~6% do texto antes de entrar no modelo, melhorando a qualidade da compressao.

Chunking automatico

O modelo XLM-RoBERTa tem janela de 512 tokens. Para textos maiores, o script divide automaticamente em chunks de ate 400 tokens (cortando em limites de linha), comprime cada um separadamente e concatena os resultados. Isso elimina o scoring degradado que ocorria em tokens apos a posicao 512.