Metadata-Version: 2.4
Name: oasyce-sdk
Version: 0.4.0
Summary: Python SDK for Oasyce -- On-chain economic system for AI agents: escrow, service marketplace, data rights, reputation, dispute resolution
Project-URL: Homepage, https://github.com/Shangri-la-0428/oasyce-chain
Project-URL: Documentation, http://47.93.32.88:1317/llms.txt
Project-URL: Repository, https://github.com/Shangri-la-0428/oasyce-sdk
Project-URL: Issues, https://github.com/Shangri-la-0428/oasyce-sdk/issues
Project-URL: Chain, https://github.com/Shangri-la-0428/oasyce-chain
Project-URL: MCP, https://github.com/Shangri-la-0428/oasyce-sdk#mcp-server
Author-email: Oasyce <dev@oasyce.com>
License-Expression: Apache-2.0
Keywords: agent-economy,ai-agents,blockchain,cosmos-sdk,data-rights,escrow,llm,mcp,oasyce,proof-of-work,reputation,service-marketplace,settlement
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
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 :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: requests>=2.28
Provides-Extra: all
Requires-Dist: langchain-core>=0.2; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2; extra == 'langchain'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# oasyce-sdk

Oasyce L1 链 Python SDK —— AI Agent 原生经济系统：产权确权、智能合约、自动仲裁。

[English](README_EN.md)

## 安装

```bash
pip install oasyce-sdk            # 基础 SDK
pip install oasyce-sdk[mcp]       # + MCP Server（Claude/Cursor/Windsurf）
pip install oasyce-sdk[langchain] # + LangChain Tools
pip install oasyce-sdk[all]       # 全部
```

## MCP Server

让你的 AI 助手（Claude Desktop / Cursor / Windsurf）直接操作 Oasyce 链。

配置 `claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "oasyce": {
      "command": "oasyce-mcp",
      "env": {
        "OASYCE_NODE": "http://47.93.32.88:1317",
        "OASYCE_FAUCET": "http://47.93.32.88:8080"
      }
    }
  }
}
```

提供 10 个工具：健康检查、领水龙头、查余额、查 agent 档案、浏览市场、列出能力、查信誉、查数据资产、查开放任务、提 issue。

## LangChain Tools

```python
from oasyce_sdk.langchain_tools import oasyce_tools
from langchain.agents import create_react_agent

agent = create_react_agent(llm, oasyce_tools)
agent.invoke({"input": "浏览 Oasyce 市场上有什么 AI 服务"})
```

## 快速开始（SDK）

```python
from oasyce_sdk import OasyceClient

client = OasyceClient("http://47.93.32.88:1317")
caps = client.list_capabilities(tag="llm")
bal = client.get_balance("oasyce1abc...")
print(f"发现 {len(caps)} 个能力, 余额: {bal.amount_oas} OAS")
```

## API 参考

### 构造函数

```python
OasyceClient(base_url="http://localhost:1317", timeout=10)
```

连接 Oasyce 链节点的 REST API (gRPC-gateway)。

---

### 能力市场 (Capability Marketplace)

#### `list_capabilities(tag=None, provider=None) -> list[Capability]`

列出所有已注册的 AI 能力。支持按标签或提供者地址过滤。

```python
all_caps = client.list_capabilities()
llm_caps = client.list_capabilities(tag="llm")
my_caps = client.list_capabilities(provider="oasyce1abc...")
```

#### `get_capability(capability_id) -> Capability`

按 ID 查询单个能力。

```python
cap = client.get_capability("cap-001")
print(cap.name, cap.price_per_call, "uoas/次")
```

#### `get_earnings(provider) -> Earnings`

查询提供者在所有能力上的累计收入。

```python
earnings = client.get_earnings("oasyce1abc...")
print(f"累计收入 {client.uoas_to_oas(earnings.total_earned_uoas)} OAS, 共 {earnings.total_calls} 次调用")
```

#### `get_invocation(invocation_id) -> Invocation`

查询单个调用记录（含状态、挑战窗口、使用报告）。

```python
inv = client.get_invocation("INV_0000000000000001")
print(inv.status, inv.output_hash, inv.usage_report)
```

#### `get_capability_params() -> dict`

查询能力模块参数。

---

### 数据资产 (Data Assets)

#### `list_assets(tag=None, owner=None) -> list[DataAsset]`

列出数据资产，支持按标签或所有者过滤。

```python
assets = client.list_assets(tag="ml")
```

#### `get_asset(asset_id) -> DataAsset`

查询单个数据资产。

```python
asset = client.get_asset("asset-001")
print(asset.name, asset.status, f"已发行 {asset.total_shares} 份")
```

#### `get_shares(asset_id) -> list[ShareHolder]`

列出数据资产的所有持有人。

```python
holders = client.get_shares("asset-001")
for h in holders:
    print(f"{h.address}: {h.shares} 份")
```

#### `get_bonding_curve(asset_id) -> BondingCurve`

查询联合曲线状态（供应量、储备金、现价）。

```python
bc = client.get_bonding_curve("asset-001")
print(f"现价: {bc.spot_price_uoas} uoas, 储备: {bc.reserve_uoas} uoas")
```

#### `get_access_level(asset_id, address) -> AccessLevel`

查询地址在数据资产上的访问等级（L0-L3）。

```python
al = client.get_access_level("asset-001", "oasyce1buyer...")
print(f"等级: {al.level}, 持股: {al.equity_bps} bps")
```

#### `get_dispute(dispute_id) -> Dispute` / `list_disputes(asset_id=None) -> list[Dispute]`

查询争议。

#### `get_migration_path(source_id, target_id) -> MigrationPath`

查询两个资产版本之间的迁移路径。

#### `get_asset_children(asset_id) -> list[DataAsset]`

查询资产的子版本（fork）。

#### `get_datarights_params() -> dict`

查询数据权益模块参数。

---

### 结算 (Settlement)

#### `get_escrow(escrow_id) -> Escrow`

按 ID 查询托管。

```python
esc = client.get_escrow("esc-001")
print(esc.status)  # LOCKED, RELEASED, REFUNDED, EXPIRED
```

#### `list_escrows(creator) -> list[Escrow]`

列出某地址创建的所有托管。

```python
escrows = client.list_escrows("oasyce1abc...")
locked = [e for e in escrows if e.status == "LOCKED"]
```

#### `get_settlement_params() -> dict`

查询结算模块参数。

---

### 信誉 (Reputation)

#### `get_reputation(address) -> Reputation`

查询地址的信誉分。

```python
rep = client.get_reputation("oasyce1abc...")
print(f"评分: {rep.score}, 来自 {rep.total_feedback} 次反馈")
```

#### `get_leaderboard() -> list[Reputation]`

获取信誉排行榜。

```python
lb = client.get_leaderboard()
for entry in lb[:5]:
    print(f"{entry.address}: {entry.score}")
```

#### `get_reputation_params() -> dict`

查询信誉模块参数。

---

### 工作证明 (Proof of Useful Work)

#### `get_task(task_id) -> Task`

按 ID 查询计算任务。

```python
task = client.get_task("42")
print(task.status, task.bounty_uoas)
```

#### `list_tasks(status=None) -> list[Task]`

按状态过滤任务（1=已提交, 2=已分配, ..., 5=已结算）。

```python
pending = client.list_tasks(status=1)
```

#### `list_executors() -> list[Executor]`

列出所有已注册的执行者。

```python
for ex in client.list_executors():
    print(f"{ex.address}: 已完成 {ex.tasks_completed} 个任务, 活跃={ex.active}")
```

#### `get_executor(address) -> Executor`

查询单个执行者。

#### `list_tasks_by_creator(creator) -> list[Task]` / `list_tasks_by_executor(executor) -> list[Task]`

按创建者或执行者过滤任务。

#### `get_work_params() -> dict` / `get_epoch_stats(epoch) -> EpochStats`

查询工作模块参数和纪元统计。

---

### 注册 (Onboarding)

#### `get_registration(address) -> Registration`

查询用户的注册信息。

```python
reg = client.get_registration("oasyce1new...")
print(f"空投: {reg.airdrop_amount} uoas, 已还: {reg.repaid_amount} uoas")
```

#### `get_debt(address) -> Debt`

查询未偿还的注册债务。

```python
debt = client.get_debt("oasyce1new...")
print(f"剩余: {debt.remaining} uoas ({debt.status})")
```

#### `get_onboarding_params() -> dict`

查询注册模块参数（PoW 难度、空投金额等）。

---

### 银行 / 账户 / 区块 (Cosmos SDK)

#### `get_balance(address) -> Balance`

查询 uoas 余额。

```python
bal = client.get_balance("oasyce1abc...")
print(f"{bal.amount_oas} OAS ({bal.amount_uoas} uoas)")
```

#### `get_account(address) -> Account`

查询账户号和序列号（签名交易时需要）。

```python
acct = client.get_account("oasyce1abc...")
print(f"账户 #{acct.account_number}, 序列 {acct.sequence}")
```

#### `get_latest_block() -> Block`

查询最新区块。

```python
block = client.get_latest_block()
print(f"高度 {block.height}, 链 {block.chain_id}")
```

---

### PoW 求解器

#### `solve_pow(address, difficulty=16) -> PowResult`

纯 Python PoW 求解器，与链上 Go 验证器完全一致。

```python
result = OasyceClient.solve_pow("oasyce1abc...", difficulty=16)
print(f"Nonce: {result.nonce}, 尝试: {result.attempts} 次")

# 然后注册
tx = client.build_self_register("oasyce1abc...", result.nonce)
```

---

### 交易构建器 (27 个)

所有 `build_*` 方法生成未签名的 Cosmos SDK 交易 JSON。签名后传给 `broadcast_tx()` 广播。

#### 能力市场

| 方法 | 说明 |
|------|------|
| `build_register_capability(sender, name, endpoint, price_uoas, ...)` | 注册 AI 能力 |
| `build_invoke_capability(sender, capability_id, input_data)` | 调用能力（自动托管） |
| `build_complete_invocation(sender, invocation_id, output_hash, usage_report)` | 提交输出（开始挑战窗口） |
| `build_fail_invocation(sender, invocation_id)` | 标记调用失败 |
| `build_claim_invocation(sender, invocation_id)` | 挑战窗口后领取付款 |
| `build_dispute_invocation(sender, invocation_id, reason)` | 挑战窗口内争议 |

#### 数据权益

| 方法 | 说明 |
|------|------|
| `build_register_asset(sender, name, content_hash, ...)` | 注册数据资产 |
| `build_buy_shares(sender, asset_id, amount_uoas)` | 买入股份（Bancor 曲线） |
| `build_sell_shares(sender, asset_id, shares)` | 卖出股份（反向曲线） |
| `build_file_dispute(sender, asset_id, reason, evidence, remedy)` | 提起争议 |
| `build_initiate_shutdown(sender, asset_id)` | 发起关停（7天冷却期） |
| `build_claim_settlement(sender, asset_id)` | 关停后按比例领取储备金 |
| `build_create_migration(sender, source_id, target_id, rate_bps, max_shares)` | 创建迁移路径 |
| `build_migrate(sender, source_id, target_id, shares)` | 执行跨版本迁移 |

#### 结算

| 方法 | 说明 |
|------|------|
| `build_create_escrow(sender, amount_uoas, capability_id, asset_id)` | 创建托管 |
| `build_release_escrow(sender, escrow_id)` | 释放托管（90/5/2/3 分账） |
| `build_refund_escrow(sender, escrow_id)` | 退款托管 |

#### 信誉

| 方法 | 说明 |
|------|------|
| `build_submit_feedback(sender, invocation_id, rating, comment)` | 提交评价（0-500） |
| `build_report_misbehavior(sender, target, evidence_type, evidence)` | 举报不良行为 |

#### 工作证明 (PoUW)

| 方法 | 说明 |
|------|------|
| `build_register_executor(sender, task_types, max_cu)` | 注册执行者 |
| `build_update_executor(sender, task_types, max_cu, active)` | 更新执行者 |
| `build_submit_task(sender, task_type, input_hash, input_uri, max_cu, bounty_uoas)` | 提交计算任务 |
| `build_commit_result(sender, task_id, commit_hash)` | 提交结果承诺 |
| `build_reveal_result(sender, task_id, output_hash, output_uri, cu_used, salt)` | 揭示结果 |
| `build_dispute_result(sender, task_id, reason, bond_uoas)` | 争议结果 |

#### 注册

| 方法 | 说明 |
|------|------|
| `build_self_register(sender, nonce)` | PoW 自注册 |
| `build_repay_debt(sender, amount_uoas)` | 偿还空投债务 |

#### `broadcast_tx(signed_tx) -> TxResult`

广播已签名交易。

```python
result = client.broadcast_tx(signed_tx)
if result.success:
    print(f"TX 哈希: {result.tx_hash}")
else:
    print(f"失败 (code {result.code}): {result.raw_log}")
```

---

### 工具方法

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

检查节点是否可达。

```python
if client.health():
    print("节点运行中")
```

#### `oas_to_uoas(oas) -> int` / `uoas_to_oas(uoas) -> float`

OAS 和 micro-OAS 之间转换。1 OAS = 1,000,000 uoas。

```python
OasyceClient.oas_to_uoas(1.5)     # 1500000
OasyceClient.uoas_to_oas(2500000)  # 2.5
```

---

## AHRP 适配器（v0.3.0）

`SigningBridge` 将 SDK 的 TX 构建器与 `oasyced` CLI 签名结合，实现一步到位的交易广播：

```python
from oasyce_sdk import OasyceClient, SigningBridge

client = OasyceClient("http://localhost:1317")
bridge = SigningBridge(
    client=client,
    oasyced_path="./oasyced",
    key_name="my-agent",
    chain_id="oasyce-testnet-1",
    node="tcp://localhost:26657",
)

# 构建 + 签名 + 广播
result = bridge.create_escrow(amount_uoas=50000, asset_id="DATA_001")
print(result.tx_hash, result.success)
```

`AhrpChainAdapter` 将 `SigningBridge` 适配为 Plugin Engine AHRP Executor 期望的接口，**无需修改任何 AHRP 代码**：

```python
from oasyce_sdk import AhrpChainAdapter

adapter = AhrpChainAdapter(bridge)
# 直接传入 AHRP Executor:
# executor = AHRPExecutor(chain_client=adapter)
```

完整示例见 `examples/ahrp_two_agent_demo.py`。

---

## 错误处理

所有错误继承自 `OasyceError`，可以宽泛或精确地捕获：

```python
from oasyce_sdk import OasyceClient
from oasyce_sdk.errors import NotFoundError, TimeoutError, OasyceError

client = OasyceClient()

try:
    cap = client.get_capability("cap-xyz")
except NotFoundError:
    print("能力不存在")
except TimeoutError:
    print("节点响应慢")
except OasyceError as e:
    print(f"出错了: {e}")
```

异常层级：

```
OasyceError
  +-- NotFoundError      # 链上未找到资源 (404 / gRPC NOT_FOUND)
  +-- ChainError         # 应用层链错误
  +-- HTTPError          # 非预期 HTTP 状态码
  +-- ConnectionError    # 无法连接节点
  +-- TimeoutError       # 请求超时
  +-- ValidationError    # 请求发出前的输入校验错误
```

## 为什么不直接用 `requests`？

你当然可以直接请求 `http://localhost:1317/oasyce/capability/v1/capabilities`。这个 SDK 额外提供：

- **类型化响应** —— 编辑器自动补全，不用猜 JSON key
- **异常层级** —— 区分 `NotFoundError` / `TimeoutError` / `ChainError`
- **单位转换** —— 内置 `oas_to_uoas()` / `uoas_to_oas()`
- **Protobuf 枚举映射** —— `ESCROW_STATUS_LOCKED` 自动变成 `"LOCKED"`
- **交易构建器** —— 正确的消息结构，不需要读 proto 文件
- **线程安全** —— 无全局状态，内部使用 `requests.Session`
- **单一依赖** —— 只需 `requests>=2.28`，无需编译 protobuf

## 生态链接

- [oasyce-chain](https://github.com/Shangri-la-0428/oasyce-chain) — L1 链（Go / Cosmos SDK），公测文档见 `docs/PUBLIC_BETA_CN.md`
- [Plugin Engine](https://github.com/Shangri-la-0428/oasyce-net) — Python CLI + Dashboard + DataVault（`pip install oasyce`）
- [Discord](https://discord.gg/tfrCn54yZW)

## 协议

Apache-2.0
