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

# fireplay-translation

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

## 安装与使用

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

```bash
uv build
pip install fireplay-translation
```

```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)
```

异步服务（FastAPI、Starlette、aiohttp 等）使用原生 `httpx.AsyncClient`，不会阻塞事件循环：

```python
import os

from fireplay_translation import QwenConfig, create_async_qwen_translator


async def main() -> None:
    async with create_async_qwen_translator(
        QwenConfig(api_key=os.environ["DASHSCOPE_API_KEY"])
    ) as translator:
        result = await translator.translate(
            "Hello, world",
            source_language="auto",
            target_language="zh-CN",
        )
        print(result.text)
```

长生命周期 Web 服务应在启动时创建一个异步 translator，在应用关闭时调用
`await translator.aclose()`，以复用连接池并正确释放资源。

## 路由语义

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

## 扩展其他模型或厂商

同步后端实现 `TranslationBackend`，异步后端实现 `AsyncTranslationBackend`；分别注入
`Translator` 或 `AsyncTranslator` 即可，业务项目无需了解供应商协议：

```python
from fireplay_translation import Translator

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

异步扩展的 `translate(TranslationRequest)` 方法定义为 `async def`，路由调用方式为
`await translator.translate(...)`。

发布前建议依次执行：

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

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

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