ordainer 0.1.0__py3-none-any.whl

ordainer/__init__.py

@@ -0,0 +1,170 @@
+"""Ask Ordainer before your tool runs.
+
+One decide() call checks the caller's plan and counts the use. Python 3.9+,
+standard library only. Mirrors the Ruby gem (packages/ordainer-ruby) and the
+Node SDK (packages/ordainer-node).
+
+    from ordainer import Client, deny_response
+
+    client = Client(api_key=os.environ["ORDAINER_API_KEY"])
+    decision = client.decide(tool="research.run")
+    if not decision.allowed:
+        blocked = deny_response(decision)
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+from typing import Any, Callable, Optional
+
+from .client import Client
+from .decision import Decision, ErrorInfo
+from .deny import (
+    BILLING_BLOCKED_MESSAGE,
+    CONCURRENCY_LIMITED_MESSAGE,
+    RATE_LIMITED_MESSAGE,
+    UNAVAILABLE_MESSAGE,
+    deny_response,
+    plan_denied_message,
+    rejected_message,
+    reset_day_utc,
+    test_limit_message,
+)
+from .engine import idempotency_key_for
+from .errors import (
+    BlockedError,
+    ConfigurationError,
+    DeniedError,
+    Error,
+    NetworkError,
+    RateLimitedError,
+    RejectedError,
+    TimeoutError,
+    UnavailableError,
+)
+from .version import __version__
+
+VERSION = __version__
+
+__all__ = [
+    "VERSION",
+    "AsyncClient",
+    "BILLING_BLOCKED_MESSAGE",
+    "BlockedError",
+    "CONCURRENCY_LIMITED_MESSAGE",
+    "Client",
+    "Configuration",
+    "ConfigurationError",
+    "Decision",
+    "DeniedError",
+    "Error",
+    "ErrorInfo",
+    "NetworkError",
+    "RATE_LIMITED_MESSAGE",
+    "RateLimitedError",
+    "RejectedError",
+    "TimeoutError",
+    "UNAVAILABLE_MESSAGE",
+    "UnavailableError",
+    "__version__",
+    "client",
+    "configure",
+    "configuration",
+    "deny_response",
+    "idempotency_key_for",
+    "plan_denied_message",
+    "rejected_message",
+    "reset",
+    "reset_day_utc",
+    "test_limit_message",
+]
+
+
+class Configuration:
+    """Global settings for ordainer.client(), same fields as Client."""
+
+    def __init__(self) -> None:
+        self.api_key: Optional[str] = os.environ.get("ORDAINER_API_KEY") or os.environ.get("ORDAINER_KEY")
+        self.base_url: Optional[str] = None
+        self.timeout: Any = None
+        self.fail_mode: Any = None
+        self.retries: Any = None
+        self.retry_budget: Any = None
+        self.mode: Any = None
+        self.billing_lapse: Any = None
+        self.deny_status: Any = None
+        self.sticky_deny: Any = None
+        self.logger: Any = None
+        self.on_decision: Optional[Callable[..., Any]] = None
+
+    def to_client_options(self) -> dict[str, Any]:
+        options = {
+            "api_key": self.api_key,
+            "base_url": self.base_url,
+            "timeout": self.timeout,
+            "fail_mode": self.fail_mode,
+            "retries": self.retries,
+            "retry_budget": self.retry_budget,
+            "mode": self.mode,
+            "billing_lapse": self.billing_lapse,
+            "deny_status": self.deny_status,
+            "sticky_deny": self.sticky_deny,
+            "logger": self.logger,
+            "on_decision": self.on_decision,
+        }
+        return {key: value for key, value in options.items() if value is not None}
+
+
+_configuration: Optional[Configuration] = None
+_client: Optional[Client] = None
+_lock = threading.RLock()
+
+
+def configuration() -> Configuration:
+    global _configuration
+    with _lock:
+        if _configuration is None:
+            _configuration = Configuration()
+        return _configuration
+
+
+def configure(callback: Callable[[Configuration], Any]) -> Configuration:
+    """Apply callback to the global configuration and drop the cached client."""
+    global _client
+    cfg = configuration()
+    callback(cfg)
+    with _lock:
+        old = _client
+        _client = None
+    if old is not None:
+        old.close()
+    return cfg
+
+
+def client() -> Client:
+    """A shared client built from the configuration."""
+    global _client
+    with _lock:
+        if _client is None:
+            _client = Client(**configuration().to_client_options())
+        return _client
+
+
+def reset() -> None:
+    """Drop the global configuration and the shared client."""
+    global _configuration, _client
+    with _lock:
+        old = _client
+        _configuration = None
+        _client = None
+    if old is not None:
+        old.close()
+
+
+def __getattr__(name: str) -> Any:
+    if name == "AsyncClient":
+        from .async_client import AsyncClient
+
+        return AsyncClient
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

ordainer/async_client.py

@@ -0,0 +1,243 @@
+"""Optional async client. Requires httpx (`pip install ordainer[async]`)."""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, Optional
+
+from .client import USER_AGENT, _default_logger, random_default
+from .decision import Decision
+from .engine import (
+    DEFAULT_BASE_URL,
+    DEFAULT_RETRIES,
+    DEFAULT_RETRY_BUDGET,
+    DEFAULT_STICKY_DENY,
+    DEFAULT_TIMEOUT,
+    FAIL_MODES,
+    MODES,
+    Runtime,
+    check_choice,
+    check_deny_status,
+    check_retries,
+    check_retry_budget,
+    check_sticky,
+    check_timeout,
+    strip_base_url,
+)
+from .errors import ConfigurationError, DeniedError, RateLimitedError, RejectedError, UnavailableError
+from .transport import Transport
+
+
+def _require_httpx() -> Any:
+    try:
+        import httpx
+    except ImportError as exc:
+        raise ImportError("AsyncClient requires httpx. Install it with: pip install 'ordainer[async]'") from exc
+    return httpx
+
+
+class AsyncClient:
+    """Async twin of Client. Same decide() rules, httpx for the HTTP call.
+
+    Use as an async context manager, or call aclose() when finished.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        fail_mode: str = "open",
+        retries: int = DEFAULT_RETRIES,
+        retry_budget: float = DEFAULT_RETRY_BUDGET,
+        mode: Optional[str] = None,
+        billing_lapse: str = "open",
+        deny_status: int = 429,
+        sticky_deny: float = DEFAULT_STICKY_DENY,
+        logger: Any = None,
+        on_decision: Optional[Callable[[Decision], Any]] = None,
+        sleeper: Optional[Callable[[float], Any]] = None,
+        random: Optional[Callable[[], float]] = None,
+    ) -> None:
+        self._httpx = _require_httpx()
+        import os
+
+        try:
+            if api_key is None:
+                api_key = os.environ.get("ORDAINER_API_KEY") or os.environ.get("ORDAINER_KEY")
+            if base_url is None:
+                base_url = os.environ.get("ORDAINER_BASE_URL") or DEFAULT_BASE_URL
+            self.base_url = strip_base_url(str(base_url))
+            self.timeout = check_timeout(timeout)
+            self.fail_mode = check_choice(fail_mode, FAIL_MODES, "fail_mode")
+            self.billing_lapse = check_choice(billing_lapse, FAIL_MODES, "billing_lapse")
+            self.mode = None if mode is None else check_choice(mode, MODES, "mode")
+            self.retries = check_retries(retries)
+            self.retry_budget = check_retry_budget(retry_budget)
+            self.deny_status = check_deny_status(deny_status)
+            self.sticky_deny = check_sticky(sticky_deny)
+        except ConfigurationError:
+            raise
+        except (TypeError, ValueError) as exc:
+            raise ConfigurationError(str(exc)) from exc
+        self.api_key = api_key
+        if logger is False:
+            active_logger = None
+        elif logger is None:
+            active_logger = _default_logger()
+        else:
+            active_logger = logger
+        self._sleeper = sleeper
+        # Transport parses the URL (host, path) the same way as the sync client. No connection is kept here.
+        try:
+            parsed = Transport(self.base_url)
+        except ConfigurationError:
+            raise
+        except Exception as exc:
+            raise ConfigurationError(str(exc)) from exc
+        self._endpoint = parsed.endpoint
+        parsed.close()
+        self._runtime = Runtime(
+            base_url=self.base_url,
+            host=parsed.host,
+            timeout=self.timeout,
+            fail_mode=self.fail_mode,
+            retries=self.retries,
+            retry_budget=self.retry_budget,
+            mode=self.mode,
+            billing_lapse=self.billing_lapse,
+            deny_status=self.deny_status,
+            sticky_deny=self.sticky_deny,
+            api_key=api_key if api_key is None else str(api_key),
+            logger=active_logger,
+            on_decision=on_decision,
+            random=random or random_default,
+        )
+        self._http: Any = None
+
+    async def _client(self) -> Any:
+        if self._http is None:
+            timeout = self._httpx.Timeout(self.timeout)
+            self._http = self._httpx.AsyncClient(timeout=timeout, follow_redirects=False, trust_env=False)
+        return self._http
+
+    async def aclose(self) -> None:
+        http = self._http
+        self._http = None
+        if http is not None:
+            await http.aclose()
+
+    async def __aenter__(self) -> "AsyncClient":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+    def __repr__(self) -> str:
+        return f"<ordainer.AsyncClient base_url={self.base_url!r} fail_mode={self.fail_mode!r}>"
+
+    async def _post(self, api_key: str, payload: bytes, timeout: float) -> tuple[int, dict[str, str], bytes]:
+        http = await self._client()
+        try:
+            response = await http.post(
+                self._endpoint,
+                content=payload,
+                headers={
+                    "Authorization": f"Bearer {api_key}",
+                    "Content-Type": "application/json",
+                    "User-Agent": USER_AGENT,
+                    "Accept": "application/json",
+                },
+                timeout=self._httpx.Timeout(timeout),
+            )
+        except self._httpx.TimeoutException:
+            raise
+        except self._httpx.HTTPError:
+            raise
+        headers = {key.lower(): value for key, value in response.headers.items()}
+        return response.status_code, headers, response.content
+
+    async def _pause(self, seconds: float) -> None:
+        sleeper = self._sleeper
+        if sleeper is None:
+            import asyncio
+
+            await asyncio.sleep(seconds)
+            return
+        result = sleeper(seconds)
+        if _is_awaitable(result):
+            await result
+
+    async def decide(
+        self,
+        *,
+        tool: Any,
+        api_key: Optional[str] = None,
+        idempotency_key: Any = None,
+        mode: Optional[str] = None,
+        fail_mode: Optional[str] = None,
+        billing_lapse: Optional[str] = None,
+        retries: Optional[int] = None,
+    ) -> Decision:
+        """Ask Ordainer whether this call may run. Never raises for an answer or an outage."""
+        plan = self._runtime.decide_plan(
+            tool=tool,
+            api_key=api_key,
+            idempotency_key=idempotency_key,
+            mode=mode,
+            fail_mode=fail_mode,
+            billing_lapse=billing_lapse,
+            retries=retries,
+        )
+        if plan["done"] is not None:
+            return self._runtime.finish(plan["done"], plan["started"])
+        timeout = self.timeout
+        attempt = 0
+        result: Decision
+        while True:
+            attempt += 1
+            try:
+                status, headers, raw = await self._post(plan["key"], plan["payload"], timeout)
+            except self._httpx.TimeoutException:
+                result, retryable = self._runtime.on_timeout(plan, timeout)
+            except Exception as exc:
+                # Same contract as the sync client: an encoding or transport error is a
+                # network_error, and fail_mode applies. decide() does not raise.
+                result, retryable = self._runtime.on_network(plan, exc)
+            else:
+                result, retryable = self._runtime.on_http(plan, status, headers, raw)
+            result.attempts = attempt
+            if not retryable or attempt >= plan["max_attempts"]:
+                break
+            nxt = self._runtime.pause_for(attempt, plan["budget_end"])
+            if nxt is None:
+                break
+            pause, timeout = nxt
+            await self._pause(pause)
+        result = self._runtime.apply_sticky(result, plan["key"], plan["tool"], plan["req_mode"])
+        return self._runtime.finish(result, plan["started"])
+
+    async def decide_or_raise(self, **kwargs: Any) -> Decision:
+        """Like decide, but raises a BlockedError subclass when the call must not run."""
+        decision = await self.decide(**kwargs)
+        if decision.allowed:
+            return decision
+        if decision.rate_limited:
+            raise RateLimitedError(decision)
+        if decision.rejected:
+            raise RejectedError(decision)
+        if decision.fail_closed:
+            raise UnavailableError(decision)
+        raise DeniedError(decision)
+
+    async def guard(self, fn: Callable[[Decision], Any], /, **kwargs: Any) -> Any:
+        """Run fn(decision) only if the call is allowed. Raises like decide_or_raise."""
+        decision = await self.decide_or_raise(**kwargs)
+        result = fn(decision)
+        if _is_awaitable(result):
+            return await result
+        return result
+
+
+def _is_awaitable(value: Any) -> bool:
+    return isinstance(value, Awaitable)

ordainer/client.py

@@ -0,0 +1,207 @@
+"""Synchronous Ordainer client. Standard library only."""
+
+from __future__ import annotations
+
+import logging
+import os
+import random
+import sys
+import time
+from typing import Any, Callable, Optional
+
+from .decision import Decision
+from .engine import (
+    DEFAULT_BASE_URL,
+    DEFAULT_RETRIES,
+    DEFAULT_RETRY_BUDGET,
+    DEFAULT_STICKY_DENY,
+    DEFAULT_TIMEOUT,
+    Runtime,
+    check_choice,
+    check_deny_status,
+    check_retries,
+    check_retry_budget,
+    check_sticky,
+    check_timeout,
+    strip_base_url,
+    FAIL_MODES,
+    MODES,
+)
+from .errors import ConfigurationError, DeniedError, RateLimitedError, RejectedError, UnavailableError
+from .transport import Transport, is_timeout
+from .version import __version__
+
+USER_AGENT = f"ordainer-python/{__version__}"
+
+
+def _default_logger() -> logging.Logger:
+    logger = logging.Logger("ordainer")
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    logger.addHandler(handler)
+    logger.setLevel(logging.WARNING)
+    return logger
+
+
+class Client:
+    """Thread-safe. Share one per process.
+
+    decide() never raises for an Ordainer answer or an outage. A deny is a normal Decision.
+    Bad arguments raise ConfigurationError.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        fail_mode: str = "open",
+        retries: int = DEFAULT_RETRIES,
+        retry_budget: float = DEFAULT_RETRY_BUDGET,
+        mode: Optional[str] = None,
+        billing_lapse: str = "open",
+        deny_status: int = 429,
+        sticky_deny: float = DEFAULT_STICKY_DENY,
+        logger: Any = None,
+        on_decision: Optional[Callable[[Decision], Any]] = None,
+        sleeper: Optional[Callable[[float], Any]] = None,
+        random: Optional[Callable[[], float]] = None,
+    ) -> None:
+        try:
+            if api_key is None:
+                api_key = os.environ.get("ORDAINER_API_KEY") or os.environ.get("ORDAINER_KEY")
+            if base_url is None:
+                base_url = os.environ.get("ORDAINER_BASE_URL") or DEFAULT_BASE_URL
+            self.base_url = strip_base_url(str(base_url))
+            self.timeout = check_timeout(timeout)
+            self.fail_mode = check_choice(fail_mode, FAIL_MODES, "fail_mode")
+            self.billing_lapse = check_choice(billing_lapse, FAIL_MODES, "billing_lapse")
+            self.mode = None if mode is None else check_choice(mode, MODES, "mode")
+            self.retries = check_retries(retries)
+            self.retry_budget = check_retry_budget(retry_budget)
+            self.deny_status = check_deny_status(deny_status)
+            self.sticky_deny = check_sticky(sticky_deny)
+        except ConfigurationError:
+            raise
+        except (TypeError, ValueError) as exc:
+            raise ConfigurationError(str(exc)) from exc
+        self.api_key = api_key
+        if logger is False:
+            active_logger = None
+        elif logger is None:
+            active_logger = _default_logger()
+        else:
+            active_logger = logger
+        self._sleeper = sleeper or time.sleep
+        try:
+            self._transport = Transport(self.base_url)
+        except ConfigurationError:
+            raise
+        except Exception as exc:
+            raise ConfigurationError(str(exc)) from exc
+        self._runtime = Runtime(
+            base_url=self.base_url,
+            host=self._transport.host,
+            timeout=self.timeout,
+            fail_mode=self.fail_mode,
+            retries=self.retries,
+            retry_budget=self.retry_budget,
+            mode=self.mode,
+            billing_lapse=self.billing_lapse,
+            deny_status=self.deny_status,
+            sticky_deny=self.sticky_deny,
+            api_key=api_key if api_key is None else str(api_key),
+            logger=active_logger,
+            on_decision=on_decision,
+            random=random or random_default,
+        )
+
+    def decide(
+        self,
+        *,
+        tool: Any,
+        api_key: Optional[str] = None,
+        idempotency_key: Any = None,
+        mode: Optional[str] = None,
+        fail_mode: Optional[str] = None,
+        billing_lapse: Optional[str] = None,
+        retries: Optional[int] = None,
+    ) -> Decision:
+        """Ask Ordainer whether this call may run. Never raises for an answer or an outage."""
+        plan = self._runtime.decide_plan(
+            tool=tool,
+            api_key=api_key,
+            idempotency_key=idempotency_key,
+            mode=mode,
+            fail_mode=fail_mode,
+            billing_lapse=billing_lapse,
+            retries=retries,
+        )
+        if plan["done"] is not None:
+            return self._runtime.finish(plan["done"], plan["started"])
+        timeout = self.timeout
+        attempt = 0
+        result: Decision
+        while True:
+            attempt += 1
+            try:
+                status, headers, raw = self._transport.post(plan["key"], plan["payload"], timeout, USER_AGENT)
+            except Exception as exc:
+                # decide() never raises for a transport failure. A newline or a non-Latin-1
+                # key makes http.client raise ValueError / UnicodeEncodeError before the
+                # bytes go out; that is a network_error, and fail_mode applies. Timeouts stay timeouts.
+                if is_timeout(exc):
+                    result, retryable = self._runtime.on_timeout(plan, timeout)
+                else:
+                    result, retryable = self._runtime.on_network(plan, exc)
+            else:
+                result, retryable = self._runtime.on_http(plan, status, headers, raw)
+            result.attempts = attempt
+            if not retryable or attempt >= plan["max_attempts"]:
+                break
+            nxt = self._runtime.pause_for(attempt, plan["budget_end"])
+            if nxt is None:
+                break
+            pause, timeout = nxt
+            self._sleeper(pause)
+        result = self._runtime.apply_sticky(result, plan["key"], plan["tool"], plan["req_mode"])
+        return self._runtime.finish(result, plan["started"])
+
+    def decide_or_raise(self, **kwargs: Any) -> Decision:
+        """Like decide, but raises a BlockedError subclass when the call must not run.
+
+        This is the Python name for the Ruby client's decide!.
+        """
+        decision = self.decide(**kwargs)
+        if decision.allowed:
+            return decision
+        if decision.rate_limited:
+            raise RateLimitedError(decision)
+        if decision.rejected:
+            raise RejectedError(decision)
+        if decision.fail_closed:
+            raise UnavailableError(decision)
+        raise DeniedError(decision)
+
+    def guard(self, fn: Callable[[Decision], Any], /, **kwargs: Any) -> Any:
+        """Run fn(decision) only if the call is allowed. Raises like decide_or_raise."""
+        decision = self.decide_or_raise(**kwargs)
+        return fn(decision)
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __repr__(self) -> str:
+        # Never shows the key.
+        return f"<ordainer.Client base_url={self.base_url!r} fail_mode={self.fail_mode!r}>"
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+def random_default() -> float:
+    return random.random()