Metadata-Version: 2.4
Name: novusai
Version: 0.1.0
Summary: NovusAI 推理服务官方 Python SDK——自有协议 /api/chat 主体，零第三方依赖
Author: NovusAI
License: Proprietary
Keywords: novusai,llm,inference,distributed
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# novusai — NovusAI 推理服务 Python SDK

NovusAI 网络的官方 Python 客户端。零第三方依赖（纯标准库），走 NovusAI 自有协议（`/api/chat`）。

## 安装

```bash
pip install novusai
```

本地源码安装：`pip install .`（项目根目录）。

## 快速开始

1. 打开 [https://www.t-cab.net](https://www.t-cab.net) →「新建 ID」→ 生成 API key（`nvk-` 前缀，永不过期可撤销）；
2. 你的节点/程序贡献推理与容量获得贡献值（CP），API 调用按实耗扣减 CP（输入 0.01 / 输出 0.04 CP/百 token）。

```python
from novusai import Client

client = Client(api_key="nvk-...")  # 或环境变量 NOVUSAI_API_KEY

result = client.chat("帮我总结这段日志")
print(result["response"])
```

带进度回调（模型加载/推理阶段）：

```python
result = client.chat(
    "跨节点推理测试",
    on_progress=lambda task: print(task["stage_label"]),
)
```

非阻塞 + 手动轮询：

```python
submitted = client.chat_async("你好")
task = client.poll(submitted["task_id"])  # status: processing/done/failed
```

## API

| 方法 | 说明 |
|---|---|
| `Client(api_key=None, base_url="https://www.t-cab.net", timeout=30, task_timeout=360)` | 缺省从 `NOVUSAI_API_KEY` 读 key |
| `chat(prompt, mode="default", on_progress=None) -> dict` | 阻塞直到完成，返回 `{success, response, ...}` |
| `chat_async(prompt, mode="default") -> dict` | 返回 `{task_id, status, stage, poll_url}` |
| `poll(task_id) -> dict` | 轮询任务态；done 携带 result |
| `usage(registration_id, days=7, include_ids=None) -> dict` | 用量/消耗聚合（注册 ID 见页面贡献区；`include_ids` 支持本人历史 ID 聚合） |

## 错误

| 异常 | HTTP | 含义 |
|---|---|---|
| `AuthenticationError` | 401 | key 无效或已撤销 |
| `InsufficientBalance` | 402 | 贡献值（CP）≤0，预检拒绝——先让节点上线积累贡献 |
| `RateLimited` | 429 | 限速（60s 窗口 6 次），`retry_after_s` 给出等待秒数 |
| `TaskFailed` | — | 任务 failed 或推理产出为空 |

所有异常继承 `NovusAIError`（`status_code` / `payload` 属性保留服务端原始响应）。
