outrun-ai 0.1.0__tar.gz

outrun_ai-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.env
+node_modules/

outrun_ai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Outrun LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

outrun_ai-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.5
+Name: outrun-ai
+Version: 0.1.0
+Summary: Python client for the Outrun API (OpenAI-compatible), built on the official OpenAI SDK.
+Project-URL: Homepage, https://outrun.to
+Project-URL: Documentation, https://outrun.to/docs/
+Project-URL: Pricing, https://outrun.to/pricing
+Project-URL: Repository, https://github.com/OutrunAIAPI/outrun-sdk
+Project-URL: Issues, https://github.com/OutrunAIAPI/outrun-sdk/issues
+Author-email: Outrun LLC <support@outrun.to>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,claude,deepseek,gemini,gpt,llm,openai-compatible,outrun,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: openai>=1.55.3
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# outrun-ai (Python)
+
+Python client for the [Outrun API](https://outrun.to). Outrun is a prepaid, OpenAI-compatible API: one key for GPT, Claude, Gemini, Grok, DeepSeek, GLM, Kimi, Qwen and MiniMax models. This package is a thin wrapper over the official `openai` package with the base URL and API key set for you, so everything the OpenAI SDK does still works.
+
+## Install
+
+```bash
+pip install outrun-ai
+```
+
+## Quickstart
+
+Create a key at https://outrun.to/key, then:
+
+```bash
+export OUTRUN_API_KEY="your-key"
+```
+
+```python
+from outrun_ai import Outrun
+
+client = Outrun()  # reads OUTRUN_API_KEY
+print(client.ask("gpt-5.6-terra", "Say hello in five words."))
+print(client.ask("deepseek-v4.1-flash", "Name three prime numbers.", system="Be brief."))
+```
+
+You can also pass `Outrun(api_key="...", base_url="...")`. The default base URL is `https://api.outrun.to/v1`. If no key is found, the client raises `OutrunError`.
+
+## Streaming
+
+```python
+for text in client.ask_stream("deepseek-v4.1-flash", "Write a haiku about rain."):
+    print(text, end="", flush=True)
+```
+
+## Model ids and prices
+
+`prices()` reads the public price list. It needs no key and costs nothing.
+
+```python
+from outrun_ai import prices
+
+for m in prices(kind="text"):
+    tier = m["tiers"][0]
+    print(m["id"], tier["prices"].get("input"), tier["prices"].get("output"), "USD per", tier["unit"])
+```
+
+Each item has `id` (the model name to send), `name`, `family`, `kind` (`text`, `image`, `video` or `audio`), `unit`, `tiers` and `paused`. Paused models are left out unless you pass `include_paused=True`. The same list is at https://outrun.to/pricing.
+
+## Everything else
+
+`Outrun` subclasses `openai.OpenAI`, so the usual calls work unchanged:
+
+```python
+client.chat.completions.create(
+    model="deepseek-v4.1-flash",
+    messages=[{"role": "user", "content": "Hi"}],
+)
+client.models.list()
+```
+
+`AsyncOutrun` is the async version (`await client.ask(...)`, `async for t in client.ask_stream(...)`).
+
+Each API request carries an `X-Outrun-SDK: python/<version>` header. Nothing else is added.
+
+## Links
+
+- Docs: https://outrun.to/docs/
+- LangChain: `pip install langchain-outrun` ([source](https://github.com/OutrunAIAPI/langchain-outrun))
+- Support: support@outrun.to
+
+License: MIT.

outrun_ai-0.1.0/README.md

@@ -0,0 +1,72 @@
+# outrun-ai (Python)
+
+Python client for the [Outrun API](https://outrun.to). Outrun is a prepaid, OpenAI-compatible API: one key for GPT, Claude, Gemini, Grok, DeepSeek, GLM, Kimi, Qwen and MiniMax models. This package is a thin wrapper over the official `openai` package with the base URL and API key set for you, so everything the OpenAI SDK does still works.
+
+## Install
+
+```bash
+pip install outrun-ai
+```
+
+## Quickstart
+
+Create a key at https://outrun.to/key, then:
+
+```bash
+export OUTRUN_API_KEY="your-key"
+```
+
+```python
+from outrun_ai import Outrun
+
+client = Outrun()  # reads OUTRUN_API_KEY
+print(client.ask("gpt-5.6-terra", "Say hello in five words."))
+print(client.ask("deepseek-v4.1-flash", "Name three prime numbers.", system="Be brief."))
+```
+
+You can also pass `Outrun(api_key="...", base_url="...")`. The default base URL is `https://api.outrun.to/v1`. If no key is found, the client raises `OutrunError`.
+
+## Streaming
+
+```python
+for text in client.ask_stream("deepseek-v4.1-flash", "Write a haiku about rain."):
+    print(text, end="", flush=True)
+```
+
+## Model ids and prices
+
+`prices()` reads the public price list. It needs no key and costs nothing.
+
+```python
+from outrun_ai import prices
+
+for m in prices(kind="text"):
+    tier = m["tiers"][0]
+    print(m["id"], tier["prices"].get("input"), tier["prices"].get("output"), "USD per", tier["unit"])
+```
+
+Each item has `id` (the model name to send), `name`, `family`, `kind` (`text`, `image`, `video` or `audio`), `unit`, `tiers` and `paused`. Paused models are left out unless you pass `include_paused=True`. The same list is at https://outrun.to/pricing.
+
+## Everything else
+
+`Outrun` subclasses `openai.OpenAI`, so the usual calls work unchanged:
+
+```python
+client.chat.completions.create(
+    model="deepseek-v4.1-flash",
+    messages=[{"role": "user", "content": "Hi"}],
+)
+client.models.list()
+```
+
+`AsyncOutrun` is the async version (`await client.ask(...)`, `async for t in client.ask_stream(...)`).
+
+Each API request carries an `X-Outrun-SDK: python/<version>` header. Nothing else is added.
+
+## Links
+
+- Docs: https://outrun.to/docs/
+- LangChain: `pip install langchain-outrun` ([source](https://github.com/OutrunAIAPI/langchain-outrun))
+- Support: support@outrun.to
+
+License: MIT.

outrun_ai-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "outrun-ai"
+version = "0.1.0"
+description = "Python client for the Outrun API (OpenAI-compatible), built on the official OpenAI SDK."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Outrun LLC", email = "support@outrun.to" }]
+keywords = ["outrun", "llm", "api", "openai-compatible", "sdk", "gpt", "claude", "gemini", "deepseek"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Typing :: Typed",
+]
+dependencies = ["openai>=1.55.3"]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[project.urls]
+Homepage = "https://outrun.to"
+Documentation = "https://outrun.to/docs/"
+Pricing = "https://outrun.to/pricing"
+Repository = "https://github.com/OutrunAIAPI/outrun-sdk"
+Issues = "https://github.com/OutrunAIAPI/outrun-sdk/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/outrun_ai"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/outrun_ai", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

outrun_ai-0.1.0/src/outrun_ai/__init__.py

@@ -0,0 +1,13 @@
+"""Outrun SDK: a thin wrapper over the OpenAI Python SDK, pointed at the Outrun API."""
+from ._client import DEFAULT_BASE_URL, AsyncOutrun, Outrun, OutrunError, __version__
+from ._prices import PRICING_URL, prices
+
+__all__ = [
+    "Outrun",
+    "AsyncOutrun",
+    "OutrunError",
+    "prices",
+    "DEFAULT_BASE_URL",
+    "PRICING_URL",
+    "__version__",
+]

outrun_ai-0.1.0/src/outrun_ai/_client.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import os
+from typing import Any, AsyncIterator, Iterator, Optional
+
+import openai
+
+__version__ = "0.1.0"
+DEFAULT_BASE_URL = "https://api.outrun.to/v1"
+_HEADER = "X-Outrun-SDK"
+
+
+class OutrunError(openai.OpenAIError):
+    """Raised when the client is misconfigured (for example, no API key)."""
+
+
+def _resolve(api_key: Optional[str], base_url: Optional[str], kwargs: dict) -> tuple:
+    key = api_key or os.environ.get("OUTRUN_API_KEY")
+    if not key:
+        raise OutrunError(
+            "No API key. Pass api_key=... or set the OUTRUN_API_KEY environment variable. "
+            "Get a key at https://outrun.to/key"
+        )
+    headers = {_HEADER: f"python/{__version__}"}
+    headers.update(kwargs.pop("default_headers", None) or {})
+    return key, base_url or DEFAULT_BASE_URL, headers
+
+
+def _messages(prompt: str, system: Optional[str]) -> list:
+    msgs = []
+    if system:
+        msgs.append({"role": "system", "content": system})
+    msgs.append({"role": "user", "content": prompt})
+    return msgs
+
+
+class Outrun(openai.OpenAI):
+    """OpenAI client defaulting to the Outrun API. Everything on openai.OpenAI still works."""
+
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, **kwargs: Any):
+        key, url, headers = _resolve(api_key, base_url, kwargs)
+        super().__init__(api_key=key, base_url=url, default_headers=headers, **kwargs)
+
+    def ask(self, model: str, prompt: str, *, system: Optional[str] = None, **kwargs: Any) -> str:
+        """Send one prompt, return the reply text."""
+        r = self.chat.completions.create(model=model, messages=_messages(prompt, system), **kwargs)
+        return r.choices[0].message.content or ""
+
+    def ask_stream(
+        self, model: str, prompt: str, *, system: Optional[str] = None, **kwargs: Any
+    ) -> Iterator[str]:
+        """Send one prompt, yield reply text as it arrives."""
+        stream = self.chat.completions.create(
+            model=model, messages=_messages(prompt, system), stream=True, **kwargs
+        )
+        for chunk in stream:
+            if chunk.choices and chunk.choices[0].delta.content:
+                yield chunk.choices[0].delta.content
+
+
+class AsyncOutrun(openai.AsyncOpenAI):
+    """Async version of Outrun."""
+
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, **kwargs: Any):
+        key, url, headers = _resolve(api_key, base_url, kwargs)
+        super().__init__(api_key=key, base_url=url, default_headers=headers, **kwargs)
+
+    async def ask(self, model: str, prompt: str, *, system: Optional[str] = None, **kwargs: Any) -> str:
+        r = await self.chat.completions.create(
+            model=model, messages=_messages(prompt, system), **kwargs
+        )
+        return r.choices[0].message.content or ""
+
+    async def ask_stream(
+        self, model: str, prompt: str, *, system: Optional[str] = None, **kwargs: Any
+    ) -> AsyncIterator[str]:
+        stream = await self.chat.completions.create(
+            model=model, messages=_messages(prompt, system), stream=True, **kwargs
+        )
+        async for chunk in stream:
+            if chunk.choices and chunk.choices[0].delta.content:
+                yield chunk.choices[0].delta.content

outrun_ai-0.1.0/src/outrun_ai/_prices.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import json
+import urllib.request
+from typing import Any, Dict, List, Optional
+
+from ._client import OutrunError, __version__
+
+PRICING_URL = "https://api.outrun.to/pricing"
+# The feed's firewall blocks the default "Python-urllib" agent, so send our own.
+_USER_AGENT = f"Mozilla/5.0 (compatible; outrun-ai-python/{__version__}; +https://outrun.to)"
+
+
+def _fetch(url: str, timeout: float) -> Dict[str, Any]:
+    req = urllib.request.Request(
+        url, headers={"User-Agent": _USER_AGENT, "Accept": "application/json"}
+    )
+    with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310 (fixed https URL)
+        return json.loads(resp.read().decode("utf-8"))
+
+
+def prices(
+    kind: Optional[str] = None,
+    *,
+    include_paused: bool = False,
+    timeout: float = 15.0,
+    url: str = PRICING_URL,
+) -> List[Dict[str, Any]]:
+    """Return the public Outrun price list. No API key is needed and nothing is billed.
+
+    Each item is a dict with ``id`` (the model name to send), ``name``, ``family``,
+    ``kind`` (``"text"``, ``"image"``, ``"video"`` or ``"audio"``), ``unit`` and
+    ``tiers`` (a list of ``{"label", "unit", "prices": {"input", "output", ...}}``,
+    prices in USD per ``unit``), plus ``paused`` (bool).
+
+    Args:
+        kind: Only return models of this kind, for example ``"text"``.
+        include_paused: Also return models that are paused right now.
+        timeout: Seconds to wait for the feed.
+        url: Feed URL. Only change this for testing.
+    """
+    try:
+        feed = _fetch(url, timeout)
+    except Exception as exc:  # network, HTTP or JSON errors
+        raise OutrunError(f"Could not read the Outrun price list from {url}: {exc}") from exc
+    if not isinstance(feed, dict) or not isinstance(feed.get("models"), list):
+        raise OutrunError(f"Unexpected price list format from {url}")
+
+    paused = set(feed.get("paused") or [])
+    out = []
+    for model in feed["models"]:
+        if not isinstance(model, dict) or "id" not in model:
+            continue
+        item = dict(model)
+        item["paused"] = item["id"] in paused
+        if item["paused"] and not include_paused:
+            continue
+        if kind is not None and item.get("kind") != kind:
+            continue
+        out.append(item)
+    return out

outrun_ai-0.1.0/tests/test_client.py

@@ -0,0 +1,102 @@
+import json
+
+try:
+    import httpx2 as httpx  # openai 3.x
+except ImportError:  # openai 1.x / 2.x
+    import httpx
+import pytest
+from outrun_ai import AsyncOutrun, Outrun, OutrunError
+
+COMPLETION = {
+    "id": "c1", "object": "chat.completion", "created": 1, "model": "m",
+    "choices": [{"index": 0, "finish_reason": "stop",
+                 "message": {"role": "assistant", "content": "hello there"}}],
+}
+SSE = (
+    'data: {"id":"c","object":"chat.completion.chunk","created":1,"model":"m","choices":[{"index":0,"delta":{"role":"assistant","content":"Hel"}}]}\n\n'
+    'data: {"id":"c","object":"chat.completion.chunk","created":1,"model":"m","choices":[{"index":0,"delta":{"content":"lo"}}]}\n\n'
+    'data: {"id":"c","object":"chat.completion.chunk","created":1,"model":"m","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}\n\n'
+    "data: [DONE]\n\n"
+)
+
+
+def make_handler(seen):
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.append(request)
+        body = json.loads(request.content or b"{}")
+        if body.get("stream"):
+            return httpx.Response(200, headers={"content-type": "text/event-stream"}, content=SSE)
+        return httpx.Response(200, json=COMPLETION)
+    return handler
+
+
+@pytest.fixture(autouse=True)
+def clean_env(monkeypatch):
+    monkeypatch.delenv("OUTRUN_API_KEY", raising=False)
+
+
+def client(seen, **kw):
+    kw.setdefault("api_key", "test-key")
+    return Outrun(http_client=httpx.Client(transport=httpx.MockTransport(make_handler(seen))), **kw)
+
+
+def test_default_base_url():
+    assert str(Outrun(api_key="k").base_url) == "https://api.outrun.to/v1/"
+
+
+def test_custom_base_url():
+    assert str(Outrun(api_key="k", base_url="http://localhost:1/v1").base_url) == "http://localhost:1/v1/"
+
+
+def test_env_key(monkeypatch):
+    monkeypatch.setenv("OUTRUN_API_KEY", "env-key")
+    assert Outrun().api_key == "env-key"
+
+
+def test_missing_key():
+    with pytest.raises(OutrunError):
+        Outrun()
+    with pytest.raises(OutrunError):
+        AsyncOutrun()
+
+
+def test_ask_returns_content_and_sends_system():
+    seen = []
+    c = client(seen)
+    assert c.ask("some-model", "hi", system="be brief") == "hello there"
+    body = json.loads(seen[0].content)
+    assert body["model"] == "some-model"
+    assert body["messages"] == [
+        {"role": "system", "content": "be brief"}, {"role": "user", "content": "hi"}]
+    assert str(seen[0].url) == "https://api.outrun.to/v1/chat/completions"
+    assert seen[0].headers["authorization"] == "Bearer test-key"
+
+
+def test_ask_stream_yields_chunks():
+    seen = []
+    assert list(client(seen).ask_stream("m", "hi")) == ["Hel", "lo"]
+
+
+def test_sdk_header_present_and_overridable():
+    seen = []
+    client(seen).ask("m", "hi")
+    assert seen[0].headers["x-outrun-sdk"] == "python/0.1.0"
+    seen2 = []
+    client(seen2, default_headers={"X-Extra": "1"}).ask("m", "hi")
+    assert seen2[0].headers["x-extra"] == "1"
+    assert seen2[0].headers["x-outrun-sdk"] == "python/0.1.0"
+
+
+def test_openai_chat_attribute_not_shadowed():
+    c = Outrun(api_key="k")
+    assert hasattr(c.chat, "completions")
+    assert hasattr(c, "models") and hasattr(c, "images")
+
+
+async def test_async_ask_and_stream():
+    seen = []
+    c = AsyncOutrun(api_key="k", http_client=httpx.AsyncClient(
+        transport=httpx.MockTransport(make_handler(seen))))
+    assert await c.ask("m", "hi") == "hello there"
+    assert [t async for t in c.ask_stream("m", "hi")] == ["Hel", "lo"]
+    assert seen[0].headers["x-outrun-sdk"] == "python/0.1.0"

outrun_ai-0.1.0/tests/test_prices.py

@@ -0,0 +1,96 @@
+import io
+import json
+import urllib.error
+
+import outrun_ai
+import pytest
+from outrun_ai import OutrunError, _prices, prices
+
+FEED = {
+    "currency": "USD",
+    "generated_at": 1,
+    "paused": ["paused-model"],
+    "models": [
+        {"id": "text-a", "name": "Text A", "family": "f", "kind": "text", "unit": "1M tokens",
+         "tiers": [{"label": "all", "unit": "1M tokens", "prices": {"input": 0.1, "output": 0.4}}]},
+        {"id": "img-b", "name": "Image B", "family": "image", "kind": "image", "unit": "image",
+         "tiers": [{"label": "all", "unit": "image", "prices": {"output": 0.02}}]},
+        {"id": "paused-model", "name": "Paused", "family": "f", "kind": "text", "unit": "1M tokens",
+         "tiers": []},
+    ],
+}
+
+
+class FakeResponse(io.BytesIO):
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+
+@pytest.fixture
+def seen(monkeypatch):
+    """Replace urlopen so no test touches the network; record each request."""
+    calls = []
+
+    def fake_urlopen(req, timeout=None):
+        calls.append((req, timeout))
+        return FakeResponse(json.dumps(FEED).encode())
+
+    monkeypatch.setattr(_prices.urllib.request, "urlopen", fake_urlopen)
+    return calls
+
+
+def test_exported():
+    assert outrun_ai.prices is prices
+    assert outrun_ai.PRICING_URL == "https://api.outrun.to/pricing"
+
+
+def test_returns_active_models_with_paused_flag(seen):
+    out = prices()
+    assert [m["id"] for m in out] == ["text-a", "img-b"]
+    assert all(m["paused"] is False for m in out)
+    assert out[0]["tiers"][0]["prices"]["output"] == 0.4
+
+
+def test_kind_filter_and_include_paused(seen):
+    assert [m["id"] for m in prices("text")] == ["text-a"]
+    both = prices(kind="text", include_paused=True)
+    assert [(m["id"], m["paused"]) for m in both] == [("text-a", False), ("paused-model", True)]
+
+
+def test_request_url_user_agent_and_timeout(seen):
+    prices(timeout=3)
+    req, timeout = seen[0]
+    assert req.full_url == "https://api.outrun.to/pricing"
+    assert timeout == 3
+    ua = req.get_header("User-agent")
+    assert ua.startswith("Mozilla/5.0") and "outrun-ai-python/" in ua
+    assert "Python-urllib" not in ua
+
+
+def test_does_not_mutate_or_need_a_key(seen, monkeypatch):
+    monkeypatch.delenv("OUTRUN_API_KEY", raising=False)
+    prices()
+    req, _ = seen[0]
+    assert req.get_header("Authorization") is None
+    assert "paused" not in FEED["models"][0]
+
+
+def test_network_error_becomes_outrun_error(monkeypatch):
+    def boom(req, timeout=None):
+        raise urllib.error.HTTPError(req.full_url, 403, "Forbidden", None, None)
+
+    monkeypatch.setattr(_prices.urllib.request, "urlopen", boom)
+    with pytest.raises(OutrunError, match="price list"):
+        prices()
+
+
+def test_bad_format_becomes_outrun_error(monkeypatch):
+    monkeypatch.setattr(
+        _prices.urllib.request, "urlopen",
+        lambda req, timeout=None: FakeResponse(b'{"unexpected": true}'),
+    )
+    with pytest.raises(OutrunError, match="format"):
+        prices()