Metadata-Version: 2.4
Name: redux-token
Version: 0.3.1
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing
Requires-Dist: typer>=0.12
Requires-Dist: mcp>=1.0
Requires-Dist: pytest>=8.0 ; extra == 'dev'
Provides-Extra: dev
License-File: LICENSE
Summary: Compressor inteligente de tokens para LLMs
Keywords: llm,tokens,compression,openai,claude,nlp,rust
Author-email: Elizio Martins <elizio.matins@gmail.com>
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/ElizioMartins/ReduxToken
Project-URL: Issues, https://github.com/ElizioMartins/ReduxToken/issues
Project-URL: Repository, https://github.com/ElizioMartins/ReduxToken

# ReduxToken

Compressor inteligente de tokens para LLMs. Reduz o custo e o consumo de tokens ao comprimir texto, JSON, código e logs antes de enviá-los para modelos como Claude e GPT-4.

Core de alta performance em **Rust**, interface acessível em **Python**.

## Benchmark

| Conteúdo | Tokens antes | Tokens depois | Economia |
|---|---|---|---|
| Log com DEBUG/TRACE | 1 166 | 47 | **96%** |
| JSON com metadados | 522 | 155 | **70%** |
| Código com comentários | 844 | 60 | **93%** |
| Texto repetitivo | 367 | 12 | **97%** |
| **Média** | | | **~90%** |

**Informação preservada:** a compressão remove ruído sem descartar o sinal. Um benchmark
determinístico (`python benchmarks/retention.py`) verifica, por cenário, que os trechos
essenciais sobrevivem — **100% de retenção do sinal** e 100% de remoção de ruído nos casos
testados. É validado no CI como teste de regressão.

## Instalação

```bash
pip install redux-token
```

> Wheels disponíveis para Linux, macOS e Windows — Python 3.10, 3.11, 3.12 e 3.13.

## Uso rápido

```python
from redux_token import ReduxToken

rt = ReduxToken()
compressed, stats = rt.compress("seu texto aqui")

print(f"Tokens economizados: {stats.tokens_saved} ({stats.savings_pct:.1f}%)")
```

## Como funciona

ReduxToken aplica filtros sequenciais ao conteúdo antes de enviá-lo ao LLM:

```
Entrada (texto / JSON / código / log)
  -> JsonFilter   — remove campos irrelevantes (id, uuid, timestamps, metadata)
  -> CodeFilter   — remove comentários // e /* */
  -> TextFilter   — remove linhas [DEBUG] e [TRACE]
  -> SmartFilter  — elimina separadores e linhas duplicadas
Saída (60–97% menos tokens)
```

## CLI

```bash
# Comprimir texto ou arquivo
redux-token compress "seu texto"
redux-token compress --file input.log
cat big_output.log | redux-token compress

# Monitorar arquivo e comprimir ao salvar
redux-token watch arquivo.log

# Estimar custo
redux-token cost 10000 800 --price 0.003

# Ver economia acumulada (histórico, gráfico, breakdown por fonte/tipo)
redux-token gain --since 7d
redux-token session          # adoção por execução
redux-token discover         # oportunidades de otimização

# Diagnóstico das integrações (core, event log, hook, proxy, MCP)
redux-token doctor

# Limpar o store de compressão reversível (TTL / tamanho)
redux-token gc --ttl 24

# Sugerir versão de menor saída de um comando ruidoso
redux-token lean "git status"   # -> git status --short --branch

# Salvar snapshot de economia em REDUXTOKEN_STATS.md
redux-token report
```

## Filtros customizados

```python
import re
from redux_token import ReduxToken

def remove_urls(text: str) -> str:
    return re.sub(r'https?://\S+', '[url]', text)

def remove_emails(text: str) -> str:
    return re.sub(r'[\w.+-]+@[\w-]+\.\w+', '[email]', text)

rt = ReduxToken(extra_filters=[remove_urls, remove_emails])
compressed, stats = rt.compress(text)
```

## Compressão reversível (CCR)

Por padrão a compressão é destrutiva — o que é removido some. Com `reversible=True`, cada
trecho removido (comentários de código, blocos de log) é guardado num store local e
substituído por um marcador `⟦rdx:ref⟧` no lugar exato. Se o modelo precisar do detalhe,
ele **recupera sob demanda** apenas aquele trecho:

```python
from redux_token import ReduxToken, reversible

rt = ReduxToken(reversible=True)
compressed, stats = rt.compress(codigo_com_comentarios)
# compressed termina com um marcador, ex.: ⟦rdx:2814d23e2ead⟧

ref = reversible.find_refs(compressed)[0]
original = reversible.retrieve(ref)   # devolve o conteúdo original exato
```

Isso permite comprimir de forma bem mais agressiva sem medo de perder informação. O store
fica em `~/.redux-token/reversible/` (content-addressed, determinístico e local).

> No MCP, use a tool `retrieve` com o `ref`. Em modo proxy puro o marcador é apenas um
> sinal — a recuperação depende do agente ter acesso à tool `retrieve`.

## Proxy HTTP (transparente)

Intercepta requests para OpenAI/Claude e comprime automaticamente sem alterar o código da aplicação:

```bash
# Iniciar o proxy
cargo run --release --package redux-token-proxy

# Configurar a aplicação para usar o proxy
# Antes: https://api.openai.com/v1/chat/completions
# Depois: http://localhost:8080/openai/v1/chat/completions

# Ver estatísticas acumuladas
curl http://localhost:8080/_redux/stats
```

Configuração em `proxy.toml` (criado automaticamente com valores padrão).

## Hook para Claude Code

Com o projeto clonado, o hook já está ativo via `.claude/settings.json`. A cada saída
grande de Bash/Read/Grep/Glob, ele **mede e registra** quanto poderia ser economizado no
event log (fonte `hook`), alimentando `redux-token gain`/`discover`. Assim você enxerga o
volume de ruído que suas ferramentas produzem.

> Um hook `PostToolUse` roda **depois** que a saída já foi gerada, então ele não reduz o
> texto que já entrou no contexto — para compressão real-time do que vai ao modelo, use o
> **proxy HTTP** (que reescreve as mensagens no caminho da requisição).

Para projetos externos, adicione ao `.claude/settings.json`:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "python -m redux_token.hook" }]
      }
    ]
  }
}
```

## Hook PreToolUse (experimental)

Além de comprimir a saída (PostToolUse), o ReduxToken pode enxugar comandos ruidosos
**antes** de rodarem, trocando-os por variantes de menor saída (ex.: `git status` →
`git status --short --branch`). Escopo pequeno e conservador — só reescreve comandos
conhecidos e exatos.

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "python -m redux_token.prehook" }]
      }
    ]
  }
}
```

> Experimental: a troca efetiva depende de o Claude Code em uso suportar `updatedInput`
> no PreToolUse; caso contrário, é um no-op inofensivo. A lógica também está disponível
> via `redux-token lean "<comando>"`.

## MCP Server (Claude Desktop, Cursor, Zed, etc.)

Qualquer cliente que suporte o protocolo MCP pode usar o ReduxToken como ferramenta.

```bash
pip install redux-token
```

### Claude Desktop

Edite o arquivo de configuração:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "redux-token": {
      "command": "python",
      "args": ["-m", "redux_token.mcp"]
    }
  }
}
```

### Cursor / Zed / outros clientes MCP

```json
{
  "mcpServers": {
    "redux-token": {
      "command": "redux-token-mcp"
    }
  }
}
```

### Ferramentas disponíveis

| Ferramenta | O que faz |
|---|---|
| `compress` | Comprime texto — remove DEBUG, comentários, metadados JSON, duplicatas (opção `reversible`) |
| `compress_file` | Lê um arquivo do disco e comprime |
| `estimate_cost` | Calcula economia financeira dado o volume de tokens |
| `retrieve` | Recupera o original de um marcador `⟦rdx:ref⟧` (compressão reversível) |

## Instalação para desenvolvimento

Requer Rust + Python 3.10+.

```bash
git clone https://github.com/ElizioMartins/ReduxToken.git
cd ReduxToken
pip install maturin
maturin develop
python examples/basic.py
```

Veja [ARCHITECTURE.md](ARCHITECTURE.md) para decisões técnicas e [ROADMAP.md](ROADMAP.md) para o plano de desenvolvimento.

## Apoio

Se o ReduxToken te economizou tokens (e dinheiro), considere contribuir para manter o projeto:

- [GitHub Sponsors](https://github.com/sponsors/ElizioMartins)
- [Ko-fi](https://ko-fi.com/eliziomartins)
- PIX: `elizio.martins@hotmail.com`

## Licença

Apache 2.0

