aiarbitration 0.1.0

Python SDK for the AIArbitration intelligent AI model router

aiarbitration · Python SDK

Intelligent AI model routing for Python applications.
AIArbitration selects the best model for every request — balancing cost, latency, capability, and compliance — and falls back automatically on failure.

pip install aiarbitration

Requires Python 3.11+.

---

Quick start

from aiarbitration import AIArbitrationClient

# Option A — supply a JWT obtained from your login flow
client = AIArbitrationClient(
    base_url="https://api.theaiarbitration.com",
    api_key="<your-jwt-token>",
)

# Option B — let the SDK authenticate for you
client = AIArbitrationClient.login(
    base_url="https://api.theaiarbitration.com",
    email="[e-mail]",
    password="s3cr3t",
)

response = client.execute("Explain quantum entanglement in one sentence.")
print(response.content)
# → "Quantum entanglement is a phenomenon where two particles ..."
print(f"Model: {response.model_used}  Cost: ${response.cost:.6f}")

---

Streaming

for chunk in client.stream("Write a short poem about the ocean."):
    print(chunk.content, end="", flush=True)
    if chunk.is_done:
        break

Async streaming

import asyncio
from aiarbitration import AIArbitrationClient

async def main():
    client = AIArbitrationClient(base_url="...", api_key="...")
    async for chunk in client.stream_async("Tell me about black holes."):
        print(chunk.content, end="", flush=True)

asyncio.run(main())

---

Structured request

from aiarbitration import AIArbitrationClient, ChatRequest, ChatMessage

request = ChatRequest(
    messages=[
        ChatMessage.system("You are a concise technical assistant."),
        ChatMessage.user("What is a transformer model?"),
    ],
    task_type="general",
    max_cost_usd=0.05,          # reject models over $0.05 for this request
    required_region="eu-west-1" # GDPR: EU-only providers
)

response = client.execute(request)

---

Cost estimate (dry run)

estimate = client.estimate("Summarise this 10,000-word document.")
print(f"Selected model : {estimate.selected_model.model_id}")
print(f"Estimated cost : ${estimate.estimated_cost:.6f}")
print(f"Candidates     : {len(estimate.all_candidates)}")

---

Image generation

from aiarbitration import ImageGenerationRequest

result = client.generate_image(ImageGenerationRequest(
    prompt="Futuristic smart city at golden hour, photorealistic",
    size="1024x1024",
))
print(result.image_url)

---

Batch execution

from aiarbitration import ChatRequest, ChatMessage

requests = [
    ChatRequest(messages=[ChatMessage.user(q)])
    for q in ["What is Python?", "What is Rust?", "What is Go?"]
]

batch = client.execute_batch(requests)
print(f"Success rate: {batch.success_rate:.0%}  Total cost: ${batch.total_cost:.6f}")
for r in batch.successful_responses:
    print(r.content[:80])

---

List available models

models = client.get_models(vision=True, tier="flagship")
for m in models:
    print(f"{m.display_name:30}  {m.context_window:,} ctx  ${m.cost_per_million_input_tokens}/M")

---

Drop-in OpenAI replacement

AIArbitration exposes an OpenAI-compatible endpoint at /v1.
Point the official OpenAI SDK at it and your existing code works unchanged:

import openai

openai.base_url = "https://api.theaiarbitration.com/v1"
openai.api_key  = "<your-jwt-token>"

response = openai.chat.completions.create(
    model="arbitrated",  # let the engine choose, or pin a specific model
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

---

Error handling

from aiarbitration import (
    AIArbitrationError,
    AuthenticationError,
    BudgetExceededError,
    RateLimitError,
    ServiceUnavailableError,
)

try:
    response = client.execute("...")
except AuthenticationError:
    print("Invalid or expired token — re-authenticate.")
except RateLimitError:
    print("Quota reached — upgrade your plan.")
except BudgetExceededError:
    print("Request cost would exceed your budget cap.")
except ServiceUnavailableError:
    print("All models are currently unavailable — try again shortly.")
except AIArbitrationError as e:
    print(f"API error {e.status_code}: {e}")

---

Configuration reference

Parameter	Default	Description
base_url	—	API base URL (required)
api_key	None	JWT bearer token
timeout	120.0	Request timeout in seconds
streaming_timeout	300.0	Streaming request timeout in seconds

---

Links

• API reference
• GitHub
• .NET SDK on NuGet