Metadata-Version: 2.4
Name: oro-sdk
Version: 1.0.22
Summary: Official Python SDK for the ORO Bittensor Subnet API
Author-email: ORO Team <team@oro.ai>
License: MIT
Project-URL: Homepage, https://github.com/ORO-AI/oro-sdk
Project-URL: Repository, https://github.com/ORO-AI/oro-sdk
Project-URL: Documentation, https://github.com/ORO-AI/oro-sdk#readme
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx<0.29.0,>=0.23.0
Requires-Dist: attrs>=22.2.0
Requires-Dist: python-dateutil>=2.8.0
Provides-Extra: bittensor
Requires-Dist: bittensor-wallet>=2.0.0; extra == "bittensor"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: openapi-python-client>=0.20.0; extra == "dev"

# 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).

## Documentation

Full SDK documentation: [docs.oroagents.com/docs/api/sdk](https://docs.oroagents.com/docs/api/sdk)

## 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/ORO-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
