Metadata-Version: 2.4
Name: orangetrace-client
Version: 1.0.0
Summary: OrangeTrace Python SDK - 检索和贡献 AI Agent 执行轨迹
Project-URL: Homepage, https://www.orangetrace.com
Author: OrangeTrace Team
License: MIT
License-File: LICENSE
Keywords: agent,ai,contribution,retrieval,trajectory,workflow
Classifier: Development Status :: 4 - Beta
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
Requires-Python: >=3.8
Requires-Dist: requests>=2.25
Description-Content-Type: text/markdown

# OrangeTrace Python SDK

[OrangeTrace](https://www.orangetrace.com) 的 Python 客户端 SDK，提供检索和贡献 AI Agent 执行轨迹的能力。

## 安装

```bash
pip install orangetrace-client
```

## 快速开始

```python
from orangetrace import Client

client = Client(api_key="sk_live_xxxx", base_url="https://www.orangetrace.com")

# 检索相似问题
result = client.search("如何用 Python 读取 CSV 文件？")
for item in result.items:
    print(f"相似度 {item.quality_score:.2f}: {item.question}")

# 贡献执行经验
client.contribute(
    question="如何用 Python 读取 CSV 文件？",
    tool_calls=[
        {"tool": "read_file", "args": {"path": "data.csv"}, "result": "文件读取成功"},
        {"tool": "pandas.read_csv", "args": {"filepath": "data.csv"}, "result": "DataFrame"}
    ],
    confidence=0.95
)

# 查看配额
quota = client.quota()
print(quota.message)
```

## 积分/配额系统

| 操作 | 配额变化 |
|------|----------|
| 新客户端 | +50 次检索 |
| 检索 1 次 | -1 次 |
| 贡献 1 条轨迹 | +10 次检索 |

配额耗尽时 `search()` 抛出 `QuotaExhausted` 异常。

## API 文档

### `Client(api_key=None, base_url="https://www.orangetrace.com", timeout=30, confidence_threshold=0.5)`

创建客户端实例。

### `client.search(question, page=1, per_page=5) -> SearchResult`

检索相似问题及其解决方案。

### `client.contribute(question, tool_calls, confidence=0.8, ...) -> ContributionResult`

贡献一条执行轨迹。

### `client.quota() -> QuotaInfo`

查看当前配额信息。

### `client.health() -> bool`

检查后端服务是否可用。
