Metadata-Version: 2.4
Name: soulshell-base
Version: 0.3.1
Summary: 统一的多云服务聚合包，提供 ASR（语音识别）、TTS（语音合成）、OSS（对象存储）、RAG（检索增强生成）服务
Author: SoulShell Maintainers
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: python-dotenv>=0.19.0
Provides-Extra: aliyun
Requires-Dist: alibabacloud-nls-python-sdk>=1.0.2; extra == 'aliyun'
Requires-Dist: alibabacloud-oss-v2>=1.1.0; extra == 'aliyun'
Requires-Dist: sounddevice>=0.4.0; extra == 'aliyun'
Requires-Dist: websockets>=14.0; extra == 'aliyun'
Provides-Extra: all
Requires-Dist: aiohttp>=3.8.0; extra == 'all'
Requires-Dist: alibabacloud-nls-python-sdk>=1.0.2; extra == 'all'
Requires-Dist: alibabacloud-oss-v2>=1.1.0; extra == 'all'
Requires-Dist: azure-cognitiveservices-speech>=1.30.0; extra == 'all'
Requires-Dist: httpx>=0.23.0; extra == 'all'
Requires-Dist: numpy>=1.24.0; extra == 'all'
Requires-Dist: python-dotenv>=0.19.0; extra == 'all'
Requires-Dist: sounddevice>=0.4.0; extra == 'all'
Requires-Dist: websocket-client>=1.9.0; extra == 'all'
Requires-Dist: websockets>=14.0; extra == 'all'
Provides-Extra: asr-aliyun
Requires-Dist: alibabacloud-nls-python-sdk>=1.0.2; extra == 'asr-aliyun'
Requires-Dist: sounddevice>=0.4.0; extra == 'asr-aliyun'
Requires-Dist: websockets>=14.0; extra == 'asr-aliyun'
Provides-Extra: asr-all
Requires-Dist: aiohttp>=3.8.0; extra == 'asr-all'
Requires-Dist: alibabacloud-nls-python-sdk>=1.0.2; extra == 'asr-all'
Requires-Dist: numpy>=1.24.0; extra == 'asr-all'
Requires-Dist: sounddevice>=0.4.0; extra == 'asr-all'
Requires-Dist: websocket-client>=1.9.0; extra == 'asr-all'
Requires-Dist: websockets>=14.0; extra == 'asr-all'
Provides-Extra: asr-volcengine
Requires-Dist: aiohttp>=3.8.0; extra == 'asr-volcengine'
Requires-Dist: aiosignal>=1.4.0; extra == 'asr-volcengine'
Requires-Dist: frozenlist>=1.8.0; extra == 'asr-volcengine'
Requires-Dist: websockets>=14.0; extra == 'asr-volcengine'
Provides-Extra: asr-xunfei
Requires-Dist: numpy>=1.24.0; extra == 'asr-xunfei'
Requires-Dist: sounddevice>=0.4.0; extra == 'asr-xunfei'
Requires-Dist: websocket-client>=1.9.0; extra == 'asr-xunfei'
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=4.3.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: python-dotenv>=0.19.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: oss-aliyun
Requires-Dist: alibabacloud-oss-v2>=1.1.0; extra == 'oss-aliyun'
Provides-Extra: oss-all
Requires-Dist: alibabacloud-oss-v2>=1.1.0; extra == 'oss-all'
Provides-Extra: rag-all
Requires-Dist: httpx>=0.23.0; extra == 'rag-all'
Provides-Extra: rag-ragflow
Requires-Dist: httpx>=0.23.0; extra == 'rag-ragflow'
Provides-Extra: tts-aliyun
Requires-Dist: alibabacloud-nls-python-sdk>=1.0.2; extra == 'tts-aliyun'
Provides-Extra: tts-all
Requires-Dist: alibabacloud-nls-python-sdk>=1.0.2; extra == 'tts-all'
Requires-Dist: azure-cognitiveservices-speech>=1.30.0; extra == 'tts-all'
Requires-Dist: httpx>=0.23.0; extra == 'tts-all'
Requires-Dist: websocket-client>=1.9.0; extra == 'tts-all'
Requires-Dist: websockets>=14.0; extra == 'tts-all'
Provides-Extra: tts-azure
Requires-Dist: azure-cognitiveservices-speech>=1.30.0; extra == 'tts-azure'
Provides-Extra: tts-volcengine-v1
Requires-Dist: httpx>=0.23.0; extra == 'tts-volcengine-v1'
Requires-Dist: websockets>=14.0; extra == 'tts-volcengine-v1'
Provides-Extra: tts-volcengine-v3
Requires-Dist: websockets>=14.0; extra == 'tts-volcengine-v3'
Provides-Extra: tts-xunfei
Requires-Dist: websocket-client>=1.9.0; extra == 'tts-xunfei'
Description-Content-Type: text/markdown

# SoulShell-Base

服务聚合项目，面向需要同时接入多家云服务的 Python 应用，提供统一的 ASR（语音识别）、TTS（语音合成）、OSS（对象存储）和 RAG（检索增强生成）接口。

[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
![License](https://img.shields.io/badge/license-MIT-green.svg)

## 项目特性

- **统一契约**：通过工厂、请求模型、响应模型和异常类型收敛不同 Provider 的接入差异。
- **按需依赖**：核心包保持轻量，云厂商 SDK 通过 extras 分组按需安装。
- **异步优先**：ASR、TTS、OSS、RAG 的核心能力围绕 async/await 设计，便于接入服务端链路。
- **配置灵活**：支持字典参数、环境变量占位符和配置文件组合使用。
- **CLI 可用**：内置 ASR 批量识别、TTS 批量合成和唤醒词音频生成命令。
- **发布友好**：打包配置只发布运行时需要的源码、许可证、变更记录和项目入口文档。

## 环境要求

- Python 3.10+
- uv（推荐用于本地开发和验证）

## 安装

基础安装：

```bash
pip install soulshell-base
```

安装指定能力：

```bash
# TTS
pip install "soulshell-base[tts-azure]"
pip install "soulshell-base[tts-aliyun]"
pip install "soulshell-base[tts-volcengine-v1]"
pip install "soulshell-base[tts-volcengine-v3]"
pip install "soulshell-base[tts-xunfei]"
pip install "soulshell-base[tts-all]"

# ASR
pip install "soulshell-base[asr-volcengine]"
pip install "soulshell-base[asr-aliyun]"
pip install "soulshell-base[asr-xunfei]"
pip install "soulshell-base[asr-all]"

# OSS / RAG / 跨模块能力
pip install "soulshell-base[oss-aliyun]"
pip install "soulshell-base[oss-all]"
pip install "soulshell-base[rag-ragflow]"
pip install "soulshell-base[rag-all]"
pip install "soulshell-base[aliyun]"
pip install "soulshell-base[all]"
```

本地开发安装：

```bash
uv sync --extra dev
```

## 模块概览

| 模块 | 导入入口 | 主要能力 | Provider |
|------|----------|----------|----------|
| TTS | `soulshell_base.tts` | 文本转语音、音色参数、批量合成支撑 | Azure、阿里云、火山引擎、讯飞 |
| ASR | `soulshell_base.asr` | 音频识别、识别结果封装、批量测试支撑 | 火山引擎、阿里云、讯飞 |
| OSS | `soulshell_base.oss` | 文件上传、分片上传、元数据和访问 URL | 阿里云 OSS |
| RAG | `soulshell_base.rag` | 数据集、助理、会话、检索和对话 | RagFlow |
| Cache | `soulshell_base.cache` | 本地缓存区域、索引和原子写入 | 本地文件系统 |
| Core | `soulshell_base.core` | 日志、重试、工具函数和运行时状态 | 通用能力 |

## 快速示例

### TTS

```python
import asyncio

from soulshell_base.tts import TTSFactory, TTSSynthesizeRequest


async def main() -> None:
    tts = TTSFactory.create(
        provider_name="azure",
        api_key="your_api_key",
        endpoint="https://example.cognitiveservices.azure.com",
    )
    request = TTSSynthesizeRequest(
        text="你好世界",
        voice_id="zh-CN-XiaoxiaoNeural",
    )
    response = await tts.synthesize(request)
    print(response)


asyncio.run(main())
```

### ASR

```python
import asyncio

from soulshell_base.asr import ASRFactory, ASRRecognizeRequest, AudioFormat


async def main(audio_bytes: bytes) -> None:
    asr = ASRFactory.create(
        provider_name="volcengine",
        token="your_token",
        appid="your_appid",
    )
    request = ASRRecognizeRequest(
        audio_data=audio_bytes,
        language="zh-CN",
        audio_format=AudioFormat.WAV,
    )
    response = await asr.recognize(request)
    print(response)


asyncio.run(main(audio_bytes=b"..."))
```

### Core

```python
from soulshell_base.core import async_retry, get_logger

logger = get_logger(__name__)


@async_retry(max_attempts=3, delay=1.0)
async def call_remote_service() -> None:
    logger.info("calling remote service")
```

## 配置约定

Provider 支持直接传入参数，也可配合 JSON 配置和环境变量占位符使用。常见占位符格式：

```text
${VAR_NAME}
${VAR_NAME:default_value}
```

示例配置：

```json
{
  "provider_name": "azure",
  "api_key": "${AZURE_API_KEY}",
  "endpoint": "${AZURE_ENDPOINT}",
  "voice_id": "${AZURE_VOICE_ID:zh-CN-XiaoxiaoNeural}",
  "encoding": "wav",
  "sample_rate": 16000
}
```

## CLI

安装后提供以下命令：

```bash
soulshell-asr --help
soulshell-tts --help
soulshell-tts-wakegen --help
```

也可以使用模块方式调用：

```bash
python -m soulshell_base.cli.asr --help
python -m soulshell_base.cli.tts --help
python -m soulshell_base.cli.tts_wakegen --help
```

## 开发与验证

常用本地验证命令：

```bash
uv sync --extra dev
uv run --extra dev pytest test/test_packaging_metadata.py -q
uv run ruff check src test
```

涉及真实云服务的集成路径需要先配置对应环境变量；没有明确需要时，优先运行不触网的契约测试和元数据测试。

## 贡献

1. 创建特性分支。
2. 保持改动范围聚焦，并遵循现有模块边界。
3. 补充或更新对应测试与文档。
4. 确认发布元数据测试和必要验证通过。
5. 提交 Pull Request。

## 许可证

MIT License。
