relay-ai-sdk 2.0.0__tar.gz

relay_ai_sdk-2.0.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/relay-ai-sdk
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

relay_ai_sdk-2.0.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.reviewer/

relay_ai_sdk-2.0.0/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: relay-ai-sdk
+Version: 2.0.0
+Summary: Official Python SDK for the Relay AI Gateway. One key, every model.
+Project-URL: Homepage, https://relay.ai5labs.com
+Project-URL: Documentation, https://relay.ai5labs.com/docs/sdk
+Project-URL: Repository, https://github.com/ai5labs/relay-sdk
+Author-email: ai5labs <relay@ai5labs.com>
+License-Expression: MIT
+Keywords: ai,ai-gateway,llm,multi-model,opentelemetry,relay,sdk,streaming,tool-calling
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.27; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.27; extra == 'otel'
+Description-Content-Type: text/markdown
+
+# Relay AI SDK
+
+Official Python SDK for the [Relay AI Gateway](https://relay.ai5labs.com). One key, every model.
+
+```bash
+pip install relay-ai-sdk
+```
+
+With OpenTelemetry:
+
+```bash
+pip install relay-ai-sdk[otel]
+```
+
+## Quick start
+
+```python
+from relay_ai import Relay
+
+client = Relay(api_key="sk-relay-...")
+
+response = client.chat("claude-sonnet-4.6", messages=[
+    {"role": "user", "content": "Explain quantum computing in one sentence."}
+])
+print(response.text)
+print(f"Tokens: {response.usage.total_tokens}")
+```
+
+## Streaming
+
+```python
+with client.chat("gemini-3.5-flash", messages=[
+    {"role": "user", "content": "Write a haiku about code."}
+], stream=True) as stream:
+    for chunk in stream:
+        print(chunk.text, end="", flush=True)
+
+    final = stream.get_final_response()
+    print(f"\nTokens: {final.usage.total_tokens}")
+```
+
+## Async
+
+```python
+from relay_ai import AsyncRelay
+
+async with AsyncRelay() as client:
+    response = await client.chat("claude-opus-4.8", messages=[
+        {"role": "user", "content": "Hello!"}
+    ])
+    print(response.text)
+```
+
+## Tool calling
+
+```python
+tools = [{
+    "type": "function",
+    "function": {
+        "name": "get_weather",
+        "description": "Get current weather",
+        "parameters": {
+            "type": "object",
+            "properties": {"city": {"type": "string"}},
+            "required": ["city"],
+        },
+    },
+}]
+
+response = client.chat("claude-sonnet-4.6", messages=[
+    {"role": "user", "content": "What's the weather in Tokyo?"}
+], tools=tools)
+
+for tc in response.tool_calls:
+    print(f"{tc.function_name}({tc.function_arguments})")
+```
+
+## Image generation
+
+```python
+result = client.images("flux-schnell", prompt="A cat astronaut on Mars")
+print(result.images[0])
+```
+
+## Audio
+
+```python
+# Transcription
+transcript = client.transcribe("whisper-1", "meeting.mp3")
+print(transcript.text)
+
+# Text-to-speech
+audio = client.speech("tts-1", "Hello from Relay!")
+with open("output.mp3", "wb") as f:
+    f.write(audio.audio)
+```
+
+## Semantic routing
+
+```python
+decision = client.route(
+    messages=[{"role": "user", "content": "Prove the Riemann hypothesis"}],
+    candidates=["claude-opus-4.8", "claude-sonnet-4.6", "gemini-3.5-flash"],
+)
+print(f"Best model: {decision.alias} ({decision.confidence:.0%})")
+print(f"Reasoning: {decision.reasoning}")
+```
+
+## Batch processing
+
+```python
+results = client.batch("claude-sonnet-4.6", [
+    {"messages": [{"role": "user", "content": "What is 2+2?"}]},
+    {"messages": [{"role": "user", "content": "What is 3+3?"}]},
+    {"messages": [{"role": "user", "content": "What is 4+4?"}]},
+], max_concurrent=5)
+
+for r in results:
+    if r.response:
+        print(f"[{r.index}] {r.response.text}")
+    else:
+        print(f"[{r.index}] Error: {r.error}")
+```
+
+## Credits
+
+```python
+state = client.credits()
+print(f"Balance: ${state.balance_cents / 100:.2f}")
+```
+
+## Error handling
+
+```python
+from relay_ai import (
+    RelayError,
+    AuthenticationError,
+    RateLimitError,
+    InsufficientCreditsError,
+    ModelNotFoundError,
+)
+
+try:
+    response = client.chat("gpt-5", messages=[...])
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after}s")
+except InsufficientCreditsError:
+    print("Top up your credits at relay.ai5labs.com")
+except ModelNotFoundError:
+    print("Model not found")
+except RelayError as e:
+    print(f"Error: {e.message}")
+```
+
+## CLI
+
+```bash
+export RELAY_API_KEY=sk-relay-...
+
+relay models                                # List models
+relay chat claude-sonnet-4.6 "Hello!"       # Quick chat
+relay chat gemini-3.5-flash "Hi" --stream   # Stream tokens
+relay credits                               # Check balance
+relay version                               # SDK version
+```
+
+## Configuration
+
+```python
+client = Relay(
+    api_key="sk-relay-...",       # or set RELAY_API_KEY env var
+    base_url="https://...",       # custom gateway URL
+    timeout=120.0,                # request timeout (seconds)
+    max_retries=2,                # automatic retries on 429/5xx
+    send_telemetry=True,          # usage analytics (metadata only)
+    http_client=httpx.Client(),   # custom httpx client
+)
+```
+
+## Telemetry
+
+The SDK sends anonymous usage metadata (model, token counts, latency) to improve the service. **No message content, prompts, responses, or tool arguments are ever transmitted.** This is enforced by a client-side allowlist and verified by server-side stripping.
+
+Disable with:
+
+```python
+client = Relay(send_telemetry=False)
+```
+
+## OpenTelemetry
+
+```python
+from relay_ai import Relay
+from relay_ai._otel import instrument, RelaySpanExporter
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+provider = TracerProvider()
+provider.add_span_processor(
+    BatchSpanProcessor(
+        RelaySpanExporter(api_key="sk-relay-...", base_url="https://api.relay.ai5labs.com/v1")
+    )
+)
+
+client = instrument(Relay())
+response = client.chat(...)  # Automatically creates OTel spans
+```
+
+## License
+
+MIT

relay_ai_sdk-2.0.0/README.md

@@ -0,0 +1,213 @@
+# Relay AI SDK
+
+Official Python SDK for the [Relay AI Gateway](https://relay.ai5labs.com). One key, every model.
+
+```bash
+pip install relay-ai-sdk
+```
+
+With OpenTelemetry:
+
+```bash
+pip install relay-ai-sdk[otel]
+```
+
+## Quick start
+
+```python
+from relay_ai import Relay
+
+client = Relay(api_key="sk-relay-...")
+
+response = client.chat("claude-sonnet-4.6", messages=[
+    {"role": "user", "content": "Explain quantum computing in one sentence."}
+])
+print(response.text)
+print(f"Tokens: {response.usage.total_tokens}")
+```
+
+## Streaming
+
+```python
+with client.chat("gemini-3.5-flash", messages=[
+    {"role": "user", "content": "Write a haiku about code."}
+], stream=True) as stream:
+    for chunk in stream:
+        print(chunk.text, end="", flush=True)
+
+    final = stream.get_final_response()
+    print(f"\nTokens: {final.usage.total_tokens}")
+```
+
+## Async
+
+```python
+from relay_ai import AsyncRelay
+
+async with AsyncRelay() as client:
+    response = await client.chat("claude-opus-4.8", messages=[
+        {"role": "user", "content": "Hello!"}
+    ])
+    print(response.text)
+```
+
+## Tool calling
+
+```python
+tools = [{
+    "type": "function",
+    "function": {
+        "name": "get_weather",
+        "description": "Get current weather",
+        "parameters": {
+            "type": "object",
+            "properties": {"city": {"type": "string"}},
+            "required": ["city"],
+        },
+    },
+}]
+
+response = client.chat("claude-sonnet-4.6", messages=[
+    {"role": "user", "content": "What's the weather in Tokyo?"}
+], tools=tools)
+
+for tc in response.tool_calls:
+    print(f"{tc.function_name}({tc.function_arguments})")
+```
+
+## Image generation
+
+```python
+result = client.images("flux-schnell", prompt="A cat astronaut on Mars")
+print(result.images[0])
+```
+
+## Audio
+
+```python
+# Transcription
+transcript = client.transcribe("whisper-1", "meeting.mp3")
+print(transcript.text)
+
+# Text-to-speech
+audio = client.speech("tts-1", "Hello from Relay!")
+with open("output.mp3", "wb") as f:
+    f.write(audio.audio)
+```
+
+## Semantic routing
+
+```python
+decision = client.route(
+    messages=[{"role": "user", "content": "Prove the Riemann hypothesis"}],
+    candidates=["claude-opus-4.8", "claude-sonnet-4.6", "gemini-3.5-flash"],
+)
+print(f"Best model: {decision.alias} ({decision.confidence:.0%})")
+print(f"Reasoning: {decision.reasoning}")
+```
+
+## Batch processing
+
+```python
+results = client.batch("claude-sonnet-4.6", [
+    {"messages": [{"role": "user", "content": "What is 2+2?"}]},
+    {"messages": [{"role": "user", "content": "What is 3+3?"}]},
+    {"messages": [{"role": "user", "content": "What is 4+4?"}]},
+], max_concurrent=5)
+
+for r in results:
+    if r.response:
+        print(f"[{r.index}] {r.response.text}")
+    else:
+        print(f"[{r.index}] Error: {r.error}")
+```
+
+## Credits
+
+```python
+state = client.credits()
+print(f"Balance: ${state.balance_cents / 100:.2f}")
+```
+
+## Error handling
+
+```python
+from relay_ai import (
+    RelayError,
+    AuthenticationError,
+    RateLimitError,
+    InsufficientCreditsError,
+    ModelNotFoundError,
+)
+
+try:
+    response = client.chat("gpt-5", messages=[...])
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after}s")
+except InsufficientCreditsError:
+    print("Top up your credits at relay.ai5labs.com")
+except ModelNotFoundError:
+    print("Model not found")
+except RelayError as e:
+    print(f"Error: {e.message}")
+```
+
+## CLI
+
+```bash
+export RELAY_API_KEY=sk-relay-...
+
+relay models                                # List models
+relay chat claude-sonnet-4.6 "Hello!"       # Quick chat
+relay chat gemini-3.5-flash "Hi" --stream   # Stream tokens
+relay credits                               # Check balance
+relay version                               # SDK version
+```
+
+## Configuration
+
+```python
+client = Relay(
+    api_key="sk-relay-...",       # or set RELAY_API_KEY env var
+    base_url="https://...",       # custom gateway URL
+    timeout=120.0,                # request timeout (seconds)
+    max_retries=2,                # automatic retries on 429/5xx
+    send_telemetry=True,          # usage analytics (metadata only)
+    http_client=httpx.Client(),   # custom httpx client
+)
+```
+
+## Telemetry
+
+The SDK sends anonymous usage metadata (model, token counts, latency) to improve the service. **No message content, prompts, responses, or tool arguments are ever transmitted.** This is enforced by a client-side allowlist and verified by server-side stripping.
+
+Disable with:
+
+```python
+client = Relay(send_telemetry=False)
+```
+
+## OpenTelemetry
+
+```python
+from relay_ai import Relay
+from relay_ai._otel import instrument, RelaySpanExporter
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+provider = TracerProvider()
+provider.add_span_processor(
+    BatchSpanProcessor(
+        RelaySpanExporter(api_key="sk-relay-...", base_url="https://api.relay.ai5labs.com/v1")
+    )
+)
+
+client = instrument(Relay())
+response = client.chat(...)  # Automatically creates OTel spans
+```
+
+## License
+
+MIT

relay_ai_sdk-2.0.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "relay-ai-sdk"
+version = "2.0.0"
+description = "Official Python SDK for the Relay AI Gateway. One key, every model."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "ai5labs", email = "relay@ai5labs.com" }]
+keywords = [
+    "llm", "ai", "relay", "ai-gateway", "multi-model", "sdk",
+    "streaming", "tool-calling", "opentelemetry",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.25.0",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+otel = [
+    "opentelemetry-api>=1.27",
+    "opentelemetry-sdk>=1.27",
+]
+
+[project.scripts]
+relay = "relay_ai._cli:main"
+
+[project.urls]
+Homepage = "https://relay.ai5labs.com"
+Documentation = "https://relay.ai5labs.com/docs/sdk"
+Repository = "https://github.com/ai5labs/relay-sdk"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/relay_ai"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "ruff>=0.6",
+    "mypy>=1.11",
+]

relay_ai_sdk-2.0.0/src/relay_ai/__init__.py

@@ -0,0 +1,85 @@
+"""Relay AI SDK — one key, every model.
+
+Usage::
+
+    from relay_ai import Relay
+
+    client = Relay(api_key="sk-relay-...")
+    response = client.chat("claude-sonnet-4.6", messages=[
+        {"role": "user", "content": "Hello!"}
+    ])
+    print(response.text)
+"""
+
+from relay_ai._client import AsyncRelay, Relay
+from relay_ai._errors import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    ContentPolicyError,
+    ContextWindowError,
+    InsufficientCreditsError,
+    InternalServerError,
+    ModelNotFoundError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    RelayError,
+)
+from relay_ai._streaming import AsyncStream, Stream
+from relay_ai._types import (
+    AudioResponse,
+    BatchResult,
+    ChatResponse,
+    CreditState,
+    ImageResponse,
+    RouteAlternate,
+    RouteResponse,
+    SpeechResponse,
+    StreamChunk,
+    ToolCall,
+    ToolCallDelta,
+    Usage,
+)
+from relay_ai._version import __version__
+
+__all__ = [
+    # Version
+    "__version__",
+    # Clients
+    "Relay",
+    "AsyncRelay",
+    # Streaming
+    "Stream",
+    "AsyncStream",
+    # Response types
+    "ChatResponse",
+    "StreamChunk",
+    "ImageResponse",
+    "AudioResponse",
+    "SpeechResponse",
+    "RouteResponse",
+    "RouteAlternate",
+    "CreditState",
+    "BatchResult",
+    "Usage",
+    "ToolCall",
+    "ToolCallDelta",
+    # Errors
+    "RelayError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIStatusError",
+    "AuthenticationError",
+    "InsufficientCreditsError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ModelNotFoundError",
+    "RateLimitError",
+    "BadRequestError",
+    "ContentPolicyError",
+    "ContextWindowError",
+    "InternalServerError",
+]

relay_ai_sdk-2.0.0/src/relay_ai/_batch.py

@@ -0,0 +1,62 @@
+"""Batch processing — concurrent fan-out through the gateway."""
+
+from __future__ import annotations
+
+import asyncio
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import TYPE_CHECKING, Any
+
+from relay_ai._types import BatchResult
+
+if TYPE_CHECKING:
+    from relay_ai._client import AsyncRelay, Relay
+
+
+def batch_sync(
+    client: Relay,
+    model: str,
+    requests: list[dict[str, Any]],
+    *,
+    max_concurrent: int = 10,
+) -> list[BatchResult]:
+    """Fan out *requests* through ``client.chat()`` using a thread pool."""
+    results: list[BatchResult | None] = [None] * len(requests)
+
+    def _one(idx: int, req: dict[str, Any]) -> BatchResult:
+        try:
+            resp = client.chat(model, **req)
+            return BatchResult(index=idx, response=resp)  # type: ignore[arg-type]
+        except Exception as exc:
+            return BatchResult(index=idx, error=str(exc))
+
+    workers = min(max_concurrent, len(requests)) or 1
+    with ThreadPoolExecutor(max_workers=workers) as pool:
+        futures = {pool.submit(_one, i, r): i for i, r in enumerate(requests)}
+        for future in as_completed(futures):
+            result = future.result()
+            results[result.index] = result
+
+    return [r for r in results if r is not None]
+
+
+async def batch_async(
+    client: AsyncRelay,
+    model: str,
+    requests: list[dict[str, Any]],
+    *,
+    max_concurrent: int = 10,
+) -> list[BatchResult]:
+    """Fan out *requests* through ``client.chat()`` using an asyncio semaphore."""
+    sem = asyncio.Semaphore(max_concurrent)
+
+    async def _one(idx: int, req: dict[str, Any]) -> BatchResult:
+        async with sem:
+            try:
+                resp = await client.chat(model, **req)
+                return BatchResult(index=idx, response=resp)  # type: ignore[arg-type]
+            except Exception as exc:
+                return BatchResult(index=idx, error=str(exc))
+
+    tasks = [_one(i, r) for i, r in enumerate(requests)]
+    results = await asyncio.gather(*tasks)
+    return sorted(results, key=lambda r: r.index)