Metadata-Version: 2.4
Name: laiwenai
Version: 0.0.1
Summary: A lightweight OpenAI-compatible LLM client wrapper with defaults, retries, logging, and manual JSON mode.
Author: LaiwenAI
License-Expression: MIT
Keywords: openai,llm,client,json,retry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: tenacity>=8.0.0
Dynamic: license-file

<p align="center">
  <img src="image/README/banner.svg" alt="LaiwenAI animated banner" width="100%">
</p>

<h1 align="center">LaiwenAI LLM Client</h1>

<p align="center">
  一个轻量的 OpenAI 兼容 Python 客户端封装，内置默认参数、重试机制、服务商校验和 logger 输出。
</p>

<p align="center">
  <a href="README.md">简体中文</a>
  ·
  <a href="README.EN.md">English</a>
</p>

<p align="center">
  <img alt="Python" src="https://img.shields.io/badge/Python-3.9%2B-3776AB?style=flat-square&logo=python&logoColor=white">
  <img alt="OpenAI compatible" src="https://img.shields.io/badge/OpenAI-Compatible-111111?style=flat-square&logo=openai&logoColor=white">
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/License-MIT-green?style=flat-square"></a>
</p>

---

## 项目简介

LaiwenAI 让 OpenAI 兼容模型的调用更省心：你只需要在 `.env` 里配置一次默认服务商、模型、超时和重试策略，就可以继续使用熟悉的 OpenAI SDK 写法，同时获得默认参数注入、服务商切换保护和可选 logger 输出。

适合用于脚本、后端服务、原型验证，以及需要在多个 OpenAI 兼容服务之间切换的小型项目。

## 功能特性

- **OpenAI SDK 兼容写法**：继续使用 `client.chat.completions.create(...)`、`client.embeddings.create(...)` 等熟悉接口。
- **支持 OpenAI 兼容接口**：通过 `DEFAULT_BASE_URL` 或实例化参数接入第三方兼容服务。
- **集中默认配置**：统一管理默认模型、embedding 模型、温度、超时、重试次数和日志目录。
- **更安全的服务商切换**：传入自定义 `base_url` 时必须显式传入 `api_key`，降低误用默认密钥的风险。
- **可选 logger 输出**：可关闭、只输出到屏幕，或同时输出到屏幕和文件。

## 项目结构

```text
.
├── .env.example          # 环境变量模板
├── LICENSE               # MIT 许可证
├── pyproject.toml        # Python 包配置
├── README.md             # 中文说明
├── README.EN.md          # English README
├── image/README/         # README 图片与 banner
├── docs/                 # 设计与代码说明
├── examples/             # 调用示例
├── tests/                # 单元测试
└── src/
    └── laiwenai/
        ├── __init__.py
        ├── llm_client.py        # LaiwenAI 客户端封装
        └── llm_config.py        # .env 配置读取
```

## 快速开始

### 1. 安装依赖

```bash
pip install laiwenai
```

### 2. 配置环境变量

```bash
cp .env.example .env
```

在 `.env` 中填入你的 API Key、OpenAI 兼容接口地址和默认模型：

```env
LLM_API_KEY=your_api_key_here
DEFAULT_BASE_URL=https://api.example.com/v1
DEFAULT_MODEL=MiniMax-M2.7
DEFAULT_EMBEDDING_MODEL=text-embedding-3-small
DEFAULT_TEMPERATURE=0
DEFAULT_TIMEOUT=30.0
MAX_RETRIES=1
ENABLE_LOG_CONSOLE=False
ENABLE_LOG_FILE=False
LOG_DIR=logs
```

### 3. 检查默认行为

运行时配置都可以放在 `.env` 中：

```env
DEFAULT_TEMPERATURE=0
DEFAULT_TIMEOUT=30.0
MAX_RETRIES=1
ENABLE_LOG_CONSOLE=False
ENABLE_LOG_FILE=False
LOG_DIR=logs
```

日志默认关闭。只想在屏幕显示日志时，将 `ENABLE_LOG_CONSOLE` 改为 `True`。如果将 `ENABLE_LOG_FILE` 改为 `True`，日志会同时输出到屏幕，并写入 `LOG_DIR/laiwenai.log`。`LOG_DIR` 默认是当前运行目录下的 `logs/`，也可以设置成你自己的日志目录。

### 4. 运行示例

```bash
python examples/llm.py
```

示例脚本会先发起一次 chat completion，再发起一次 embedding 请求，并打印模型回复或 embedding 向量维度。

## 使用方式

### 默认客户端

`LaiwenAI()` 会读取 `.env` 中的配置，并通过 `laiwenai.llm_config` 转换成运行时配置。

```python
from laiwenai import LaiwenAI

client = LaiwenAI()

response = client.chat.completions.create(
    messages=[
        {"role": "user", "content": "Hello, please confirm your model version"}
    ]
)

print(response.choices[0].message.content)
```

### 请求默认值

`model`、`temperature` 和 `timeout` 不传或传入 `None` 时，会使用默认配置。Chat/Responses 请求默认使用 `.env` 里的 `DEFAULT_MODEL`，Embedding 请求默认使用 `.env` 里的 `DEFAULT_EMBEDDING_MODEL`。

```python
response = client.chat.completions.create(
    model=None,
    messages=[{"role": "user", "content": "Hello"}],
    temperature=None,
    timeout=None,
)
```

Embedding 调用示例：

```python
embedding = client.embeddings.create(input="Hello")
print(len(embedding.data[0].embedding))
```

JSON mode 等 OpenAI SDK 参数会原样透传给底层接口：

```python
response = client.chat.completions.create(
    messages=[{"role": "user", "content": "Return a JSON object"}],
    response_format={"type": "json_object"},
)
```

### OpenAI 兼容接口

当你传入自定义 `base_url` 时，必须显式传入 `api_key`，避免把默认密钥误用于另一个服务商。

```python
from laiwenai import LaiwenAI

client = LaiwenAI(
    api_key="your-provider-key",
    base_url="https://api.example.com/v1",
    model="MiniMax-M2.7",
)
```

### 内置使用帮助

```python
from laiwenai import LaiwenAI

print(LaiwenAI.usage())
```

## 调用日志

默认不输出日志。将 `.env` 中的 `ENABLE_LOG_CONSOLE` 设置为 `True` 后，LaiwenAI 会把结构化日志输出到屏幕。将 `ENABLE_LOG_FILE` 设置为 `True` 后，LaiwenAI 会同时输出到屏幕，并追加写入 `LOG_DIR/laiwenai.log`。

日志包含时间、API 类型、模型、耗时、Token 用量、结束原因、系统提示词、用户提示词、回复文本和完整 JSON。

## 测试

```bash
PYTHONPATH=src pytest tests/test_llm.py -v
```

示例输出：

![Pytest output screenshot](image/README/1776004937743.png)

## 配置参考

| 配置项 | 文件 | 说明 |
| --- | --- | --- |
| `LLM_API_KEY` | `.env` | 通过 `python-dotenv` 加载的默认 API Key。 |
| `DEFAULT_BASE_URL` | `.env` | 默认 OpenAI 兼容接口地址；不配置则使用 OpenAI SDK 默认地址。 |
| `DEFAULT_MODEL` | `.env` | Chat/Responses 请求未指定模型时使用的模型；必须配置。 |
| `DEFAULT_EMBEDDING_MODEL` | `.env` | Embedding 请求未指定模型时使用的模型；必须配置。 |
| `DEFAULT_TEMPERATURE` | `.env` | 请求未指定或传入 `None` 时使用的温度。 |
| `DEFAULT_TIMEOUT` | `.env` | 请求未指定或传入 `None` 时使用的超时时间。 |
| `MAX_RETRIES` | `.env` | 封装 API 调用的重试次数。 |
| `ENABLE_LOG_CONSOLE` | `.env` | 是否只输出屏幕日志。 |
| `ENABLE_LOG_FILE` | `.env` | 是否开启文件日志；开启后同时输出到屏幕和文件。 |
| `LOG_DIR` | `.env` | 文件日志目录；默认当前运行目录下的 `logs`。 |

## 参与贡献

欢迎提交 Issue 和 Pull Request。对于有行为变化的修改，建议附上简短说明、必要示例，以及能防止回归的测试。

## 开源协议

LaiwenAI 基于 [MIT License](LICENSE) 开源。
