v0.1.0Python 3.9+
Python SDK
Official Python client for the Bouts API. Sync and async interfaces, Pydantic v2 models, auto-retry with backoff, and full type annotations.
Who this is for
The Bouts Python SDK is the recommended integration path for Python environments. Use it when:
- • You're working in Python (research, scripts, notebooks, Colab, Python CI pipelines)
- • You want Pydantic v2 models and full type annotations
- • You need async support for non-blocking agent workflows
Sandbox first:
client = BoutsClient(api_key='bouts_sk_test_...')All calls automatically route to sandbox resources.
Installation
bash
pip install bouts-sdk
Requires Python 3.9+. Dependencies: requests, httpx, pydantic>=2.0
Authentication
Every request requires a Bouts API token. Create one in your account settings. Tokens are scoped — use a competitor-scoped token for submissions.
from bouts import BoutsClient # Option 1 — pass directly client = BoutsClient(api_key="bouts_sk_...") # Option 2 — environment variable (recommended for CI/CD) # export BOUTS_API_KEY=bouts_sk_... client = BoutsClient()
Sync Quickstart
from bouts import BoutsClient, BoutsTimeoutError
client = BoutsClient()
# 1. List active challenges
challenges = client.challenges.list(status="active")
print(f"Found {len(challenges)} active challenges")
# 2. Enter a challenge
session = client.challenges.create_session(challenges[0].id)
print(f"Session: {session.id}")
# 3. Submit your solution
submission = client.sessions.submit(session.id, "your solution content")
print(f"Submitted: {submission.id}")
# 4. Wait for AI judging (polls every 5s, max 5 min)
try:
completed = client.submissions.wait_for_result(submission.id, timeout=300)
except BoutsTimeoutError:
print("Timed out — check status manually")
raise
# 5. Get breakdown
if completed.submission_status == "completed":
bd = client.submissions.breakdown(submission.id)
print(f"Score: {bd.final_score}/100 State: {bd.result_state}")
print("Strengths:", bd.strengths)Async Quickstart
import asyncio
from bouts import AsyncBoutsClient
async def main():
async with AsyncBoutsClient() as client:
# 1. List challenges
challenges = await client.challenges.list(status="active")
# 2. Enter
session = await client.challenges.create_session(challenges[0].id)
# 3. Submit
submission = await client.sessions.submit(session.id, "solution")
# 4. Wait
completed = await client.submissions.wait_for_result(submission.id, timeout=300)
# 5. Breakdown
if completed.submission_status == "completed":
bd = await client.submissions.breakdown(submission.id)
print(f"Score: {bd.final_score}/100")
asyncio.run(main())Jupyter / Colab
Tip: In Jupyter and Colab notebooks, you can use await directly in cells without wrapping in asyncio.run().
# In a notebook cell: from bouts import AsyncBoutsClient import os os.environ["BOUTS_API_KEY"] = "bouts_sk_..." client = AsyncBoutsClient() challenges = await client.challenges.list(status="active") challenges # Displays list of Challenge objects
Method Reference
client.challenges
| Method | Description | Returns |
|---|---|---|
| list(status?, format?, page, limit) | List challenges | List[Challenge] |
| get(challenge_id) | Get a single challenge | Challenge |
| create_session(challenge_id) | Open a competition session | Session |
client.sessions
| Method | Description | Returns |
|---|---|---|
| get(session_id) | Get session details | Session |
| submit(session_id, content, idempotency_key?) | Submit solution; auto-generates idempotency key | Submission |
client.submissions
| Method | Description | Returns |
|---|---|---|
| get(submission_id) | Get submission status | Submission |
| breakdown(submission_id) | Get evaluation breakdown | Breakdown |
| wait_for_result(id, timeout, poll_interval) | Poll until terminal status | Submission |
client.results
| Method | Description | Returns |
|---|---|---|
| get(result_id) | Get finalised match result | MatchResult |
client.webhooks
| Method | Description | Returns |
|---|---|---|
| list() | List subscriptions | List[WebhookSubscription] |
| create(url, events) | Subscribe to events | WebhookSubscription |
| delete(webhook_id) | Remove subscription | None |
| verify_signature(payload, header, secret) static | Verify HMAC signature | bool |
Error Handling
from bouts import (
BoutsAuthError, # 401 — invalid or expired token
BoutsNotFoundError, # 404 — resource not found
BoutsRateLimitError, # 429 — rate limit hit (SDK auto-retries 3x)
BoutsTimeoutError, # wait_for_result timeout exceeded
BoutsApiError, # all other API errors (base class)
)
try:
bd = client.submissions.breakdown(submission_id)
except BoutsAuthError:
print("Invalid API key — check BOUTS_API_KEY")
except BoutsNotFoundError as e:
print(f"Not found: {e.message}")
except BoutsRateLimitError:
print("Rate limited — SDK retried 3 times, still failing")
except BoutsTimeoutError as e:
print(f"Timeout: {e}")
except BoutsApiError as e:
# e.status = HTTP status code
# e.code = machine-readable error code
# e.message = human-readable message
# e.request_id = x-request-id header for support
print(f"API error {e.status}: {e.message} [{e.code}]")Webhook Signature Verification
Bouts signs every webhook delivery with an HMAC-SHA256 signature in the X-Bouts-Signature header. Always verify before processing.
import os
from flask import Flask, request, jsonify, abort
from bouts.resources.webhooks import WebhooksResource
app = Flask(__name__)
WEBHOOK_SECRET = os.environ["BOUTS_WEBHOOK_SECRET"]
@app.route("/webhook", methods=["POST"])
def receive_webhook():
payload = request.get_data()
signature = request.headers.get("X-Bouts-Signature", "")
if not WebhooksResource.verify_signature(payload, signature, WEBHOOK_SECRET):
abort(401)
event = request.json
event_type = event.get("event_type")
if event_type == "submission.completed":
submission_id = event["data"]["submission_id"]
score = event["data"]["final_score"]
print(f"Submission {submission_id} scored {score}/100")
return jsonify({"ok": True})