horasis 1.0.0__py3-none-any.whl

horasis/__init__.py

@@ -0,0 +1,106 @@
+"""Computer vision SDK with API-key access control.
+
+Applications import from this module and :mod:`horasis.api`. The
+`foundation`, `access`, `backend`, `orchestration` and `plugins` packages
+are for extension authors (a new `Backend`, a custom `Telemetry` sink) and
+are not covered by the stability guarantee of the top-level API.
+
+Quick start:
+    >>> from horasis import Client, InMemoryApiKeyValidator, Tier
+    >>> validator = InMemoryApiKeyValidator()
+    >>> validator.register_simple("demo-key", principal_id="alice", tier=Tier.FREE)
+    >>> client = Client.build(validator=validator)
+    >>> result = client.detection.detect("photo.jpg", api_key="demo-key")
+"""
+
+from horasis.access.keys import ApiKeyValidator, HashedApiKeyValidator, InMemoryApiKeyValidator
+from horasis.access.quota import UsageReport
+from horasis.access.tiers import Tier
+from horasis.api.async_client import AsyncClient
+from horasis.api.client import (
+    Client,
+    ContentModerator,
+    FaceDetector,
+    ImageClassifier,
+    ObjectDetector,
+    TextExtractor,
+)
+from horasis.foundation.config import Config, InputPolicy
+from horasis.foundation.errors import (
+    AccessDeniedError,
+    AdapterError,
+    BackendUnavailableError,
+    ConfigurationError,
+    ExpiredApiKeyError,
+    HorasisError,
+    InvalidApiKeyError,
+    ModelDownloadError,
+    NoBackendError,
+    QuotaExceededError,
+    RateLimitedError,
+    RemoteError,
+    RevokedApiKeyError,
+    ValidationError,
+    VisualizationUnavailableError,
+)
+from horasis.foundation.schemas import (
+    BatchItem,
+    ClassificationResult,
+    DetectionResult,
+    Face,
+    FaceResult,
+    Image,
+    ModerationResult,
+    OcrResult,
+    Task,
+    TextRegion,
+    Video,
+    VideoDetectionResult,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "AccessDeniedError",
+    "AdapterError",
+    "ApiKeyValidator",
+    "AsyncClient",
+    "BackendUnavailableError",
+    "BatchItem",
+    "ClassificationResult",
+    "Client",
+    "Config",
+    "ConfigurationError",
+    "ContentModerator",
+    "DetectionResult",
+    "ExpiredApiKeyError",
+    "Face",
+    "FaceDetector",
+    "FaceResult",
+    "HashedApiKeyValidator",
+    "HorasisError",
+    "Image",
+    "ImageClassifier",
+    "InMemoryApiKeyValidator",
+    "InputPolicy",
+    "InvalidApiKeyError",
+    "ModelDownloadError",
+    "ModerationResult",
+    "NoBackendError",
+    "ObjectDetector",
+    "OcrResult",
+    "QuotaExceededError",
+    "RateLimitedError",
+    "RemoteError",
+    "RevokedApiKeyError",
+    "Task",
+    "TextExtractor",
+    "TextRegion",
+    "Tier",
+    "UsageReport",
+    "ValidationError",
+    "Video",
+    "VideoDetectionResult",
+    "VisualizationUnavailableError",
+    "__version__",
+]

horasis/__main__.py

@@ -0,0 +1,3 @@
+from horasis.cli import main
+
+raise SystemExit(main())

horasis/access/__init__.py

@@ -0,0 +1,42 @@
+"""Layer 4: API keys, tiers, quotas and rate limits.
+
+Imports only from the foundation layer.
+"""
+
+from horasis.access.guard import AccessContext, requires_access
+from horasis.access.keys import ApiKeyValidator, HashedApiKeyValidator, InMemoryApiKeyValidator
+from horasis.access.policy import Policy
+from horasis.access.principal import AnonymousPrincipal, Principal
+from horasis.access.quota import (
+    InMemoryQuotaStore,
+    QuotaManager,
+    QuotaStore,
+    UsageReport,
+    WindowUsage,
+)
+from horasis.access.ratelimit import RateLimiter, RedisRateLimiter, TokenBucketLimiter
+from horasis.access.stores import RedisQuotaStore, SQLiteQuotaStore, redis_backends
+from horasis.access.tiers import Tier
+
+__all__ = [
+    "AccessContext",
+    "AnonymousPrincipal",
+    "ApiKeyValidator",
+    "HashedApiKeyValidator",
+    "InMemoryApiKeyValidator",
+    "InMemoryQuotaStore",
+    "Policy",
+    "Principal",
+    "QuotaManager",
+    "QuotaStore",
+    "RateLimiter",
+    "RedisQuotaStore",
+    "RedisRateLimiter",
+    "SQLiteQuotaStore",
+    "Tier",
+    "TokenBucketLimiter",
+    "UsageReport",
+    "WindowUsage",
+    "redis_backends",
+    "requires_access",
+]

horasis/access/guard.py

@@ -0,0 +1,192 @@
+"""The access-control decorator.
+
+Every public-API call passes through :func:`requires_access` before it
+reaches orchestration. The API key is resolved to a
+:class:`~horasis.access.principal.Principal`,
+:class:`~horasis.access.policy.Policy` authorizes the task, rate limits and
+quota are charged, and :class:`~horasis.foundation.telemetry.Telemetry`
+hooks fire around the call.
+
+It decorates methods of any object that keeps an :class:`AccessContext` in
+``_access`` and takes ``api_key`` as a keyword argument.
+"""
+
+from __future__ import annotations
+
+import functools
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, TypeVar
+
+from horasis.access.keys import ApiKeyValidator
+from horasis.access.policy import Policy
+from horasis.access.principal import Principal
+from horasis.access.quota import QuotaManager, UsageReport
+from horasis.access.ratelimit import RateLimiter, TokenBucketLimiter
+from horasis.foundation.config import Config, QuotaRule
+from horasis.foundation.errors import HorasisError, QuotaExceededError, ValidationError
+from horasis.foundation.imaging import to_image
+from horasis.foundation.schemas import Task
+from horasis.foundation.telemetry import NullTelemetry, Telemetry
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+@dataclass(frozen=True)
+class AccessContext:
+    """Everything `requires_access` needs to guard a call."""
+
+    config: Config
+    validator: ApiKeyValidator
+    policy: Policy
+    quota_manager: QuotaManager
+    rate_limiter: RateLimiter
+    telemetry: Telemetry = field(default_factory=NullTelemetry)
+
+    @classmethod
+    def build(
+        cls,
+        *,
+        config: Config,
+        validator: ApiKeyValidator,
+        quota_manager: QuotaManager | None = None,
+        rate_limiter: RateLimiter | None = None,
+        telemetry: Telemetry | None = None,
+    ) -> AccessContext:
+        return cls(
+            config=config,
+            validator=validator,
+            policy=Policy(config),
+            quota_manager=quota_manager or QuotaManager(),
+            rate_limiter=rate_limiter or TokenBucketLimiter(),
+            telemetry=telemetry or NullTelemetry(),
+        )
+
+
+    def charge(self, principal: Principal, task: Task, *, units: int = 1) -> None:
+        """Rate-limit and meter `units` calls of `task` for `principal`.
+
+        Each unit costs ``Config.cost_for(task)``. All-or-nothing: if any
+        limit rejects, everything taken so far is given back.
+
+        Raises:
+            RateLimitedError: per-minute bucket empty (has ``retry_after``).
+            QuotaExceededError: window quota exhausted (has ``retry_after``,
+                ``limit`` and ``scope``).
+        """
+        rule = self.config.tier(principal.tier.value)
+        pid, name = principal.principal_id, task.value
+        cost = self.config.cost_for(name) * units
+        self.rate_limiter.acquire(pid, name, rule, cost)
+        try:
+            self.quota_manager.check_and_consume(pid, rule.quota, cost=cost)
+            task_rule = self._task_rule(rule.task_quotas.get(name), rule.quota)
+            try:
+                self.quota_manager.check_and_consume(pid, task_rule, cost=cost, scope=f"task:{name}")
+            except QuotaExceededError:
+                self.quota_manager.refund(pid, rule.quota, cost=cost)
+                raise
+        except QuotaExceededError:
+            self.rate_limiter.refund(pid, name, rule, cost)
+            raise
+
+    @staticmethod
+    def _task_rule(specific: QuotaRule | None, overall: QuotaRule) -> QuotaRule:
+        return specific or overall
+
+    def usage(self, principal: Principal) -> UsageReport:
+        """Return used and remaining units for `principal`, overall and per task."""
+        rule = self.config.tier(principal.tier.value)
+        pid = principal.principal_id
+        per_task = {
+            name: self.quota_manager.window_usage(
+                pid, self._task_rule(rule.task_quotas.get(name), rule.quota), scope=f"task:{name}"
+            )
+            for name in rule.allowed_tasks
+            if principal.scopes is None or name in principal.scopes
+        }
+        return UsageReport(
+            principal_id=pid,
+            tier=principal.tier.value,
+            overall=self.quota_manager.window_usage(pid, rule.quota),
+            per_task=per_task,
+        )
+
+
+def _validated_inputs(
+    access: AccessContext, args: tuple[Any, ...], kwargs: dict[str, Any]
+) -> tuple[tuple[Any, ...], dict[str, Any]]:
+    """Decode and validate the image argument (first positional, or ``image=``).
+
+    The decoded `Image` replaces the raw input, so the wrapped method does not
+    decode twice and malformed input is rejected before anything is charged.
+    """
+    policy = access.config.inputs
+    if "image" in kwargs:
+        return args, {**kwargs, "image": to_image(kwargs["image"], policy)}
+    if args:
+        return (to_image(args[0], policy), *args[1:]), kwargs
+    return args, kwargs
+
+
+def requires_access(task: Task, *, validate_image: bool = True) -> Callable[[F], F]:
+    """Authenticate, authorize and charge quota before running the method.
+
+    The method must be called with an ``api_key`` keyword and its instance
+    must keep an :class:`AccessContext` in ``_access``. It receives the
+    resolved ``principal`` as a keyword argument.
+
+    Args:
+        task: Task the method performs, for authorization and telemetry.
+        validate_image: Decode and validate the image argument before
+            charging, so invalid input costs nothing. Set False for video.
+    """
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+            access: AccessContext | None = getattr(self, "_access", None)
+            if access is None:
+                raise ValidationError(
+                    f"{type(self).__name__} has no AccessContext; cannot enforce @requires_access"
+                )
+
+            api_key = kwargs.pop("api_key", None)
+            if not api_key:
+                raise ValidationError("api_key is required")
+
+            principal: Principal = access.validator.validate(api_key)
+            access.policy.authorize(principal, task)
+            if validate_image:
+                args, kwargs = _validated_inputs(access, args, kwargs)
+            access.charge(principal, task)
+
+            access.telemetry.on_call_start(task=task.value, principal_id=principal.principal_id)
+            start = time.perf_counter()
+            try:
+                result = func(self, *args, principal=principal, **kwargs)
+            except HorasisError as exc:
+                access.telemetry.on_error(
+                    task=task.value, principal_id=principal.principal_id, error=exc
+                )
+                raise
+            except Exception as exc:  # pragma: no cover - defensive
+                access.telemetry.on_error(
+                    task=task.value, principal_id=principal.principal_id, error=exc
+                )
+                raise
+            latency_ms = (time.perf_counter() - start) * 1000
+            backend = getattr(result, "backend", "unknown")
+            access.telemetry.on_call_end(
+                task=task.value,
+                principal_id=principal.principal_id,
+                backend=backend,
+                latency_ms=latency_ms,
+                success=True,
+            )
+            return result
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator

horasis/access/keys.py

@@ -0,0 +1,204 @@
+"""API key validators."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+import secrets
+import time
+from dataclasses import dataclass
+from typing import Protocol
+
+from horasis.access.principal import Principal
+from horasis.access.tiers import Tier
+from horasis.foundation.errors import ExpiredApiKeyError, InvalidApiKeyError, RevokedApiKeyError
+
+
+class ApiKeyValidator(Protocol):
+    """Resolves a raw API key string into an authenticated :class:`Principal`."""
+
+    def validate(self, api_key: str) -> Principal:
+        """Return the :class:`Principal` for `api_key`.
+
+        Raises:
+            InvalidApiKeyError: if the key is missing, malformed, or unknown.
+            ExpiredApiKeyError: if the key existed but has passed its expiry.
+            RevokedApiKeyError: if the key was explicitly revoked.
+        """
+        raise NotImplementedError
+
+
+class InMemoryApiKeyValidator:
+    """Validator backed by a dict of plaintext keys, for tests and demos.
+
+    Use :class:`HashedApiKeyValidator` for real deployments.
+    """
+
+    def __init__(self) -> None:
+        self._keys: dict[str, tuple[Principal, float | None, bool]] = {}
+
+    def register(
+        self,
+        api_key: str,
+        principal: Principal,
+        *,
+        expires_at: float | None = None,
+    ) -> None:
+        """Register `api_key`, optionally with an expiry (Unix epoch seconds)."""
+        self._keys[api_key] = (principal, expires_at, False)
+
+    def register_simple(
+        self,
+        api_key: str,
+        *,
+        principal_id: str,
+        tier: Tier,
+        expires_at: float | None = None,
+        scopes: list[str] | None = None,
+    ) -> None:
+        self.register(
+            api_key,
+            Principal(principal_id=principal_id, tier=tier, scopes=scopes),
+            expires_at=expires_at,
+        )
+
+    def revoke(self, api_key: str) -> None:
+        """Revoke `api_key` but keep its record.
+
+        `validate` then raises `RevokedApiKeyError` rather than `InvalidApiKeyError`.
+        """
+        if api_key in self._keys:
+            principal, expires_at, _ = self._keys[api_key]
+            self._keys[api_key] = (principal, expires_at, True)
+
+    def validate(self, api_key: str) -> Principal:
+        if not api_key:
+            raise InvalidApiKeyError("API key is empty")
+
+        entry = self._keys.get(api_key)
+        if entry is None:
+            raise InvalidApiKeyError("API key is unknown")
+
+        principal, expires_at, revoked = entry
+        if revoked:
+            raise RevokedApiKeyError(
+                "API key has been revoked", context={"principal_id": principal.principal_id}
+            )
+        if expires_at is not None and time.time() >= expires_at:
+            raise ExpiredApiKeyError(
+                "API key has expired", context={"principal_id": principal.principal_id}
+            )
+        return principal
+
+
+@dataclass
+class _KeyRecord:
+    salt: bytes
+    digest: bytes
+    principal: Principal
+    expires_at: float | None
+    revoked: bool = False
+
+
+def _digest(salt: bytes, secret: str) -> bytes:
+    return hashlib.sha256(salt + secret.encode()).digest()
+
+
+class HashedApiKeyValidator:
+    """Validator that never stores a key, only a per-key salted SHA-256 hash.
+
+    Keys look like ``hrs_<key_id>.<secret>``. The public ``key_id`` finds the
+    record; the 256-bit random ``secret`` is checked against its salted hash
+    with a constant-time comparison. (A fast hash is appropriate because the
+    secret is high-entropy random, not a human password.) A key is shown once,
+    at :meth:`issue` time, and cannot be recovered afterwards.
+
+    Supports expiry, revocation and scopes (which tasks the key may call).
+    Records live in memory; use :meth:`export_records` / :meth:`load_records`
+    to persist them in your own store.
+    """
+
+    PREFIX = "hrs_"
+
+    def __init__(self) -> None:
+        self._records: dict[str, _KeyRecord] = {}
+
+    def issue(
+        self,
+        *,
+        principal_id: str,
+        tier: Tier,
+        expires_at: float | None = None,
+        scopes: list[str] | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> str:
+        """Create a key and return it. This is the only time it is available."""
+        key_id = secrets.token_hex(6)
+        secret = secrets.token_urlsafe(32)
+        salt = os.urandom(16)
+        principal = Principal(
+            principal_id=principal_id, tier=tier, scopes=scopes, metadata=metadata or {}
+        )
+        self._records[key_id] = _KeyRecord(salt, _digest(salt, secret), principal, expires_at)
+        return f"{self.PREFIX}{key_id}.{secret}"
+
+    @staticmethod
+    def _split(api_key: str) -> tuple[str, str] | None:
+        if not api_key.startswith(HashedApiKeyValidator.PREFIX) or "." not in api_key:
+            return None
+        key_id, _, secret = api_key[len(HashedApiKeyValidator.PREFIX) :].partition(".")
+        return (key_id, secret) if key_id and secret else None
+
+    def revoke(self, api_key_or_id: str) -> None:
+        """Revoke by full key or by ``key_id``."""
+        parts = self._split(api_key_or_id)
+        record = self._records.get(parts[0] if parts else api_key_or_id)
+        if record is not None:
+            record.revoked = True
+
+    def validate(self, api_key: str) -> Principal:
+        parts = self._split(api_key) if api_key else None
+        if parts is None:
+            raise InvalidApiKeyError("API key is malformed or empty")
+        key_id, secret = parts
+        record = self._records.get(key_id)
+        # Hash even for unknown ids so timing doesn't reveal which ids exist.
+        salt = record.salt if record else bytes(16)
+        expected = record.digest if record else bytes(32)
+        ok = hmac.compare_digest(_digest(salt, secret), expected)
+        if record is None or not ok:
+            raise InvalidApiKeyError("API key is unknown")
+        if record.revoked:
+            raise RevokedApiKeyError(
+                "API key has been revoked", context={"principal_id": record.principal.principal_id}
+            )
+        if record.expires_at is not None and time.time() >= record.expires_at:
+            raise ExpiredApiKeyError(
+                "API key has expired", context={"principal_id": record.principal.principal_id}
+            )
+        return record.principal
+
+    def export_records(self) -> dict[str, dict[str, object]]:
+        """Return a JSON-friendly snapshot for persistence (hashes only, never keys)."""
+        return {
+            kid: {
+                "salt": r.salt.hex(),
+                "digest": r.digest.hex(),
+                "principal": r.principal.model_dump(mode="json"),
+                "expires_at": r.expires_at,
+                "revoked": r.revoked,
+            }
+            for kid, r in self._records.items()
+        }
+
+    def load_records(self, records: dict[str, dict[str, object]]) -> None:
+        """Restore a snapshot made by :meth:`export_records`."""
+        for kid, r in records.items():
+            self._records[kid] = _KeyRecord(
+                salt=bytes.fromhex(str(r["salt"])),
+                digest=bytes.fromhex(str(r["digest"])),
+                principal=Principal.model_validate(r["principal"]),
+                expires_at=r["expires_at"],  # type: ignore[arg-type]
+                revoked=bool(r["revoked"]),
+            )

horasis/access/policy.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from horasis.access.principal import Principal
+from horasis.foundation.config import Config
+from horasis.foundation.errors import AccessDeniedError, ConfigurationError
+from horasis.foundation.schemas import Task
+
+
+class Policy:
+    """Checks whether a principal's tier and key scopes allow a task."""
+
+    def __init__(self, config: Config) -> None:
+        self._config = config
+
+    def authorize(self, principal: Principal, task: Task) -> None:
+        """Raise :class:`AccessDeniedError` unless `principal` may call `task`.
+
+        The tier must be configured and allow `task`, and the key's scopes,
+        if set, must include it.
+        """
+        try:
+            rule = self._config.tier(principal.tier.value)
+        except ConfigurationError as exc:
+            raise AccessDeniedError(
+                f"tier {principal.tier.value!r} is not configured",
+                context={"principal_id": principal.principal_id},
+            ) from exc
+
+        if task.value not in rule.allowed_tasks:
+            raise AccessDeniedError(
+                f"tier {principal.tier.value!r} may not call {task.value!r}",
+                context={
+                    "principal_id": principal.principal_id,
+                    "tier": principal.tier.value,
+                    "task": task.value,
+                },
+            )
+
+        if principal.scopes is not None and task.value not in principal.scopes:
+            raise AccessDeniedError(
+                f"API key is not scoped for {task.value!r}",
+                context={
+                    "principal_id": principal.principal_id,
+                    "task": task.value,
+                    "scopes": list(principal.scopes),
+                },
+            )

horasis/access/principal.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from horasis.access.tiers import Tier
+
+
+class Principal(BaseModel):
+    """An authenticated caller.
+
+    Attributes:
+        principal_id: Stable identifier for the caller (never the raw key).
+        tier: The caller's tier.
+        metadata: Free-form data attached by the key-validation backend
+            (e.g. organization name, plan expiry).
+        scopes: Task values this caller's key may invoke, or ``None`` for
+            "everything the tier allows". Scopes only narrow the tier.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    principal_id: str
+    tier: Tier
+    metadata: dict[str, str] = Field(default_factory=dict)
+    scopes: list[str] | None = None
+
+
+class AnonymousPrincipal(Principal):
+    """Principal for tests and local development."""
+
+    principal_id: str = "anonymous"
+    tier: Tier = Tier.FREE