arbitr-sdk 0.2.0__tar.gz

arbitr_sdk-0.2.0/.gitignore

@@ -0,0 +1,19 @@
+# Secrets — never commit API keys.
+.env
+.env.*
+!.env.example
+
+__pycache__/
+.venv/
+venv/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.hypothesis/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.DS_Store

arbitr_sdk-0.2.0/LICENSE

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

arbitr_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.5
+Name: arbitr-sdk
+Version: 0.2.0
+Summary: Official Python client and CLI for the Arbitr External API
+Project-URL: Homepage, https://github.com/strakergroup/arbitr-python
+Project-URL: Documentation, https://api-arbitr.straker.ai/docs
+Project-URL: Source, https://github.com/strakergroup/arbitr-python
+Author: Straker
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,arbitr,localisation,localization,sdk,straker,translation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Localization
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2
+Requires-Dist: typer>=0.27.1
+Description-Content-Type: text/markdown
+
+# Arbitr Python
+
+Official Python client and `arbitr` CLI for the [Arbitr External API](https://api-arbitr.straker.ai/docs).
+
+```bash
+pip install arbitr-sdk
+```
+
+The PyPI package is `arbitr-sdk`. The import and CLI stay `arbitr`.
+
+```python
+from arbitr import ArbitrClient
+
+client = ArbitrClient.from_env()  # ARBITR_API_KEY, optional ARBITR_BASE_URL
+project = client.projects.submit(
+    files=["report.docx"],
+    name="Q3 report",
+    target_language_codes=["ko-kr", "fr-fr"],
+    idempotency_key="run-2026-08-report",
+)
+final = client.projects.wait(project.id)
+client.projects.download_zip(final.id, "out/deliverables.zip")
+```
+
+Async:
+
+```python
+from arbitr import AsyncArbitrClient
+
+async with AsyncArbitrClient.from_env() as client:
+    me = await client.me()
+```
+
+Coding agents: give your agent this prompt:
+
+```text
+Set up arbitr for me. Fetch https://arbitr.apidocumentation.com/getting-started/agent-setup/index.md and follow it.
+```
+
+Or install the persistent agent skill:
+
+```bash
+npx -y skills add strakergroup/arbitr-python --skill arbitr --yes --global
+```
+
+CLI:
+
+Mint a key at [https://arbitr.straker.ai/settings/api-keys](https://arbitr.straker.ai/settings/api-keys).
+
+```bash
+export ARBITR_API_KEY=abr_live_...
+arbitr me
+arbitr submit report.docx --locales ko-kr,fr-fr --wait --out out/
+```
+
+Exit codes: `0` ok, `1` API error, `2` usage/config/network/timeout, `3` parked
+at a human gate.
+
+Default host is production: `https://api-arbitr.straker.ai`.
+
+Language codes are lowercase BCP-47 tags (`ko-kr`, `fr-fr`). Bare codes (`ko`)
+are rejected by the API — `client.languages.resolve(["ko"])` expands them, or
+`arbitr submit --resolve-locales` does it for you.
+
+The client wraps the **published** OpenAPI surface only. Deprecated aliases
+(agent-selection, `/deliverables/zip`, `/resume`) are not wrapped; use the
+canonical replacements (`wait()` / the Arbitr UI, `?format=zip`, `/resumptions`).
+
+## Errors
+
+Everything this package raises derives from `ArbitrBaseError`, so one `except`
+is enough to be safe. Below it there are two branches:
+
+| Branch | Raised when | Notable members |
+|---|---|---|
+| `ArbitrError` | the API returned a non-2xx response | `AuthenticationError`, `PaymentRequiredError`, `NotFoundError`, `ConflictError`, `ValidationError`, `RateLimitError`, `GoneError`, `ServerError` |
+| `ArbitrClientError` | the call failed before or instead of an error envelope | `TransportError` (`ConnectionFailedError`, `RequestTimeoutError`), `ClientInputError`, `ActionRequiredError`, `ProjectWaitTimeoutError`, `ResponseParseError` |
+
+`httpx` exceptions never escape the client — connection and timeout failures
+arrive as `ConnectionFailedError` / `RequestTimeoutError` with the original
+exception on `__cause__`.
+
+```python
+from arbitr import ArbitrBaseError, PaymentRequiredError
+
+try:
+    client.projects.resume(project_id)
+except PaymentRequiredError as exc:
+    print(f"short by {exc.shortfall} credits")
+except ArbitrBaseError as exc:
+    print(f"call failed: {exc}")
+```
+
+## Retries and rate limits
+
+Retries are opt-in and off by default on the library client:
+
+```python
+client = ArbitrClient.from_env(max_retries=3)
+```
+
+The CLI retries GET up to 3 times (`--max-retries` / `ARBITR_MAX_RETRIES`).
+
+Only GET is replayed — `Retry-After` is honoured on 429 and 5xx back off
+exponentially (capped at 60s). `POST /v1/projects` is never retried
+automatically because its multipart body streams file handles; pass
+`idempotency_key=` and retry it yourself. After any call,
+`client.rate_limit` holds the latest `X-RateLimit-*` values.
+
+## Develop
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check src tests scripts
+uv run ty check
+uv run python scripts/generate_models.py   # after refreshing the pinned spec
+uv run python scripts/check_operation_coverage.py
+```
+
+Pin a fresh production spec:
+
+```bash
+curl -sS https://api-arbitr.straker.ai/openapi.json -o src/arbitr/openapi.json
+uv run python scripts/generate_models.py
+```
+
+The snapshot ships inside the package, so an installed copy can diff itself
+against a live host:
+
+```python
+from arbitr import pinned_spec
+
+print(sorted(pinned_spec()["paths"]))
+```
+
+Do not edit `src/arbitr/generated/models.py` by hand.

arbitr_sdk-0.2.0/README.md

@@ -0,0 +1,137 @@
+# Arbitr Python
+
+Official Python client and `arbitr` CLI for the [Arbitr External API](https://api-arbitr.straker.ai/docs).
+
+```bash
+pip install arbitr-sdk
+```
+
+The PyPI package is `arbitr-sdk`. The import and CLI stay `arbitr`.
+
+```python
+from arbitr import ArbitrClient
+
+client = ArbitrClient.from_env()  # ARBITR_API_KEY, optional ARBITR_BASE_URL
+project = client.projects.submit(
+    files=["report.docx"],
+    name="Q3 report",
+    target_language_codes=["ko-kr", "fr-fr"],
+    idempotency_key="run-2026-08-report",
+)
+final = client.projects.wait(project.id)
+client.projects.download_zip(final.id, "out/deliverables.zip")
+```
+
+Async:
+
+```python
+from arbitr import AsyncArbitrClient
+
+async with AsyncArbitrClient.from_env() as client:
+    me = await client.me()
+```
+
+Coding agents: give your agent this prompt:
+
+```text
+Set up arbitr for me. Fetch https://arbitr.apidocumentation.com/getting-started/agent-setup/index.md and follow it.
+```
+
+Or install the persistent agent skill:
+
+```bash
+npx -y skills add strakergroup/arbitr-python --skill arbitr --yes --global
+```
+
+CLI:
+
+Mint a key at [https://arbitr.straker.ai/settings/api-keys](https://arbitr.straker.ai/settings/api-keys).
+
+```bash
+export ARBITR_API_KEY=abr_live_...
+arbitr me
+arbitr submit report.docx --locales ko-kr,fr-fr --wait --out out/
+```
+
+Exit codes: `0` ok, `1` API error, `2` usage/config/network/timeout, `3` parked
+at a human gate.
+
+Default host is production: `https://api-arbitr.straker.ai`.
+
+Language codes are lowercase BCP-47 tags (`ko-kr`, `fr-fr`). Bare codes (`ko`)
+are rejected by the API — `client.languages.resolve(["ko"])` expands them, or
+`arbitr submit --resolve-locales` does it for you.
+
+The client wraps the **published** OpenAPI surface only. Deprecated aliases
+(agent-selection, `/deliverables/zip`, `/resume`) are not wrapped; use the
+canonical replacements (`wait()` / the Arbitr UI, `?format=zip`, `/resumptions`).
+
+## Errors
+
+Everything this package raises derives from `ArbitrBaseError`, so one `except`
+is enough to be safe. Below it there are two branches:
+
+| Branch | Raised when | Notable members |
+|---|---|---|
+| `ArbitrError` | the API returned a non-2xx response | `AuthenticationError`, `PaymentRequiredError`, `NotFoundError`, `ConflictError`, `ValidationError`, `RateLimitError`, `GoneError`, `ServerError` |
+| `ArbitrClientError` | the call failed before or instead of an error envelope | `TransportError` (`ConnectionFailedError`, `RequestTimeoutError`), `ClientInputError`, `ActionRequiredError`, `ProjectWaitTimeoutError`, `ResponseParseError` |
+
+`httpx` exceptions never escape the client — connection and timeout failures
+arrive as `ConnectionFailedError` / `RequestTimeoutError` with the original
+exception on `__cause__`.
+
+```python
+from arbitr import ArbitrBaseError, PaymentRequiredError
+
+try:
+    client.projects.resume(project_id)
+except PaymentRequiredError as exc:
+    print(f"short by {exc.shortfall} credits")
+except ArbitrBaseError as exc:
+    print(f"call failed: {exc}")
+```
+
+## Retries and rate limits
+
+Retries are opt-in and off by default on the library client:
+
+```python
+client = ArbitrClient.from_env(max_retries=3)
+```
+
+The CLI retries GET up to 3 times (`--max-retries` / `ARBITR_MAX_RETRIES`).
+
+Only GET is replayed — `Retry-After` is honoured on 429 and 5xx back off
+exponentially (capped at 60s). `POST /v1/projects` is never retried
+automatically because its multipart body streams file handles; pass
+`idempotency_key=` and retry it yourself. After any call,
+`client.rate_limit` holds the latest `X-RateLimit-*` values.
+
+## Develop
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check src tests scripts
+uv run ty check
+uv run python scripts/generate_models.py   # after refreshing the pinned spec
+uv run python scripts/check_operation_coverage.py
+```
+
+Pin a fresh production spec:
+
+```bash
+curl -sS https://api-arbitr.straker.ai/openapi.json -o src/arbitr/openapi.json
+uv run python scripts/generate_models.py
+```
+
+The snapshot ships inside the package, so an installed copy can diff itself
+against a live host:
+
+```python
+from arbitr import pinned_spec
+
+print(sorted(pinned_spec()["paths"]))
+```
+
+Do not edit `src/arbitr/generated/models.py` by hand.

arbitr_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,93 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "arbitr-sdk"
+dynamic = ["version"]
+description = "Official Python client and CLI for the Arbitr External API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Straker" }]
+keywords = ["arbitr", "straker", "translation", "localization", "localisation", "api", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Localization",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2",
+    "typer>=0.27.1",
+]
+
+[project.scripts]
+arbitr = "arbitr.cli:entrypoint"
+
+[project.urls]
+Homepage = "https://github.com/strakergroup/arbitr-python"
+Documentation = "https://api-arbitr.straker.ai/docs"
+Source = "https://github.com/strakergroup/arbitr-python"
+
+[dependency-groups]
+dev = [
+    "datamodel-code-generator>=0.75.1",
+    "hypothesis>=6.165.10",
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "respx>=0.23.1",
+    "ruff>=0.16.4",
+    "ty>=0.0.74",
+]
+
+[tool.hatch.version]
+path = "src/arbitr/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/arbitr"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "scripts", "README.md", "LICENSE"]
+
+[tool.uv]
+package = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests", "scripts"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "C4", "RUF", "ANN", "ASYNC", "S"]
+ignore = ["ANN401"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101", "S105", "S106"]
+"scripts/**" = ["S603", "S607"]
+"src/arbitr/generated/**" = ["ALL"]
+
+[tool.ty.environment]
+python-version = "3.11"
+extra-paths = ["src"]
+
+[tool.ty.rules]
+# Resource `.list()` methods shadow the builtin `list` in sibling annotations.
+# Runtime is fine (PEP 563). Generated models also emit Pydantic `constr()`
+# calls that ty rejects as type expressions.
+invalid-type-form = "ignore"

arbitr_sdk-0.2.0/scripts/check_operation_coverage.py

@@ -0,0 +1,52 @@
+"""Fail if a published OpenAPI operationId is missing from both clients.
+
+The mapping tables live in ``arbitr._coverage`` so this script and
+``tests/test_operation_coverage.py`` cannot drift apart.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+
+from arbitr import ArbitrClient, AsyncArbitrClient
+from arbitr._coverage import (
+    IGNORED_OPERATION_IDS,
+    OPERATION_METHODS,
+    audit_spec_mapping,
+    missing_client_methods,
+    published_operation_ids,
+)
+
+
+def _client_errors() -> list[str]:
+    """Check both clients expose every mapped operation, closing them after."""
+    errors: list[str] = []
+    with ArbitrClient(api_key="abr_test_coverage") as sync_client:
+        errors += [f"ArbitrClient missing {item}" for item in missing_client_methods(sync_client)]
+
+    async def check_async() -> list[str]:
+        async with AsyncArbitrClient(api_key="abr_test_coverage") as async_client:
+            return [
+                f"AsyncArbitrClient missing {item}" for item in missing_client_methods(async_client)
+            ]
+
+    return errors + asyncio.run(check_async())
+
+
+def main() -> int:
+    """Exit 1 when the snapshot and client methods drift."""
+    errors = audit_spec_mapping().problems() + _client_errors()
+
+    if errors:
+        print("operation coverage failed:", file=sys.stderr)
+        for line in errors:
+            print(f"  {line}", file=sys.stderr)
+        return 1
+    ignored = len(published_operation_ids() & IGNORED_OPERATION_IDS)
+    print(f"ok: {len(OPERATION_METHODS)} operations on both clients; {ignored} ignored aliases")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

arbitr_sdk-0.2.0/scripts/check_pinned_spec.py

@@ -0,0 +1,141 @@
+"""Fail if the packaged OpenAPI pin differs from live production.
+
+Compares ``src/arbitr/openapi.json`` (via ``pinned_spec()``) to
+``PROD_OPENAPI_URL``. Pytest stays offline; this script is the scheduled
+CI entrypoint.
+
+    uv run python scripts/check_pinned_spec.py
+    uv run python scripts/check_pinned_spec.py --other-file /tmp/openapi.json
+
+Exit 0 if they match after canonicalize, 1 on drift, 2 when the live
+spec is unreadable (CI retries), 3 on unexpected script failures, 4 when
+the packaged pin is unreadable (fail immediately; not a prod flake).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import traceback
+from pathlib import Path
+
+import httpx
+
+from arbitr._spec import (
+    PROD_OPENAPI_URL,
+    OpenAPIDocumentError,
+    openapi_document_diff,
+    parse_openapi_document,
+    pinned_spec,
+)
+
+_DIFF_HEAD_LINES = 200
+_FETCH_TIMEOUT_SECONDS = 30.0
+
+EXIT_MATCH = 0
+EXIT_DRIFT = 1
+EXIT_UNREADABLE = 2
+EXIT_UNEXPECTED = 3
+EXIT_PIN_UNREADABLE = 4
+
+
+class SpecFetchError(Exception):
+    """The live OpenAPI URL could not be fetched."""
+
+
+class SpecReadError(Exception):
+    """An OpenAPI JSON file could not be read from disk."""
+
+
+def _print_cli_error(exc: BaseException) -> None:
+    print(f"error: {exc}", file=sys.stderr)
+    if exc.__cause__ is not None:
+        print(f"cause: {exc.__cause__}", file=sys.stderr)
+
+
+def _print_unexpected(exc: BaseException) -> None:
+    print(f"error: unexpected failure: {exc}", file=sys.stderr)
+    traceback.print_exc(file=sys.stderr)
+
+
+def fetch_openapi_url(url: str) -> dict[str, object]:
+    """GET ``url`` and parse it as an OpenAPI object.
+
+    Raises:
+        SpecFetchError: On transport or HTTP failure.
+        OpenAPIDocumentError: If the body is not a JSON object.
+    """
+    try:
+        response = httpx.get(url, timeout=_FETCH_TIMEOUT_SECONDS, follow_redirects=True)
+        response.raise_for_status()
+    except httpx.HTTPError as exc:
+        raise SpecFetchError(f"failed to fetch {url}") from exc
+    return parse_openapi_document(response.text, source=url)
+
+
+def load_openapi_file(path: Path) -> dict[str, object]:
+    """Read an OpenAPI JSON file.
+
+    Raises:
+        SpecReadError: If the file cannot be read.
+        OpenAPIDocumentError: If the text is not a JSON object OpenAPI document.
+    """
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise SpecReadError(f"cannot read {path}") from exc
+    return parse_openapi_document(raw, source=str(path))
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Compare the pin to a live URL or a local file. Returns a process exit code."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    source = parser.add_mutually_exclusive_group()
+    source.add_argument(
+        "--url",
+        default=None,
+        help=f"live OpenAPI URL (default: {PROD_OPENAPI_URL})",
+    )
+    source.add_argument(
+        "--other-file",
+        type=Path,
+        default=None,
+        help="compare the pin to this JSON file instead of fetching",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        pin = pinned_spec()
+    except (OpenAPIDocumentError, OSError) as exc:
+        _print_cli_error(exc)
+        return EXIT_PIN_UNREADABLE
+    except Exception as exc:
+        _print_unexpected(exc)
+        return EXIT_UNEXPECTED
+
+    try:
+        if args.other_file is not None:
+            live = load_openapi_file(args.other_file)
+        else:
+            live = fetch_openapi_url(args.url or PROD_OPENAPI_URL)
+        diff = openapi_document_diff(pin, live)
+    except (SpecFetchError, SpecReadError, OpenAPIDocumentError) as exc:
+        _print_cli_error(exc)
+        return EXIT_UNREADABLE
+    except Exception as exc:
+        _print_unexpected(exc)
+        return EXIT_UNEXPECTED
+
+    if diff is None:
+        print("pinned spec matches live OpenAPI after canonicalize")
+        return EXIT_MATCH
+
+    lines = diff.splitlines(keepends=True)
+    sys.stdout.write("".join(lines[:_DIFF_HEAD_LINES]))
+    if len(lines) > _DIFF_HEAD_LINES:
+        print(f"... ({len(lines) - _DIFF_HEAD_LINES} more diff lines truncated)")
+    return EXIT_DRIFT
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())