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 responsesync_detailed()- Blocking request returning full Response objectasyncio()- Async request returning parsed responseasyncio_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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
oro_sdk-1.0.102.tar.gz
(147.4 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
oro_sdk-1.0.102-py3-none-any.whl
(356.2 kB
view details)
File details
Details for the file oro_sdk-1.0.102.tar.gz.
File metadata
- Download URL: oro_sdk-1.0.102.tar.gz
- Upload date:
- Size: 147.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.11.15
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e26928d684d6a0716eea6b87ea3acb95691ca07cf2e8a2479e216a08c06f338e
|
|
| MD5 |
e14f45215b299c053f75680cf63ef2dc
|
|
| BLAKE2b-256 |
5b80b88855975c504bdbfda2c878c0a59607203d768ace493620650ad598acf9
|
File details
Details for the file oro_sdk-1.0.102-py3-none-any.whl.
File metadata
- Download URL: oro_sdk-1.0.102-py3-none-any.whl
- Upload date:
- Size: 356.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.11.15
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
321a54a4dfff4f8d06ab94fadce6e63a343c91f34c44b5e6880da4a0a68f5ab0
|
|
| MD5 |
63a2cd856fd32d51c382b8a2d99dc391
|
|
| BLAKE2b-256 |
dd17ad9d2f21478504eb0603b04c96a7085ccfe72fc8a59379011cf9026dcb01
|
