Metadata-Version: 2.4
Name: devnors-data
Version: 0.1.0
Summary: Devnors Data Python SDK —— 一个 API Key 调用所有数据（法律等多领域官方权威数据）
Author: Devnors
License: MIT
Project-URL: Homepage, https://data.devnors.com
Project-URL: Documentation, https://data.devnors.com/console/docs
Keywords: devnors,data,api,legal,agent,llm
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24
Dynamic: license-file

# Devnors Data Python SDK

一个 API Key 调用所有数据 —— 面向 AI Agent 的高质量数据 API（法律等多领域官方权威数据，每条出处可回溯）。

## 安装

> PyPI 正式发布进行中（打 `sdk-v*` tag 触发，见 [docs/RELEASE.md](../docs/RELEASE.md)）。发布后：

```bash
pip install devnors-data
```

发布前可用源码安装（从仓库根目录）：

```bash
pip install -e ./sdk
```

## 快速开始

先在 [开发者控制台](https://data.devnors.com/console) 创建 API Key。

```python
from devnors_data import DevnorsData

client = DevnorsData(api_key="devnors_sk_live_xxx")  # 或设环境变量 DEVNORS_API_KEY

# 裁判文书检索
res = client.legal_cases("民间借贷 利息", top_k=10)
for hit in res["hits"]:
    print(hit.get("case_no"), hit.get("title"))

# 法条检索
laws = client.legal_laws("合同解除 违约金")

# 统一入口（任意数据域/类型）
res = client.query(domain="legal", type="case", query="劳动争议", top_k=5)
print(res["units"], "tokens used")
```

异步：

```python
import asyncio
from devnors_data import AsyncDevnorsData

async def main():
    client = AsyncDevnorsData(api_key="devnors_sk_live_xxx")
    res = await client.legal_cases("交通事故 责任认定")
    print(res["total_hits"])

asyncio.run(main())
```

## 自动重试与分页

- **自动退避重试**：`429`/`5xx`/连接级错误默认重试 2 次（指数退避 + 抖动，`429` 优先按 `Retry-After`）；`400/401/402/501` 等不可重试错误**绝不重试**。关闭：`DevnorsData(..., max_retries=0)`（行为等同旧版）。
- **分页遍历**：`paginate(...)` 自动翻页（读 `total_hits` 判尽头），`max_items` 截断总量。

```python
for hit in client.paginate("legal", "case", "借贷纠纷", page_size=20, max_items=100):
    print(hit.get("case_no"))
```

## 计费与错误

- 按次调用计费，响应含 `units`（本次消耗 tokens）与 `request_id`。
- 余额不足抛 `DevnorsDataError(code="insufficient_balance", status=402)`；充值见控制台。
- 触发限流抛 `code="rate_limited"`（429）；数据源不可用 `code="unavailable"`（503，不计费）。
- 每个 `DevnorsDataError` 携带 `code` / `retryable` / `next_action` / `request_id`，便于 Agent 自纠与报障对账。

## 数据域

| domain | type | 状态 |
|---|---|---|
| legal | case / law_article / law_catalog | 已上线 |
| content / enterprise / research | — | 规划中（同一个 Key 上线即用） |
