# tokencompress

本地、零云依赖的 token / 文本压缩工具包。把冗长 prompt、日志、长文压短，**省 token、省钱、不联网**。

- 纯 Python，无强制依赖（可选 `tiktoken` 做精确 GPT 计数）
- 四种形态随便挑：MCP 服务 / HTTP API / CLI / 当库导入
- 离线规则压缩 + 可选本地 Ollama 语义压缩 + gzip 无损打包
- 智能自动压缩：短输入原样放行，代码块/URL/JSON 自动豁免，只压正文

![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)

## English

**tokencompress** is a local, zero-cloud token & text compression toolkit for LLM prompts, context windows, and log/transport volume.

- 🔒 **100% local** — no API keys, no network calls. Rules & lossless run fully offline; semantic mode only talks to a local Ollama.
- 🧩 **Four interfaces** — MCP server, HTTP API, CLI, and importable Python library.
- 🌏 **Bilingual** — first-class Chinese + English filler/stop-word removal and phrase abbreviation.
- 🤖 **Smart auto-compress** — short inputs pass through untouched; code blocks, URLs, and JSON are auto-exempt; only prose gets compressed.
- 📦 **Lossless mode** — gzip + base64 packing for logs/transport, fully reversible.

**Keywords:** token compression, prompt compression, LLM context, local-first, privacy, MCP, CLI, Chinese NLP, text compression, Ollama.

---

## 安装

```bash
cd tokcompress
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
```

> 没有自带 venv。按上面“安装”步骤建 `.venv` 即可；或 `pip install .` 后直接用系统 `python3`。

---

## 最简单的用法

### 1) 当库导入（推荐给写代码的人）

```python
from tokencompress import compress, auto_compress, measure

# 手动压
r = compress("你的长文本……", method="rules")
print(r["compressed"])            # 压缩后的文本
print(r["metrics"]["token_ratio"])  # 0.71 表示省了约 29% token

# 智能自动压：短的不动，长的才压
out = auto_compress("你的长文本……")["compressed"]
```

### 2) 命令行（CLI）

```bash
# 压一段文字
python -m tokencompress compress "你的长文本……"

# 从管道读（最常用）
cat long_prompt.txt | python -m tokencompress autocompress -

# 只算 token 数
python -m tokencompress measure "你的长文本……"
```

### 3) `tca` 包装脚本（一行管道，最简）

```bash
# 压缩剪贴板
pbpaste | ./bin/tca

# 压缩文件
cat long_prompt.txt | ./bin/tca

# 自定义触发阈值（token 数，低于此值原样放行）
echo "很长的文本……" | ./bin/tca --threshold 300
```

可选：把下面这行加进 `~/.zshrc`，之后任意位置都能用 `tca`：

```bash
alias tca="$HOME/path/to/tokencompress/bin/tca"   # 替换成你的实际路径
```

### 4) HTTP 服务（给别的程序调用）

```bash
python -m tokencompress serve --port 8787
```

```bash
curl -s -X POST localhost:8787/compress \
  -H 'Content-Type: application/json' \
  -d '{"text":"你的长文本……","method":"rules"}'
```

端点：`/health` `/strategies` `/backends` `/measure` `/compress` `/decompress` `/autocompress`

### 5) 接入 WorkBuddy（MCP）

把 `examples/mcp_config.json` 的内容加进 `~/.workbuddy/mcp.json` 的 `mcpServers`，
重启 WorkBuddy 后，对话里就能直接让模型调用 `compress_text` / `auto_compress_text` 等工具。

---

## 压缩方法

| method | 说明 | 是否可逆 | 依赖 |
|--------|------|----------|------|
| `rules` | 离线规则流水线：去空白/去重/去填充词/短语缩写 | 否（有损但语义保留） | 无 |
| `semantic` | 本地 Ollama 模型做语义压缩 | 否 | 本机 Ollama |
| `both` | 先 rules 再语义 | 否 | 本机 Ollama（无则回退 rules） |
| `lossless` | gzip + base64 打包，用于日志/传输 | **是** | 无 |

`rules` 流水线顺序：`whitespace → dedup → filler → abbreviate → truncate`
可用 `compress(text, strategies_list=[...])` 指定只跑其中几步。

---

## 真实压缩率（本机实测）

### 案例 1：中英混合 prompt（method=`rules`）

> 输入：*“我们需要因为时间成本的原因去写一个用于短视频生成的提示词，for example 我们可以这样描述：given a topic，in order to 让模型生成一段画面。actually 要注意避免图像畸变这个问题，basically 这个细节很重要，also 要让画面保持稳定。”*

| 指标 | 压缩前 | 压缩后 | 比率 |
|------|--------|--------|------|
| tokens（离线估算） | 128 | 92 | **0.719** |
| bytes | 301 | 261 | 0.867 |

命中的规则：`filler`（去掉 actually/basically/also）、`abbreviate`（for example→e.g.、in order to→to）

> 输出：*“我们需要因为时间成本的原因去写一个用于短视频生成的提示词，e.g. 我们可以这样描述：given a topic，to 让模型生成一段画面。 要注意避免图像畸变这个问题， 这个细节很重要， 要让画面保持稳定”*

### 案例 2：重复日志（method=`lossless`）

> 输入：50 行相同的 `INFO ... worker-7 processed batch id=8821 items=64 ok`

| 指标 | 压缩前 | 压缩后 | 比率 |
|------|--------|--------|------|
| bytes | 3050 | 144 | **0.047** |

可逆：解压后与原文逐字节一致 ✓（适合日志归档/网络传输）

### 案例 3：智能自动压缩（auto_compress）

- 短输入（≤ 500 token，可配 `--threshold`）：**原样放行**，绝不误伤指令
- 长输入（上面案例 1 重复 6 遍）：自动压缩，`token_ratio ≈ 0.717`
- 代码块（``` ``` ```）、URL、文件路径、JSON 行：**永远不压**

---

## 常见问题

**token 数是怎么算的？** 离线估算：CJK ≈ 1 token/字符，拉丁文 ≈ 1 token/4 字符。
装了 `tiktoken` 后 `measure(text, model="gpt-4o")` 可拿到精确 GPT 计数。

**会把我数据发到云端吗？** 不会。`rules` / `lossless` 完全本地。`semantic` 只连本机
`http://localhost:11434`（Ollama），不联网、不经过任何第三方。

**装了 Ollama 怎么启用语义压缩？** 拉一个小模型（如 `qwen2.5:3b`），`list_backends()`
会显示 `ollama: available`。之后 `compress(text, method="semantic")` 即可。

---

## 文件结构

```
tokcompress/
├── tokencompress/        # 包本体
│   ├── __init__.py       # 导出 compress / measure / decompress / auto_compress ...
│   ├── core.py           # 统一入口
│   ├── strategies.py     # 规则流水线 + 无损打包 + 语义压缩
│   ├── tokenizer.py      # token 估算 / 后端探测
│   ├── cli.py            # 命令行
│   ├── http_server.py    # HTTP API
│   └── mcp_server.py     # MCP 服务
├── bin/tca               # 一键自动压缩包装脚本
├── examples/             # mcp_config.json / usage.md
└── requirements.txt
```