Metadata-Version: 2.5
Name: jargon-engine
Version: 1.0.0
Summary: 行业黑话翻译引擎：把黑话翻译成接地气、搞笑、好懂的人话。面向中文互联网 + AI 行业新人，1万+词库，REST API 一键接入。
Project-URL: Homepage, https://github.com/HongMing-Huang/jargon-engine
Project-URL: Documentation, https://github.com/HongMing-Huang/jargon-engine#readme
Project-URL: Issues, https://github.com/HongMing-Huang/jargon-engine/issues
Project-URL: Changelog, https://github.com/HongMing-Huang/jargon-engine#更新日志
Author: renhuayixia
License: MIT
License-File: LICENSE
Keywords: chinese,glossary,jargon,slang,translation,词典,黑话
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Chinese (Simplified)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.9.0
Provides-Extra: api
Requires-Dist: fastapi>=0.115.0; extra == 'api'
Requires-Dist: uvicorn[standard]>=0.32.0; extra == 'api'
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Provides-Extra: llm
Requires-Dist: httpx>=0.27.0; extra == 'llm'
Description-Content-Type: text/markdown

<div align="center">
  <h1>jargon-engine · 行业黑话翻译引擎</h1>
  <p>把行业黑话翻译成接地气、搞笑、好懂的人话</p>
</div>

<p align="center">
  <a href="https://pypi.org/project/jargon-engine/"><img alt="PyPI" src="https://img.shields.io/pypi/v/jargon-engine?style=flat-square&label=PyPI"></a>
  <a href="https://github.com/HongMing-Huang/jargon-engine/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/HongMing-Huang/jargon-engine/ci.yml?style=flat-square&label=CI"></a>
  <a href="https://github.com/HongMing-Huang/jargon-engine/actions/workflows/publish.yml"><img alt="Publish" src="https://img.shields.io/github/actions/workflow/status/HongMing-Huang/jargon-engine/publish.yml?style=flat-square&label=Publish"></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/HongMing-Huang/jargon-engine?style=flat-square"></a>
  <img alt="Python" src="https://img.shields.io/pypi/pyversions/jargon-engine?style=flat-square">
  <img alt="Terms" src="https://img.shields.io/badge/词库-10,388-brightgreen?style=flat-square">
</p>

<p align="center">
  <img alt="translate" src="https://img.shields.io/badge/POST%20translate-4ms-success?style=flat-square">
  <img alt="lookup" src="https://img.shields.io/badge/GET%20lookup-0.7ms-success?style=flat-square">
  <img alt="search" src="https://img.shields.io/badge/GET%20search-1.9ms-success?style=flat-square">
</p>

---

## jargon-engine 是什么？

新人进一个行业，最懵的就是满屏黑话。**jargon-engine** 把「赋能业务、形成闭环、颗粒度对齐」翻译成人话——既给正经解释，也给带梗的搞笑版，还能整句重写。

它基于 **AC 自动机** 实现毫秒级匹配，内置 **10,388 条去重词条**，覆盖互联网 + AI 全行业 12 大分类。提供 Python SDK / REST API / CLI 三种接入方式，可独立部署，也可作为路由嵌入任意 FastAPI 项目。

```python
from jargon_engine import Engine

engine = Engine()
result = engine.translate("这个方案要赋能业务，形成闭环")
print(result.translated)
# 这个写满套路的PDF要给你装个外挂，让你干得更溜。，绕一圈回来，接头了，没断线。
```

---

## 特性

| 能力 | 说明 |
|------|------|
| 🚀 **毫秒级检索** | AC 自动机一次扫描匹配全部词条，万级词库 translate 仅 4ms |
| 🧠 **万级词库** | 10,388 条去重词条，12 大行业，生产管线持续扩充 |
| 😂 **三种风格** | `funny` 搞笑人话版 / `plain` 正经版 / `explain` 带例句详解 |
| 🔌 **三种接入** | Python SDK / REST API / CLI，任选其一 |
| 🧩 **可嵌入** | FastAPI 路由可 `include_router` 进任意现有项目 |
| 🛡️ **API 健壮** | Pydantic 校验、CORS、API Key 鉴权、统一错误处理、404/400/422 |
| ⚡ **高性能** | lookup O(1) 字典索引、search 预计算缓存 |
| 📦 **数据分离** | 引擎运行时与词库生产管线物理隔离，互不依赖 |

---

## 快速开始

### 安装

```bash
pip install jargon-engine            # SDK + CLI
pip install "jargon-engine[api]"     # 加上 REST API（FastAPI + uvicorn）
```

### Python SDK

```python
from jargon_engine import Engine

engine = Engine()
result = engine.translate("要赋能业务，形成闭环，注意颗粒度")

print(result.translated)   # 翻译后的人话
print(result.hits)         # 命中词条详情
print(result.elapsed_ms)   # 耗时（毫秒）
```

### REST API

```bash
jargon-engine serve --port 7861

curl -X POST http://localhost:7861/api/jargon/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"赋能业务形成闭环","style":"funny"}'
```

### CLI

```bash
jargon-engine translate "赋能业务形成闭环"
jargon-engine lookup "赋能"
jargon-engine stats
jargon-engine serve --port 7861
```

---

## REST API

### 端点总览

| 方法 | 路径 | 功能 | 状态码 |
|------|------|------|--------|
| GET | `/api/health` | 健康检查（免鉴权） | 200 |
| GET | `/api/jargon/translate/health` | 子路由健康 | 200 |
| POST | `/api/jargon/translate` | 整段黑话 → 人话 | 200 / 400 / 422 |
| GET | `/api/jargon/terms/{word}` | 单个词条详情 | 200 / 404 |
| GET | `/api/jargon/search` | 模糊搜索词库 | 200 / 422 |
| GET | `/api/jargon/stats` | 词库统计 | 200 |

### 鉴权

设置环境变量 `JARGON_API_KEY` 后，所有 `/api/jargon/*` 端点需携带请求头：

```
X-API-Key: <你的key>
# 或
Authorization: Bearer <你的key>
```

未设置该变量时不启用鉴权（开发模式）。`/api/health` 始终免鉴权，供负载均衡探活。

### POST /api/jargon/translate

**请求体**：

| 字段 | 类型 | 必填 | 默认 | 说明 |
|------|------|------|------|------|
| `text` | string | 是 | - | 待翻译文本，长度 ≥ 1 |
| `style` | string | 否 | `funny` | `funny` / `plain` / `explain` |
| `industry` | string | 否 | `null` | 限定行业；支持别名 `developer`→`tech` |
| `llm_polish` | bool | 否 | `false` | 是否 LLM 润色（需注入润色器） |
| `include_untracked` | bool | 否 | `false` | 是否返回未收录候选词 |

**响应**（毫秒级）：

```json
{
  "ok": true,
  "original": "这个方案要赋能业务，形成闭环",
  "translated": "这个写满套路的PDF要给你装个外挂，让你干得更溜",
  "hits": [
    {
      "word": "赋能",
      "plain": "为个人或组织提供能力或条件",
      "funny": "给你装个外挂，让你干得更溜",
      "industry": "internet",
      "example": "我们要赋能一线团队 → 给他们工具和权限，让他们自己飞",
      "aliases": ["加持", "赋能业务", "持续赋能"]
    }
  ],
  "untracked": [],
  "stats": {
    "total_terms": 10388,
    "matched": 2,
    "elapsed_ms": 4.1,
    "mode": "dictionary"
  }
}
```

### GET /api/jargon/search

```bash
curl "http://localhost:7861/api/jargon/search?q=agent&industry=ai&limit=10"
```

| 参数 | 类型 | 默认 | 约束 |
|------|------|------|------|
| `q` | string | `""` | 关键字 |
| `industry` | string | - | 合法行业 |
| `limit` | int | 20 | 1-100 |

### 错误处理

所有错误统一 JSON 格式：

| 状态码 | 场景 | 响应 |
|--------|------|------|
| 400 | `industry` 不存在 | `{"detail": "未知的 industry: xyz..."}` |
| 401 | API Key 无效 | `{"detail": "无效或缺失的 API Key"}` |
| 404 | 词条不存在 | `{"detail": "词条 xxx 不存在"}` |
| 422 | 参数校验失败 | `{"detail": [{"loc": [...], "msg": "..."}]}` |
| 500 | 内部错误 | `{"ok": false, "error": "内部服务错误"}` |

---

## Python SDK

```python
from jargon_engine import Engine

engine = Engine()                          # 内置词库
engine = Engine(extra_tsv_dir="./my")      # 合并自定义词库

result = engine.translate(
    "赋能业务，形成闭环",
    style="funny",           # funny / plain / explain
    industry=None,           # None=全部，或指定行业
    llm_polish=False,
    include_untracked=False,
)

engine.lookup("赋能")         # O(1) 查词
engine.search("agent", industry="ai", limit=10)  # 模糊搜索
engine.stats()                # {"total": int, "by_industry": dict}
```

### 注入 LLM 润色器

```python
def my_polish(text: str, hits: list) -> str | None:
    # 调用任意 LLM 返回润色整句；返回 None 则保留词典模式结果
    ...

engine = Engine(llm_polish=my_polish)
engine.translate("...", llm_polish=True)
```

---

## 词库

词库以 TSV 存储在 `data/seed/`，每行一条，按行业分文件。**加词 = 加一行**，PR 合并即可，git diff 友好。

| 字段 | 说明 |
|------|------|
| `word` | 主词 |
| `industry` | 所属行业 id |
| `aliases` | 别名（分号分隔，匹配时一并命中） |
| `plain` | 正经解释 |
| `funny` | 搞笑人话版 |
| `example` | 例句对比（黑话 → 人话） |
| `weight` | 匹配权重（越大越优先） |
| `source` | 来源（数据归属追溯） |

### 行业分类

单一事实来源在 `src/jargon_engine/industries.py`，新增行业只需在此登记。

| id | 名称 | id | 名称 |
|----|------|----|------|
| `internet` | 互联网通用 | `marketing` | 市场与增长 |
| `product` | 产品 | `operations` | 运营 |
| `tech` | 技术 | `design` | 设计与体验 |
| `ai` | AI 与大模型 | `finance` | 商业与投融资 |
| `data` | 数据 | `workplace` | 职场与管理 |
| `hr` | 人力资源 | `ecommerce` | 电商与零售 |

别名：`developer` → `tech`。

---

## 架构

```
┌─────────────────────────────────────────────┐
│            API 层（FastAPI）                 │
│  app.py · deps.py · cli.py                  │
│  Pydantic 校验 · CORS · API Key · 错误兜底  │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│            Engine（引擎入口）                │
│  加载词库 → 构建索引 → 翻译/查词/搜索        │
│  O(1) lookup · 预计算 search · 行业 resolve │
└──────┬──────────────────┬───────────────────┘
       │                  │
┌──────▼──────┐  ┌────────▼────────┐
│ Translator  │  │    Matcher      │
│ 词典命中→   │◄─│ AC 自动机       │
│ 语境重组→   │  │ 最长优先·fail链 │
│ LLM 润色    │  │ 行业过滤·去重叠 │
└─────────────┘  └─────────────────┘
       │                  │
┌──────▼──────────────────▼───────────────────┐
│        Store · Models · Industries          │
│  TSV 加载 · merge 合并 · Pydantic v2        │
└─────────────────────────────────────────────┘

词库生产管线（独立组件，与引擎运行时隔离）：
┌─────────────────────────────────────────────┐
│            tools/pipeline/                  │
│  expand_wordlists · llm_generate · merge    │
│  validate · import/*（外部数据源）          │
└─────────────────────────────────────────────┘
```

**关键设计**：

- **引擎与生产管线分离**：`src/jargon_engine/` 是运行时（打进 wheel），`tools/pipeline/` 是离线词库生产（不打包），两者无共享执行环境
- **启动时建索引**：加载词库 + AC 自动机 + dict 索引 + search 缓存，一次构建反复用
- **Engine 单例**：`lru_cache` 避免每请求重建
- **无状态抓取**：生产管线不生成/存储完成状态指标，仅读已有输出续跑

---

## 词库生产管线

万级词库靠管线生产，位于 `tools/pipeline/`（与引擎运行时物理隔离）：

```
合并开源词表（MIT/CC BY-SA 来源）
    ↓
LLM 扩充行业词单（expand_wordlists.py）
    ↓
LLM 批量生成释义（llm_generate.py：funny/plain/example/aliases）
    ↓
合并去重（merge.py）+ 校验（validate.py）
    ↓
人工审校 + 社区共建（PR 持续加词）
```

```bash
python tools/pipeline/validate.py data/seed/*.tsv
python tools/pipeline/merge.py --sources a.tsv b.tsv --out merged.tsv
python tools/pipeline/expand_wordlists.py \
  --wordlist tools/pipeline/import/wordlists/ai.txt --industry ai --target 900 \
  --out tools/pipeline/import/wordlists/ai.txt
python tools/pipeline/llm_generate.py \
  --wordlist tools/pipeline/import/wordlists/ai.txt --industry ai \
  --out data/seed/ai_generated.tsv
```

需配置 `DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL` / `DEEPSEEK_MODEL`。外部数据来源见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

---

## 配置

| 变量 | 默认 | 说明 |
|------|------|------|
| `JARGON_API_KEY` | - | API Key 鉴权，未设置则不启用 |
| `JARGON_CORS_ORIGINS` | `*` | 允许的跨域来源，逗号分隔；生产请收紧 |
| `JARGON_EXTRA_TSV_DIR` | - | 额外 TSV 词库目录，合并到内置词库 |
| `DEEPSEEK_API_KEY` | - | 词库生产管线用，引擎运行不需要 |

---

## 部署

### 独立部署

```bash
pip install "jargon-engine[api]"
JARGON_API_KEY=your-secret jargon-engine serve --host 0.0.0.0 --port 7861
```

### 嵌入现有 FastAPI 项目

```python
from fastapi import FastAPI
from jargon_engine.api.app import create_router

app = FastAPI()
app.include_router(create_router(), prefix="/api/jargon")
```

### 生产建议

- `uvicorn jargon_engine.api.app:create_app --factory --workers 4` 多进程
- Nginx 反向代理做 TLS、限流、缓存
- 收紧 `JARGON_CORS_ORIGINS` 为实际前端域名
- 启用 `JARGON_API_KEY` 防止 `llm_polish` 被滥用产生 LLM 费用

---

## 开发

```bash
pip install -e ".[dev,api]"
pytest                 # 46 用例
ruff check .           # lint
jargon-engine serve --port 7861   # 开发服务
```

---

## 路线图

| 里程碑 | 状态 | 内容 |
|--------|------|------|
| **v0.1 基础引擎** | ✅ 已发布 | AC 自动机匹配、词典翻译、REST API、CLI、12 大行业 |
| **v1.0 工程化** | ✅ 已发布 | API 规范化（Pydantic/CORS/鉴权/错误处理）、O(1) 索引、测试覆盖、CI/CD、引擎与生产管线分离 |
| **v1.1 生态** | 🚧 进行中 | PyPI 发布、Docker 部署、前端接入、更多行业（法律/教育/医疗） |
| **v2.0 国际化** | 📋 规划中 | 英文社区支持、中英双向翻译、多语言释义 |
| **v2.x 智能化** | 📋 规划中 | LLM 润色内置、分词改进、SQLite FTS5 倒排、词条贡献后台 |

### 近期 TODO

- 补 translator LLM 润色分支与 CLI 的集成测试
- 加 pre-commit hook（ruff + pytest）
- Dockerfile 与 docker-compose 示例
- 词库去重审计：跨文件同义词统一 aliases

---

## 贡献

1. Fork 仓库并拉取分支
2. 加词：在 `data/seed/<行业>.tsv` 追加一行，跑 `python tools/pipeline/validate.py data/seed/*.tsv` 校验
3. 加行业：在 `src/jargon_engine/industries.py` 的 `INDUSTRIES` 登记
4. 改代码：跑 `pytest` 与 `ruff check .` 确保通过
5. 提 PR，描述变更与动机

词库贡献请确保 `funny` 版接地气、不生硬、不冒犯；外部数据来源请在 `THIRD_PARTY_NOTICES.md` 登记版权。

---

## 许可证

[MIT](LICENSE) — Copyright © 2026 renhuayixia

本项目基于 MIT 协议开源，**允许任意改造、二次开发、商用**，但必须在衍生项目中保留原作者版权声明与许可声明。词库数据来源及版权见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
