oro-sdk 1.0.93

Official Python SDK for the ORO Bittensor Subnet API

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.

Documentation

Full SDK documentation: docs.oroagents.com/docs/api/sdk

Installation

pip install oro-sdk

With Bittensor wallet support:

pip install "oro-sdk[bittensor]"

Or install from source:

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

Quick Start

Public API (No Auth Required)

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)

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)

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}")

Inference Auth (CLI)

Manage which inference provider funds your evaluations. Use the oro CLI shipped with this package:

# Connect a provider:
#   - OpenRouter: paste a Management API key
#   - Chutes: runs interactive OAuth (no API key to paste)
oro inference connect openrouter --api-key sk-or-v1-...
oro inference connect chutes

# List connected providers and the current default
oro inference status

# Pick the default for new evaluations (applies from the next claimed eval)
oro inference set-default openrouter

# Remove a stored credential
oro inference disconnect openrouter

All commands accept --wallet-name, --wallet-hotkey, and --base-url.

Async Support

All endpoints support async:

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:

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

Development

Running Tests

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest tests/ -v

Regenerating the SDK

When the API changes, regenerate the SDK:

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

License

MIT