Metadata-Version: 2.5
Name: fireplay-translation
Version: 0.2.1
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`；只有主模型返回 HTTP 429/RPM 限流时才切换到 `qwen3.8-flash`。收到限流后会短暂熔断主模型，避免在限流窗口内重复发送必然失败的请求。鉴权、超时和普通服务错误不会被备用模型隐藏。

## 安装

从公共 PyPI 安装：

```bash
pip install fireplay-translation
```

使用 uv：

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

包要求 Python 3.10 或更高版本。

## 同步调用

```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 所在地域覆盖此地址。
        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 等异步服务应复用原生异步客户端，避免阻塞事件循环：

```python
import os

from fireplay_translation import QwenConfig, create_async_qwen_translator


async def translate_once() -> str:
    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",
        )
        return result.text
```

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

## 路由语义

- `qwen-mt-flash` 成功时直接返回结果。
- 只有 HTTP 429 会触发 `qwen3.8-flash`。
- 限流熔断时间为 `max(Retry-After, rate_limit_cooldown_seconds)`，默认至少 60 秒。
- 主模型的非 429 错误原样返回。
- 主模型限流且备用模型失败时，`TranslationFallbackError` 保留两次异常。
- `TranslationResult` 暴露实际模型、是否兜底、兜底原因和上游 token 用量。

完整契约见 [Python 公共 API](docs/03-design/public-api.md) 和 [429 兜底决策](docs/04-decisions/ADR-20260914-rate-limit-fallback.md)。

## 扩展其他模型或供应商

同步后端实现 `TranslationBackend`，异步后端实现 `AsyncTranslationBackend`，再注入 `Translator` 或 `AsyncTranslator`：

```python
from fireplay_translation import Translator

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

架构和资源生命周期约定见 [翻译路由架构](docs/03-design/translation-architecture.md)。

## 开发

```bash
uv sync --frozen
uv run pytest
uv build
```

发布新版本前必须遵循 [公共 PyPI 发布手册](docs/06-operations/pypi-release.md)，不要从包含旧版本制品的 `dist/` 目录直接批量上传。

## 文档

[项目知识索引](docs/index.md) 是文档入口和权威地图。项目文档使用稳定 ID、生命周期状态和生成式清单管理。先把 `PROJECT_DOC_STEWARD_SKILL` 指向本机安装的 `project-doc-steward` 目录，再执行：

```bash
uv run "$PROJECT_DOC_STEWARD_SKILL/scripts/inventory_documents.py" . --sync-ai-policy
uv run "$PROJECT_DOC_STEWARD_SKILL/scripts/validate_metadata.py" . --check
```

## 分发与许可

- PyPI：[fireplay-translation](https://pypi.org/project/fireplay-translation/)
- 许可证元数据：`Proprietary`

在项目所有者明确授权前，不要假定公共 PyPI 分发等同于开放源码许可。
