# ORO SDK for Python

Official Python SDK for the ORO Bittensor Subnet API.

This SDK is auto-generated from the OpenAPI specification using [openapi-python-client](https://github.com/openapi-generators/openapi-python-client).

## Installation

```bash
pip install oro-sdk
```

With Bittensor wallet support:

```bash
pip install oro-sdk[bittensor]
```

Or install from source:

```bash
pip install git+https://github.com/KriyOS-AI/oro-sdk.git#subdirectory=packages/python
```

## Quick Start

### Public API (No Auth Required)

```python
from oro_sdk import Client
from oro_sdk.api.public import get_leaderboard, get_top_for_emissions

client = Client(base_url="https://api.oro.ai")

# Get leaderboard
leaderboard = get_leaderboard.sync(client=client)
if leaderboard:
    for entry in leaderboard.entries:
        print(f"{entry.rank}. {entry.miner_hotkey}: {entry.final_score}")

# Get top agent for emissions
top = get_top_for_emissions.sync(client=client)
if top:
    print(f"Top miner: {top.top_miner_hotkey} with score {top.top_score}")
```

### Validator API (Requires Bittensor Wallet)

```python
from bittensor_wallet import Wallet
from oro_sdk import BittensorAuthClient
from oro_sdk.api.validator import claim_work, heartbeat_evaluation_run, complete_evaluation_run
from oro_sdk.models import CompleteEvaluationRequest, CompleteEvaluationRequestTerminalStatus

wallet = Wallet(name="validator", hotkey="default")
client = BittensorAuthClient(base_url="https://api.oro.ai", wallet=wallet)

# Claim work
work = claim_work.sync(client=client)
if work:
    print(f"Claimed eval run: {work.eval_run_id}")

    # Send heartbeat
    heartbeat = heartbeat_evaluation_run.sync(
        eval_run_id=work.eval_run_id,
        client=client,
    )
    print(f"Lease extended to: {heartbeat.lease_expires_at}")

    # Complete run
    result = complete_evaluation_run.sync(
        eval_run_id=work.eval_run_id,
        client=client,
        body=CompleteEvaluationRequest(
            terminal_status=CompleteEvaluationRequestTerminalStatus.SUCCESS,
            validator_score=0.85,
        ),
    )
    print(f"Completed! Eligible: {result.agent_version_became_eligible}")
else:
    print("No work available")
```

### Miner API (Requires Bittensor Wallet)

```python
from bittensor_wallet import Wallet
from oro_sdk import BittensorAuthClient
from oro_sdk.api.miner import submit_agent, get_miner_agent_version_status

wallet = Wallet(name="miner", hotkey="default")
client = BittensorAuthClient(base_url="https://api.oro.ai", wallet=wallet)

# Submit an agent (multipart file upload)
with open("my_agent.py", "rb") as f:
    from oro_sdk.models import SubmitAgentBody
    from oro_sdk.types import File

    body = SubmitAgentBody(file=File(payload=f, file_name="my_agent.py"))
    response = submit_agent.sync(client=client, body=body)

if response.admission_status.value == "ACCEPTED":
    print(f"Submitted! Version ID: {response.agent_version_id}")

    # Check status
    status = get_miner_agent_version_status.sync(
        agent_version_id=response.agent_version_id,
        client=client,
    )
    print(f"State: {status.state}, Score: {status.final_score}")
```

### Async Support

All endpoints support async:

```python
import asyncio
from oro_sdk import Client
from oro_sdk.api.public import get_leaderboard

async def main():
    client = Client(base_url="https://api.oro.ai")
    leaderboard = await get_leaderboard.asyncio(client=client)
    print(leaderboard)

asyncio.run(main())
```

## API Structure

The SDK is organized by API tag:

- `oro_sdk.api.public` - Public endpoints (no auth)
- `oro_sdk.api.validator` - Validator endpoints (requires validator wallet)
- `oro_sdk.api.miner` - Miner endpoints (requires miner wallet)
- `oro_sdk.api.admin` - Admin endpoints (requires admin access)

Each endpoint module provides:
- `sync()` - Blocking request returning parsed response
- `sync_detailed()` - Blocking request returning full Response object
- `asyncio()` - Async request returning parsed response
- `asyncio_detailed()` - Async request returning full Response object

## Models

All request/response models are in `oro_sdk.models`:

```python
from oro_sdk.models import (
    ClaimWorkResponse,
    HeartbeatResponse,
    CompleteEvaluationRequest,
    CompleteEvaluationResponse,
    LeaderboardResponse,
    TopForEmissions,
    # ... etc
)
```

## Development

### Running Tests

```bash
# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest tests/ -v
```

### Regenerating the SDK

When the API changes, regenerate the SDK:

```bash
pip install openapi-python-client
./scripts/generate-python.sh
```

## License

MIT
