Metadata-Version: 2.5
Name: fireplay-translation
Version: 0.1.0
Summary: Extensible translation routing with rate-limit fallback
License: Proprietary
Requires-Python: >=3.10
Requires-Dist: requests>=2.32
Description-Content-Type: text/markdown

# fireplay-translation

公司内部可复用的 Python 翻译路由包。调用方只依赖 `Translator` 接口；默认实现以
`qwen-mt-flash` 为主模型，仅在主模型返回 429/RPM 限流时使用
`qwen3.8-flash`，并短暂熔断主模型，避免限流期间反复发送必然失败的请求。

## 安装与使用

从公司包仓安装构建后的 wheel，或在源码仓内执行：

```bash
uv build
pip install dist/fireplay_translation-0.1.0-py3-none-any.whl
```

```python
import os

from fireplay_translation import QwenConfig, create_qwen_translator

translator = create_qwen_translator(
    QwenConfig(
        api_key=os.environ["DASHSCOPE_API_KEY"],
        # 推荐换成与 API Key 同地域的 Model Studio 工作空间地址。
        base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    )
)

result = translator.translate(
    "Hello, world",
    source_language="auto",
    target_language="zh-CN",
)
print(result.text)
print(result.model, result.fallback_used)
```

## 路由语义

- `qwen-mt-flash` 正常、超时、鉴权错误或服务异常时，错误原样返回，不静默换模型。
- 只有 429 限流会触发 `qwen3.8-flash`，因此调用方能区分容量问题和配置/服务故障。
- 收到 429 后按 `max(Retry-After, rate_limit_cooldown_seconds)` 暂停主路由，默认 60 秒。
- Qwen3.8 回退请求关闭 thinking，并要求只返回译文。
- `TranslationResult.fallback_used`、`model` 和 token 字段可用于监控成本与回退率。

## 扩展其他模型或厂商

实现一个带 `model` 属性和 `translate(TranslationRequest)` 方法的
`TranslationBackend`，再注入 `Translator` 即可；业务项目无需了解供应商协议：

```python
from fireplay_translation import Translator

translator = Translator(
    MyPrimaryBackend(...),
    rate_limit_fallback=MyFallbackBackend(...),
)
```

发布前建议依次执行：

```bash
uv run pytest
uv build
```

发布到公司包仓后，业务项目按普通版本依赖安装：

```bash
uv add fireplay-translation
```
