Metadata-Version: 2.4
Name: oiiai-lib
Version: 0.0.3
Summary: A minimalist Python package scaffolded with uv
Project-URL: Homepage, https://github.com/weisiren000/oiiai
Project-URL: Repository, https://github.com/weisiren000/oiiai
Project-URL: Documentation, https://github.com/weisiren000/oiiai
Project-URL: Issues, https://github.com/weisiren000/oiiai/issues
Author-email: Chen Xuanyi <cxyvsir04@qq.com>
Maintainer-email: Chen Xuanyi <cxyvsir04@qq.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.8
Requires-Dist: brotli>=1.2.0
Requires-Dist: requests>=2.25.0
Requires-Dist: sniffio>=1.3.1
Requires-Dist: zhipuai>=2.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# oiiai

[![PyPI version](https://img.shields.io/pypi/v/oiiai-lib.svg)](https://pypi.org/project/oiiai-lib/)
[![Python versions](https://img.shields.io/pypi/pyversions/oiiai-lib.svg)](https://pypi.org/project/oiiai-lib/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

oiiai 是一个简单的 AI 模型调用工具包，提供模型列表获取和模型调用功能。

## 特性

- 🚀 支持多个 AI 提供商的模型列表获取
- 📦 统一的 API 接口
- 🛠️ 简单易用的设计
- 🔧 可扩展的架构
- 📝 统一的日志记录系统（支持 JSON 格式和异步日志）

## 支持的提供商

| 提供商 | 模型获取 | 说明 |
|--------|----------|------|
| 智谱 AI | ✅ FetchZhipu | 从官方文档页面解析模型列表 |
| OpenRouter | ✅ FetchOpenRouter | 通过 API 获取模型列表 |
| ModelScope | ✅ FetchModelScope | 通过 API 获取模型列表 |
| SiliconFlow | ✅ FetchSiliconFlow | 通过 API 获取模型列表 |
| IFlow | ✅ FetchIFlow | 通过 API 获取模型列表 |

## 安装

### 使用 pip

```bash
pip install oiiai-lib
```

### 使用 uv

```bash
uv add oiiai-lib
```

## 快速开始

```python
from oiiai import (
    FetchZhipu,
    FetchOpenRouter,
    FetchModelScope,
    FetchSiliconFlow,
    FetchIFlow,
)

# 获取可用模型列表

# 从智谱 AI 获取模型列表
zhipu_fetcher = FetchZhipu()

zhipu_models = zhipu_fetcher.fetch_models()
print(f"智谱 AI 可用模型: {len(zhipu_models)} 个")

# 从 OpenRouter 获取模型列表
openrouter_fetcher = FetchOpenRouter(api_key="your-api-key")

openrouter_models = openrouter_fetcher.fetch_models()
print(f"OpenRouter 可用模型: {len(openrouter_models)} 个")

# 从 ModelScope 获取模型列表
modelscope_fetcher = FetchModelScope()

modelscope_models = modelscope_fetcher.fetch_models()
print(f"ModelScope 可用模型: {len(modelscope_models)} 个")

# 从 SiliconFlow 获取模型列表
siliconflow_fetcher = FetchSiliconFlow()

siliconflow_models = siliconflow_fetcher.fetch_models()
print(f"SiliconFlow 可用模型: {len(siliconflow_models)} 个")

# 从 IFlow 获取模型列表
iflow_fetcher = FetchIFlow()

iflow_models = iflow_fetcher.fetch_models()
print(f"IFlow 可用模型: {len(iflow_models)} 个")
```

## API 参考

### 基类 FetchBase

所有模型获取器的抽象基类。

```python
from oiiai import FetchBase

class MyFetcher(FetchBase):
    @property
    def provider(self) -> str:
        return "my_provider"
    
    def fetch_models(self) -> List[str]:
        # 实现获取逻辑
        return ["model-1", "model-2"]
```

### FetchOpenRouter

从 OpenRouter API 获取模型列表。

```python
from oiiai import FetchOpenRouter

# 使用 API Key（可选，不传则从环境变量 OPENROUTER_API_KEY 获取）
fetcher = FetchOpenRouter(api_key="your-api-key")

# 获取模型列表
models = fetcher.fetch_models()
print(models)  # ['openai/gpt-4o', 'anthropic/claude-3-opus', ...]
```

### FetchZhipu

从智谱 AI 官方文档页面解析模型列表。

```python
from oiiai import FetchZhipu

fetcher = FetchZhipu()
models = fetcher.fetch_models()
print(models)  # ['glm-4-flash', 'glm-4', ...]
```

### FetchModelScope

从 ModelScope API 获取模型列表。

```python
from oiiai import FetchModelScope

fetcher = FetchModelScope()
models = fetcher.fetch_models()
print(models)  # ['deepseek-ai/DeepSeek-R1-0528', 'Qwen/Qwen2.5-72B-Instruct', ...]
```

### FetchSiliconFlow

从 SiliconFlow API 获取模型列表。需要设置环境变量 `SILICONFLOW_API_KEY`。

```python
from oiiai import FetchSiliconFlow

fetcher = FetchSiliconFlow()
models = fetcher.fetch_models()
print(models)  # ['deepseek-ai/DeepSeek-R1', 'Qwen/Qwen2.5-72B-Instruct', ...]
```

### FetchIFlow

从 IFlow 平台获取模型列表。

```python
from oiiai import FetchIFlow

fetcher = FetchIFlow()
models = fetcher.fetch_models()
print(models)  # ['qwen3-max', 'deepseek-r1', 'kimi-k2', ...]
```

## 日志配置

oiiai 提供统一的日志记录系统，支持 JSON 格式输出和异步日志。

### 基本配置

```python
import logging
from oiiai import configure_logging, shutdown_logging

# 配置日志级别为 DEBUG，使用 JSON 格式输出
configure_logging(level=logging.DEBUG)

# 使用完毕后关闭日志（清理异步日志资源）
shutdown_logging()
```

### 配置选项

```python
configure_logging(
    level=logging.WARNING,    # 日志级别（默认: WARNING）
    handler=None,             # 自定义 Handler（默认: NullHandler）
    use_json=True,            # 是否使用 JSON 格式（默认: True）
    async_enabled=False,      # 是否启用异步日志（默认: False）
)
```

### 自定义 Handler

```python
import logging
from oiiai import configure_logging

# 使用文件 Handler
file_handler = logging.FileHandler("oiiai.log")
configure_logging(level=logging.INFO, handler=file_handler)
```

### 异步日志

在高并发场景下，可以启用异步日志避免阻塞：

```python
from oiiai import configure_logging, shutdown_logging

# 启用异步日志
configure_logging(level=logging.INFO, async_enabled=True)

# 程序退出前务必调用 shutdown_logging() 确保日志写入完成
shutdown_logging()
```

### JSON 日志格式

启用 JSON 格式后，日志输出包含以下字段：

| 字段 | 说明 |
|------|------|
| timestamp | ISO 8601 格式时间戳 |
| level | 日志级别 |
| provider | Provider 标识符 |
| message | 日志消息 |
| module | 模块名称 |
| function | 函数名称 |
| line | 行号 |
| exc_info | 异常堆栈（可选） |

## 开发

### 克隆仓库

```bash
git clone https://github.com/weisiren000/oiiai
cd oiiai
```

### 安装开发依赖

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

### 运行测试

```bash
uv run pytest
```

### 代码格式化

```bash
uv run ruff format .
uv run ruff check .
```

## 扩展

实现自定义获取器只需继承 `FetchBase` 并实现 `provider` 属性和 `fetch_models()` 方法。

## 许可证

MIT License. 详见 [LICENSE](LICENSE) 文件。

## 贡献

欢迎提交 Issue 和 Pull Request！

## 链接

- [GitHub 仓库](https://github.com/weisiren000/oiiai)
- [PyPI 页面](https://pypi.org/project/oiiai-lib/)
- [文档](https://github.com/weisiren000/oiiai/docs)