arbitr-sdk 0.2.0__py3-none-any.whl

arbitr/__init__.py

@@ -0,0 +1,155 @@
+"""Official Python client and CLI for the Arbitr External API."""
+
+from arbitr._constants import (
+    ACTION_REQUIRED_STATUSES,
+    ALLOWED_UPLOAD_EXTENSIONS,
+    DEFAULT_BASE_URL,
+    MAX_UPLOAD_FILES,
+    MAX_UPLOAD_TOTAL_BYTES,
+    SUPPORTED_FORMATS,
+    TERMINAL_STATUSES,
+)
+from arbitr._datetime import UtcDatetime
+from arbitr._projects import ProjectResumptionResponse
+from arbitr._spec import OpenAPIDocumentError, pinned_spec
+from arbitr._version import __version__
+from arbitr.async_client import AsyncArbitrClient
+from arbitr.client import ArbitrClient, new_idempotency_key
+from arbitr.errors import (
+    ActionRequiredError,
+    AmbiguousLocaleCodesError,
+    ArbitrBaseError,
+    ArbitrClientError,
+    ArbitrError,
+    AuthenticationError,
+    BareLocaleCodeError,
+    ClientInputError,
+    ConflictError,
+    ConnectionFailedError,
+    DisallowedFileExtensionError,
+    FindingsKeysetError,
+    GoneError,
+    MissingApiKeyError,
+    NotFoundError,
+    PaymentRequiredError,
+    ProjectWaitTimeoutError,
+    RateLimitError,
+    RequestTimeoutError,
+    ResponseDecodeError,
+    ResponseParseError,
+    ServerError,
+    TransportError,
+    UnknownLocaleCodesError,
+    ValidationError,
+)
+from arbitr.generated.models import (
+    AgentFinding,
+    ApiKeyMode,
+    Assessment,
+    AssessmentCredits,
+    ChainOfCustodyResponse,
+    CreatedVia,
+    CreditBalanceResponse,
+    CreditWallet,
+    DeliverableGeneration,
+    DeliverableListResponse,
+    FindingListResponse,
+    FindingPage,
+    FindingSeverity,
+    FindingStatus,
+    FindingType,
+    FlagFinding,
+    HumanReviewResponse,
+    HumanReviewStatus,
+    LanguageListResponse,
+    LanguageResponse,
+    MeResponse,
+    Page,
+    ProjectDeliverableResponse,
+    ProjectListResponse,
+    ProjectResponse,
+    Review,
+    SourceFileIdentity,
+)
+from arbitr.webhooks import (
+    KNOWN_EVENTS,
+    WebhookVerificationError,
+    compute_signature,
+    parse_event,
+    verify_signature,
+)
+
+__all__ = [
+    "ACTION_REQUIRED_STATUSES",
+    "ALLOWED_UPLOAD_EXTENSIONS",
+    "DEFAULT_BASE_URL",
+    "KNOWN_EVENTS",
+    "MAX_UPLOAD_FILES",
+    "MAX_UPLOAD_TOTAL_BYTES",
+    "SUPPORTED_FORMATS",
+    "TERMINAL_STATUSES",
+    "ActionRequiredError",
+    "AgentFinding",
+    "AmbiguousLocaleCodesError",
+    "ApiKeyMode",
+    "ArbitrBaseError",
+    "ArbitrClient",
+    "ArbitrClientError",
+    "ArbitrError",
+    "Assessment",
+    "AssessmentCredits",
+    "AsyncArbitrClient",
+    "AuthenticationError",
+    "BareLocaleCodeError",
+    "ChainOfCustodyResponse",
+    "ClientInputError",
+    "ConflictError",
+    "ConnectionFailedError",
+    "CreatedVia",
+    "CreditBalanceResponse",
+    "CreditWallet",
+    "DeliverableGeneration",
+    "DeliverableListResponse",
+    "DisallowedFileExtensionError",
+    "FindingListResponse",
+    "FindingPage",
+    "FindingSeverity",
+    "FindingStatus",
+    "FindingType",
+    "FindingsKeysetError",
+    "FlagFinding",
+    "GoneError",
+    "HumanReviewResponse",
+    "HumanReviewStatus",
+    "LanguageListResponse",
+    "LanguageResponse",
+    "MeResponse",
+    "MissingApiKeyError",
+    "NotFoundError",
+    "OpenAPIDocumentError",
+    "Page",
+    "PaymentRequiredError",
+    "ProjectDeliverableResponse",
+    "ProjectListResponse",
+    "ProjectResponse",
+    "ProjectResumptionResponse",
+    "ProjectWaitTimeoutError",
+    "RateLimitError",
+    "RequestTimeoutError",
+    "ResponseDecodeError",
+    "ResponseParseError",
+    "Review",
+    "ServerError",
+    "SourceFileIdentity",
+    "TransportError",
+    "UnknownLocaleCodesError",
+    "UtcDatetime",
+    "ValidationError",
+    "WebhookVerificationError",
+    "__version__",
+    "compute_signature",
+    "new_idempotency_key",
+    "parse_event",
+    "pinned_spec",
+    "verify_signature",
+]

arbitr/_constants.py

@@ -0,0 +1,58 @@
+"""Constants shared by the sync and async clients (no I/O)."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+DEFAULT_BASE_URL = "https://api-arbitr.straker.ai"
+
+TERMINAL_STATUSES = frozenset({"cancelled", "completed", "published", "failed"})
+ACTION_REQUIRED_STATUSES = frozenset({"agent_selection", "awaiting_payment"})
+AGENT_SELECTION_CONFIRM_POLLS = 2
+
+# Leading-byte-checked upload allowlist from the published OpenAPI snapshot.
+ALLOWED_UPLOAD_EXTENSIONS = frozenset(
+    {
+        ".csv",
+        ".dita",
+        ".ditamap",
+        ".docx",
+        ".htm",
+        ".html",
+        ".idml",
+        ".json",
+        ".markdown",
+        ".md",
+        ".pdf",
+        ".po",
+        ".pptx",
+        ".properties",
+        ".srt",
+        ".strings",
+        ".ts",
+        ".txt",
+        ".vtt",
+        ".xlf",
+        ".xliff",
+        ".xlsx",
+        ".xml",
+    }
+)
+SUPPORTED_FORMATS: list[str] = sorted(ALLOWED_UPLOAD_EXTENSIONS)
+
+MAX_UPLOAD_FILES = 100
+MAX_UPLOAD_TOTAL_BYTES = 200 * 1024 * 1024
+
+DEFAULT_WORKFLOW = ("AI_TRANSLATION",)
+DEFAULT_SOURCE_LANGUAGE = "en-us"
+
+# Retries are opt-in via ``max_retries``. 429 carries Retry-After; the 5xx
+# codes back off exponentially. Other statuses are never retried. Only GET
+# is replayed — POST /v1/projects streams file handles that cannot be
+# rewound, so callers retry it themselves with ``idempotency_key``.
+RETRY_STATUS_CODES = frozenset({429, 500, 502, 503, 504})
+RETRY_BACKOFF_BASE_SECONDS = 0.5
+RETRY_BACKOFF_MAX_SECONDS = 60.0
+
+OnActionRequired = Literal["raise", "wait"]
+ExtensionCheck = Literal["allowlist", "off"]

arbitr/_coverage.py

@@ -0,0 +1,127 @@
+"""Published-surface coverage rules, shared by the CI script and the test suite.
+
+Single source of truth for which OpenAPI operations this package wraps. Both
+``scripts/check_operation_coverage.py`` and ``tests/test_operation_coverage.py``
+read these tables, so a new operation cannot be half-registered.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from arbitr._spec import pinned_spec
+
+# Deprecated aliases still in the published spec. The canonical replacements
+# are implemented; these ids must not grow a wrapper.
+IGNORED_OPERATION_IDS = frozenset(
+    {
+        "getAgentSelection",
+        "submitAgentSelection",
+        "downloadDeliverablesZip",
+        "downloadDeliverable",
+        "resumeProject",
+        "resumeHumanReview",
+    }
+)
+
+# operationId -> dotted attribute on ArbitrClient / AsyncArbitrClient
+OPERATION_METHODS: dict[str, str] = {
+    "getCurrentKey": "me",
+    "createProject": "projects.submit",
+    "listProjects": "projects.list",
+    "getProject": "projects.get",
+    "listDeliverables": "projects.deliverables",
+    "getDeliverable": "projects.deliverable",
+    "listProjectFindings": "projects.findings",
+    "getProjectChainOfCustody": "projects.chain_of_custody",
+    "createProjectResumption": "projects.resume",
+    "createReviewResumption": "projects.resume_human_review",
+    "listLanguages": "languages.list",
+    "getCreditBalance": "credits.balance",
+}
+
+_HTTP_METHODS = frozenset({"get", "put", "post", "delete", "patch", "head", "options", "trace"})
+
+
+def published_operation_ids() -> set[str]:
+    """Every operationId in the pinned snapshot."""
+    ids: set[str] = set()
+    paths = pinned_spec().get("paths")
+    if not isinstance(paths, dict):
+        return ids
+    for item in paths.values():
+        if not isinstance(item, dict):
+            continue
+        for name, op in item.items():
+            if name.lower() in _HTTP_METHODS and isinstance(op, dict) and "operationId" in op:
+                ids.add(str(op["operationId"]))
+    return ids
+
+
+def resolve_attr(root: object, dotted: str) -> object:
+    """Walk a dotted attribute path, raising AttributeError if any part is missing."""
+    current = root
+    for part in dotted.split("."):
+        current = getattr(current, part)
+    return current
+
+
+@dataclass(frozen=True)
+class CoverageReport:
+    """Drift between the pinned snapshot and the mapping tables."""
+
+    unmapped: list[str] = field(default_factory=list)
+    """Published operationIds that are neither mapped nor ignored."""
+
+    unpublished: list[str] = field(default_factory=list)
+    """Mapped operationIds absent from the snapshot."""
+
+    stale_ignores: list[str] = field(default_factory=list)
+    """Ignored operationIds absent from the snapshot."""
+
+    wrapped_ignores: list[str] = field(default_factory=list)
+    """Ignored operationIds that wrongly grew a method mapping."""
+
+    @property
+    def ok(self) -> bool:
+        """True when the snapshot and the tables agree."""
+        return not (self.unmapped or self.unpublished or self.stale_ignores or self.wrapped_ignores)
+
+    def problems(self) -> list[str]:
+        """Human-readable lines describing each drift, empty when ``ok``."""
+        lines: list[str] = []
+        if self.unmapped:
+            lines.append(f"published operationIds with no method mapping: {self.unmapped}")
+        if self.unpublished:
+            lines.append(f"mapped operationIds not in the snapshot: {self.unpublished}")
+        if self.stale_ignores:
+            lines.append(f"ignored operationIds not in the snapshot: {self.stale_ignores}")
+        if self.wrapped_ignores:
+            lines.append(f"ignored operationIds must not be wrapped: {self.wrapped_ignores}")
+        return lines
+
+
+def audit_spec_mapping() -> CoverageReport:
+    """Compare the pinned snapshot against the mapping tables."""
+    published = published_operation_ids()
+    mapped = set(OPERATION_METHODS)
+    return CoverageReport(
+        unmapped=sorted(published - IGNORED_OPERATION_IDS - mapped),
+        unpublished=sorted(mapped - published),
+        stale_ignores=sorted(IGNORED_OPERATION_IDS - published),
+        wrapped_ignores=sorted(IGNORED_OPERATION_IDS & mapped),
+    )
+
+
+def missing_client_methods(client: object) -> list[str]:
+    """Mapped operations whose dotted attribute is missing or not callable."""
+    missing: list[str] = []
+    for op_id, dotted in sorted(OPERATION_METHODS.items()):
+        try:
+            attr = resolve_attr(client, dotted)
+        except AttributeError:
+            missing.append(f"{dotted} (operationId {op_id})")
+            continue
+        if not callable(attr):
+            missing.append(f"{dotted} is not callable (operationId {op_id})")
+    return missing

arbitr/_credentials.py

@@ -0,0 +1,128 @@
+"""API-key mode and dotenv construction shared by both clients (no network)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from arbitr._constants import DEFAULT_BASE_URL
+from arbitr._env import pick_env_value, read_env_file
+from arbitr._http import derive_ui_url, parse_max_retries
+from arbitr.errors import ClientInputError, MissingApiKeyError
+
+CLI_DEFAULT_MAX_RETRIES = 3
+
+
+def api_key_mode(api_key: str) -> str:
+    """Best-effort key mode from the prefix: ``live``, ``test``, or ``unknown``."""
+    if "_live_" in api_key:
+        return "live"
+    if "_test_" in api_key:
+        return "test"
+    return "unknown"
+
+
+@dataclass(frozen=True)
+class HostSettings:
+    """API and UI hosts resolved from env / dotenv / explicit overrides."""
+
+    base_url: str
+    ui_base_url: str
+
+
+@dataclass(frozen=True)
+class ClientSettings:
+    """Resolved constructor inputs from env / dotenv / explicit overrides."""
+
+    api_key: str
+    base_url: str
+    ui_base_url: str | None
+    extra: dict[str, Any]
+
+
+def _parse_env_max_retries(raw: str) -> int:
+    """Parse ``ARBITR_MAX_RETRIES`` from a dotenv / env string."""
+    try:
+        value = int(raw.strip())
+    except ValueError:
+        raise ClientInputError("max_retries must be a non-negative integer") from None
+    return parse_max_retries(value)
+
+
+def load_host_settings(
+    env_file: str | Path = ".env",
+    *,
+    base_url: str | None = None,
+    ui_base_url: str | None = None,
+) -> HostSettings:
+    """Resolve API and UI hosts without requiring an API key."""
+    file_vals = read_env_file(env_file)
+    url = (
+        base_url
+        or pick_env_value(
+            "ARBITR_BASE_URL",
+            "ARBITR_API_DOMAIN",
+            "arbitr_api_domain",
+            file_vals=file_vals,
+        )
+        or DEFAULT_BASE_URL
+    )
+    ui = (
+        ui_base_url
+        or pick_env_value("ARBITR_UI_URL", "arbitr_ui_url", file_vals=file_vals)
+        or derive_ui_url(url)
+    )
+    return HostSettings(base_url=url.rstrip("/"), ui_base_url=ui.rstrip("/"))
+
+
+def resolve_cli_max_retries(
+    env_file: str | Path,
+    *,
+    max_retries: int | None,
+) -> int:
+    """CLI retry count: flag, then env, then ``CLI_DEFAULT_MAX_RETRIES``."""
+    if max_retries is not None:
+        return parse_max_retries(max_retries)
+    file_vals = read_env_file(env_file)
+    raw = pick_env_value("ARBITR_MAX_RETRIES", "arbitr_max_retries", file_vals=file_vals)
+    if raw is not None:
+        return _parse_env_max_retries(raw)
+    return CLI_DEFAULT_MAX_RETRIES
+
+
+def load_client_settings(
+    env_file: str | Path = ".env",
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    **kwargs: Any,
+) -> ClientSettings:
+    """Resolve API key, base URL, and UI URL for client construction.
+
+    Raises:
+        MissingApiKeyError: If no key is in the arguments, environment, or dotenv file.
+    """
+    file_vals = read_env_file(env_file)
+    host = load_host_settings(
+        env_file,
+        base_url=base_url,
+        ui_base_url=kwargs.pop("ui_base_url", None),
+    )
+    key = api_key or pick_env_value("ARBITR_API_KEY", "arbitr_api_key", file_vals=file_vals)
+    if "max_retries" not in kwargs:
+        raw = pick_env_value("ARBITR_MAX_RETRIES", "arbitr_max_retries", file_vals=file_vals)
+        if raw is not None:
+            kwargs["max_retries"] = _parse_env_max_retries(raw)
+    if not key:
+        raise MissingApiKeyError(
+            "No API key found. Set ARBITR_API_KEY in the environment or "
+            "arbitr_api_key in the env file. Mint a key at "
+            "https://arbitr.straker.ai/settings/api-keys"
+        )
+    return ClientSettings(
+        api_key=key,
+        base_url=host.base_url,
+        ui_base_url=host.ui_base_url,
+        extra=kwargs,
+    )

arbitr/_datetime.py

@@ -0,0 +1,23 @@
+"""The timestamp type every generated model uses for ``format: date-time``.
+
+``AwareDatetime`` would reject a naive ISO string outright, and a plain
+``datetime`` would hand the caller a naive value that raises ``TypeError`` the
+moment it is compared against an aware one. Both are worse than assuming UTC:
+every timestamp the API returns is UTC, it just has not always carried the
+offset. ``scripts/generate_models.py`` rewrites ``AwareDatetime`` to this.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Annotated
+
+from pydantic import AfterValidator
+
+
+def assume_utc(value: datetime) -> datetime:
+    """Tag a naive timestamp as UTC; convert an aware one to UTC."""
+    return value.replace(tzinfo=UTC) if value.tzinfo is None else value.astimezone(UTC)
+
+
+UtcDatetime = Annotated[datetime, AfterValidator(assume_utc)]

arbitr/_env.py

@@ -0,0 +1,54 @@
+"""Dotenv + env-var loading for client construction (no network)."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def _unquote(value: str) -> str:
+    """Strip one matched pair of surrounding quotes.
+
+    Only a matched pair is removed, so a value that merely ends in a quote
+    keeps it.
+    """
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
+        return value[1:-1]
+    return value
+
+
+def read_env_file(path: str | Path) -> dict[str, str]:
+    """Parse a KEY=VALUE dotenv file; missing files yield an empty dict.
+
+    Understands ``export KEY=VALUE`` and ignores blank and ``#`` comment
+    lines. Values are not expanded and inline comments are not stripped —
+    a ``#`` inside a value is part of the value.
+    """
+    file_path = Path(path)
+    values: dict[str, str] = {}
+    if not file_path.is_file():
+        return values
+    for line in file_path.read_text().splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or "=" not in stripped:
+            continue
+        if stripped.startswith("export "):
+            stripped = stripped[len("export ") :].lstrip()
+        key, value = stripped.split("=", 1)
+        values[key.strip()] = _unquote(value.strip())
+    return values
+
+
+def pick_env_value(*names: str, file_vals: dict[str, str]) -> str | None:
+    """Return the first non-empty value from os.environ, then the dotenv file.
+
+    Every alias is checked in the environment before any dotenv value, so a
+    file ``ARBITR_API_KEY`` cannot override an env ``arbitr_api_key``.
+    """
+    for name in names:
+        if os.environ.get(name):
+            return os.environ[name]
+    for name in names:
+        if file_vals.get(name):
+            return file_vals[name]
+    return None