orth 0.1.0__py3-none-any.whl

orth-0.1.0.dist-info/METADATA

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: orth
+Version: 0.1.0
+Summary: Python SDK to call any API on the Orthogonal platform
+Project-URL: Homepage, https://orthogonal.sh
+Project-URL: Repository, https://github.com/orthogonal-sh/python
+Project-URL: Issues, https://github.com/orthogonal-sh/python/issues
+Author-email: Orthogonal <founders@orthogonal.sh>
+License: MIT License
+        
+        Copyright (c) 2026 Orthogonal
+        
+        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.
+License-File: LICENSE
+Keywords: ai-agents,api,orthogonal,payments,sdk,x402
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.24
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# Orthogonal Python SDK
+
+**Python SDK for calling APIs on the [Orthogonal](https://orthogonal.com) platform.**
+
+Call any API on the Orthogonal platform through one client and one credit balance — authentication, routing, and billing are handled for you.
+
+[![python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+</div>
+
+## Table of Contents
+
+- [Why Orthogonal](#why-orthogonal)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Authentication](#authentication)
+- [Usage](#usage)
+- [Async Usage](#async-usage)
+- [Error Handling](#error-handling)
+- [API Reference](#api-reference)
+- [Related](#related)
+- [License](#license)
+
+## Why Orthogonal
+
+Orthogonal puts a catalog of APIs behind one account and one balance:
+
+- **One integration** — call any API on the platform through a single `run()` method.
+- **Pay per use** — a single credit balance instead of juggling dozens of provider subscriptions.
+- **Sync and async** — a blocking `Orthogonal` client and an `await`-able `AsyncOrthogonal`, both usable as context managers.
+- **Typed** — `RunOptions` / `RunResponse` typed dicts and full type hints.
+
+## Installation
+
+Requires **Python 3.9+**.
+
+```bash
+pip install orth
+```
+
+## Quick Start
+
+```python
+import os
+from orthogonal import Orthogonal
+
+with Orthogonal(api_key=os.environ["ORTHOGONAL_API_KEY"]) as orthogonal:
+    res = orthogonal.run(
+        api="tavily",
+        path="/search",
+        query={"query": "latest AI news"},
+    )
+
+print(res["data"])   # the upstream API's response
+print(res["price"])  # amount charged, e.g. "0.01"
+```
+
+Get an API key from your [Orthogonal dashboard](https://orthogonal.com/dashboard).
+
+## Authentication
+
+Pass your key to the constructor (reading it from the environment keeps keys out of source):
+
+```python
+orthogonal = Orthogonal(api_key=os.environ["ORTHOGONAL_API_KEY"])
+```
+
+## Usage
+
+### GET request (query params)
+
+```python
+res = orthogonal.run(
+    api="fantastic-jobs",
+    path="/v1/active-ats",
+    query={"time_frame": "1h", "limit": 10},
+)
+```
+
+### POST request (JSON body)
+
+```python
+res = orthogonal.run(
+    api="some-api",
+    path="/v1/generate",
+    body={"prompt": "a red bicycle"},
+)
+```
+
+### Options dict instead of keyword arguments
+
+```python
+res = orthogonal.run({
+    "api": "tavily",
+    "path": "/search",
+    "query": {"query": "hello world"},
+})
+```
+
+### Custom headers
+
+Headers passed to the constructor are sent on every request:
+
+```python
+orthogonal = Orthogonal(
+    api_key=os.environ["ORTHOGONAL_API_KEY"],
+    headers={"x-my-trace-id": "abc123"},
+)
+```
+
+## Async Usage
+
+`AsyncOrthogonal` mirrors the sync client with `await` and `async with`:
+
+```python
+import asyncio
+from orthogonal import AsyncOrthogonal
+
+async def main():
+    async with AsyncOrthogonal(api_key=os.environ["ORTHOGONAL_API_KEY"]) as orthogonal:
+        res = await orthogonal.run(
+            api="tavily",
+            path="/search",
+            query={"query": "orthogonal"},
+        )
+        print(res["data"])
+
+asyncio.run(main())
+```
+
+## Error Handling
+
+`run()` returns the response on success and raises **`OrthogonalError`** on any non-2xx response (invalid key, insufficient credits, or an upstream/validation error). The message describes what went wrong.
+
+```python
+from orthogonal import Orthogonal, OrthogonalError
+
+try:
+    res = orthogonal.run(api="tavily", path="/search", query={"query": "x"})
+except OrthogonalError as err:
+    print(f"request failed: {err}")
+```
+
+## API Reference
+
+### `Orthogonal(api_key, *, headers=None, base_url=...)`
+
+| Argument | Type | Description |
+| --- | --- | --- |
+| `api_key` | `str` | **Required.** Your Orthogonal API key (`orth_live_…` / `orth_test_…`). |
+| `headers` | `Mapping[str, str] \| None` | Optional headers sent on every request. |
+| `base_url` | `str` | Override the API base URL (advanced). |
+
+### `orthogonal.run(options=None, *, api, path, query=None, body=None)` → `RunResponse`
+
+Call an endpoint. Pass **either** an `options` dict **or** keyword arguments (not both).
+
+| Argument | Type | Description |
+| --- | --- | --- |
+| `api` | `str` | **Required.** The API slug (e.g. `"tavily"`). |
+| `path` | `str` | **Required.** The endpoint path (e.g. `"/search"`). |
+| `query` | `Mapping[str, JSONValue]` | Query parameters. |
+| `body` | `Mapping[str, JSONValue]` | Request body for POST/PUT/PATCH. |
+
+**`RunResponse`** (a `TypedDict`)
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `success` | `bool` | Whether the call succeeded. |
+| `price` | `str` | Amount charged in USD (e.g. `"0.01"`). |
+| `data` | `JSONValue` | The upstream API's response. |
+
+### `AsyncOrthogonal(...)`
+
+Same constructor and `run(...)` signature as `Orthogonal`, but `run()` is a coroutine (`await`) and the client supports `async with` / `await client.close()`.
+
+### `OrthogonalError`
+
+Raised by `run()` on a non-2xx response. Subclass of `Exception`; `str(err)` is a human-readable message.
+
+Both clients are context managers — use `with` / `async with` (or call `close()`) so the underlying HTTP connection is released.
+
+## Related
+
+- **[`@orth/cli`](https://www.npmjs.com/package/@orth/cli)** — the Orthogonal command-line tool.
+- **[`@orth/sdk`](https://www.npmjs.com/package/@orth/sdk)** — the official TypeScript/JavaScript SDK.
+
+## License
+
+[MIT](./LICENSE) © Orthogonal

orth-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+orthogonal/__init__.py,sha256=OmB4k6rFi6N77peIvfUkqcb-4A_xihdUKLHNKN2ouRU,346
+orthogonal/_client.py,sha256=PWJzg_y2tnOwcK4NEWuVyWDUL2-ZwRxlwxiv8Q634lc,7424
+orthogonal/_exceptions.py,sha256=aAosaAev8MKGgsFQrUipXAV2U0jckb1uBRx9F0xHEys,143
+orthogonal/_types.py,sha256=aZlTbysfTM14kxxn4iB2pc463tLvTrgBTmOIeMkBXcI,607
+orthogonal/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+orth-0.1.0.dist-info/METADATA,sha256=uTFP1UUx_HwQAVI4Vk8-q_Z3LmgT3pH5w-NDsNp_3CY,7920
+orth-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+orth-0.1.0.dist-info/licenses/LICENSE,sha256=lJVAB8xpPTFoafV6eUIwECKM7CAaR1uBX-iRQ4TigiA,1067
+orth-0.1.0.dist-info/RECORD,,

orth-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

orth-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orthogonal
+
+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.

orthogonal/__init__.py

@@ -0,0 +1,16 @@
+"""Python client for the Orthogonal API."""
+
+from ._client import AsyncOrthogonal, Orthogonal
+from ._exceptions import OrthogonalError
+from ._types import JSONValue, RunOptions, RunResponse
+
+__all__ = [
+    "AsyncOrthogonal",
+    "JSONValue",
+    "Orthogonal",
+    "OrthogonalError",
+    "RunOptions",
+    "RunResponse",
+]
+
+__version__ = "0.1.0"

orthogonal/_client.py

@@ -0,0 +1,224 @@
+"""HTTP clients for the Orthogonal API."""
+
+from __future__ import annotations
+
+import json
+import math
+from typing import Any, Dict, Mapping, Optional, Union, cast
+
+import httpx
+
+from ._exceptions import OrthogonalError
+from ._types import JSONValue, RunOptions, RunResponse
+
+VERSION = "0.1.0"
+BASE_URL = "https://api.orth.sh"
+_RUN_PATH = "/v1/run"
+_INVALID_API_KEY = "Invalid API key. Visit https://orthogonal.sh to get one!"
+_INSUFFICIENT_FUNDS = "Insufficient funds. Add USDC at https://orthogonal.sh"
+
+
+def _js_truthy(value: Any) -> bool:
+    """Return JavaScript-like truthiness for values found in API responses."""
+
+    if value is None or value is False:
+        return False
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return value != 0 and not (isinstance(value, float) and math.isnan(value))
+    if isinstance(value, str):
+        return bool(value)
+    return True
+
+
+def _format_error(raw: Any, status: int) -> str:
+    fallback = f"Request failed with status {status}"
+    if raw is None:
+        return fallback
+    if isinstance(raw, str):
+        return raw or fallback
+    if isinstance(raw, Mapping):
+        message = raw.get("message")
+        if isinstance(message, str) and message:
+            return message
+        error = raw.get("error")
+        if isinstance(error, str) and error:
+            return error
+    if isinstance(raw, (Mapping, list)):
+        try:
+            encoded = json.dumps(raw, separators=(",", ":"), ensure_ascii=False)
+        except (TypeError, ValueError, OverflowError):
+            return fallback
+        return encoded if encoded not in {"{}", "[]", "null"} else fallback
+    if isinstance(raw, bool):
+        return "true" if raw else "false"
+    return str(raw)
+
+
+def _error_from_response(response: httpx.Response, data: Any) -> OrthogonalError:
+    if response.status_code == 401:
+        return OrthogonalError(_INVALID_API_KEY)
+    if response.status_code == 402:
+        return OrthogonalError(_INSUFFICIENT_FUNDS)
+
+    nested_error: Any = None
+    top_level_error: Any = None
+    if isinstance(data, Mapping):
+        nested = data.get("data")
+        if isinstance(nested, Mapping):
+            nested_error = nested.get("error")
+        top_level_error = data.get("error")
+
+    raw_error = nested_error if _js_truthy(nested_error) else top_level_error
+    return OrthogonalError(_format_error(raw_error, response.status_code))
+
+
+def _headers(api_key: str, custom_headers: Optional[Mapping[str, str]]) -> Dict[str, str]:
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+        "User-Agent": f"orthogonal-python/{VERSION}",
+        "X-Orthogonal-Source": "sdk",
+    }
+    if custom_headers:
+        headers.update(custom_headers)
+    return headers
+
+
+def _payload(
+    api: str,
+    path: str,
+    query: Optional[Mapping[str, JSONValue]],
+    body: Optional[Mapping[str, JSONValue]],
+) -> Dict[str, Any]:
+    payload: Dict[str, Any] = {"api": api, "path": path}
+    if query is not None:
+        payload["query"] = dict(query)
+    if body is not None:
+        payload["body"] = dict(body)
+    return payload
+
+
+class Orthogonal:
+    """Synchronous client for calling APIs on the Orthogonal platform."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        headers: Optional[Mapping[str, str]] = None,
+        base_url: str = BASE_URL,
+        timeout: Union[float, httpx.Timeout, None] = 30.0,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("Orthogonal API key is required")
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(timeout=timeout)
+        self._url = f"{base_url.rstrip('/')}{_RUN_PATH}"
+        self._headers = _headers(api_key, headers)
+
+    def run(
+        self,
+        options: Optional[RunOptions] = None,
+        *,
+        api: Optional[str] = None,
+        path: Optional[str] = None,
+        query: Optional[Mapping[str, JSONValue]] = None,
+        body: Optional[Mapping[str, JSONValue]] = None,
+    ) -> RunResponse:
+        """Call an API through Orthogonal."""
+
+        if options is not None:
+            if api is not None or path is not None or query is not None or body is not None:
+                raise TypeError("Pass either options or keyword arguments, not both")
+            api = options["api"]
+            path = options["path"]
+            query = options.get("query")
+            body = options.get("body")
+        if api is None or path is None:
+            raise TypeError("run() requires 'api' and 'path'")
+
+        response = self._client.post(
+            self._url,
+            headers=self._headers,
+            json=_payload(api, path, query, body),
+        )
+        data = response.json()
+        if not response.is_success:
+            raise _error_from_response(response, data)
+        return cast(RunResponse, data)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client when it is SDK-owned."""
+
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> Orthogonal:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+class AsyncOrthogonal:
+    """Asynchronous client for calling APIs on the Orthogonal platform."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        headers: Optional[Mapping[str, str]] = None,
+        base_url: str = BASE_URL,
+        timeout: Union[float, httpx.Timeout, None] = 30.0,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("Orthogonal API key is required")
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(timeout=timeout)
+        self._url = f"{base_url.rstrip('/')}{_RUN_PATH}"
+        self._headers = _headers(api_key, headers)
+
+    async def run(
+        self,
+        options: Optional[RunOptions] = None,
+        *,
+        api: Optional[str] = None,
+        path: Optional[str] = None,
+        query: Optional[Mapping[str, JSONValue]] = None,
+        body: Optional[Mapping[str, JSONValue]] = None,
+    ) -> RunResponse:
+        """Call an API through Orthogonal."""
+
+        if options is not None:
+            if api is not None or path is not None or query is not None or body is not None:
+                raise TypeError("Pass either options or keyword arguments, not both")
+            api = options["api"]
+            path = options["path"]
+            query = options.get("query")
+            body = options.get("body")
+        if api is None or path is None:
+            raise TypeError("run() requires 'api' and 'path'")
+
+        response = await self._client.post(
+            self._url,
+            headers=self._headers,
+            json=_payload(api, path, query, body),
+        )
+        data = response.json()
+        if not response.is_success:
+            raise _error_from_response(response, data)
+        return cast(RunResponse, data)
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client when it is SDK-owned."""
+
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncOrthogonal:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()

orthogonal/_exceptions.py

@@ -0,0 +1,5 @@
+"""Exceptions raised by the Orthogonal SDK."""
+
+
+class OrthogonalError(Exception):
+    """Raised when the Orthogonal API rejects a request."""

orthogonal/_types.py

@@ -0,0 +1,26 @@
+"""Public type definitions for the Orthogonal SDK."""
+
+from typing import Dict, List, TypedDict, Union
+
+JSONPrimitive = Union[str, int, float, bool, None]
+JSONValue = Union[JSONPrimitive, List["JSONValue"], Dict[str, "JSONValue"]]
+
+
+class _RequiredRunOptions(TypedDict):
+    api: str
+    path: str
+
+
+class RunOptions(_RequiredRunOptions, total=False):
+    """Options accepted by :meth:`Orthogonal.run`."""
+
+    query: Dict[str, JSONValue]
+    body: Dict[str, JSONValue]
+
+
+class RunResponse(TypedDict):
+    """Response returned by the Orthogonal API."""
+
+    success: bool
+    price: str
+    data: JSONValue

orthogonal/py.typed

@@ -0,0 +1 @@
+