ironeye 1.0.0__tar.gz

ironeye-1.0.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

ironeye-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+# The build this repository has to pass. It runs on the supported floor and the
+# current release of the toolchain, because a client library that only builds on
+# the version its author happened to have installed is a support ticket waiting.
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install --upgrade pip build httpx
+      - name: Import the package from a clean install
+        run: |
+          pip install .
+          python -c "import ironeye; print(ironeye.__version__)"
+      - run: python -m build

ironeye-1.0.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.egg-info/
+dist/
+build/
+.venv/

ironeye-1.0.0/LICENSE

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

ironeye-1.0.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.5
+Name: ironeye
+Version: 1.0.0
+Summary: Official Python client for the IronEye document intelligence and collection API.
+Project-URL: Documentation, https://ironeye.org/docs/sdk/python
+Project-URL: Homepage, https://ironeye.org
+Project-URL: Repository, https://github.com/IronEyeAPI/ironeye-python
+Project-URL: Issues, https://github.com/IronEyeAPI/ironeye-python/issues
+Author: Direct Softworks
+License-Expression: MIT
+License-File: LICENSE
+Keywords: document,gdpr,ironeye,malware,osint,pii,secrets
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# IronEye for Python
+
+The official Python client for the [IronEye](https://ironeye.org) API: document
+analysis over bytes you send, and normalised collection from public sources,
+behind one key.
+
+```sh
+pip install ironeye
+```
+
+## Features
+
+- Synchronous and `async` clients over one shared transport, so the two cannot
+  drift apart.
+- Every analysis route, the async job path with `await_job`, the collection
+  catalogue and the data-subject-rights endpoints.
+- `TypedDict` models, and one exception class per refusal family.
+- Retries on the server's own `retryable` flag, honouring `Retry-After`.
+- Logs to the `ironeye` logger. No credential, no payload.
+
+Full documentation, including every endpoint and every option, is at
+**https://ironeye.org/docs/sdk/python**.
+
+---
+
+Direct Softworks · [MIT](LICENSE) · issues and pull requests welcome

ironeye-1.0.0/README.md

@@ -0,0 +1,26 @@
+# IronEye for Python
+
+The official Python client for the [IronEye](https://ironeye.org) API: document
+analysis over bytes you send, and normalised collection from public sources,
+behind one key.
+
+```sh
+pip install ironeye
+```
+
+## Features
+
+- Synchronous and `async` clients over one shared transport, so the two cannot
+  drift apart.
+- Every analysis route, the async job path with `await_job`, the collection
+  catalogue and the data-subject-rights endpoints.
+- `TypedDict` models, and one exception class per refusal family.
+- Retries on the server's own `retryable` flag, honouring `Retry-After`.
+- Logs to the `ironeye` logger. No credential, no payload.
+
+Full documentation, including every endpoint and every option, is at
+**https://ironeye.org/docs/sdk/python**.
+
+---
+
+Direct Softworks · [MIT](LICENSE) · issues and pull requests welcome

ironeye-1.0.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ironeye"
+version = "1.0.0"
+description = "Official Python client for the IronEye document intelligence and collection API."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Direct Softworks" }]
+keywords = ["ironeye", "document", "pii", "malware", "secrets", "gdpr", "osint"]
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Documentation = "https://ironeye.org/docs/sdk/python"
+Homepage = "https://ironeye.org"
+Repository = "https://github.com/IronEyeAPI/ironeye-python"
+Issues = "https://github.com/IronEyeAPI/ironeye-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ironeye"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true

ironeye-1.0.0/src/ironeye/__init__.py

@@ -0,0 +1,67 @@
+"""Official Python client for the IronEye API.
+
+    from ironeye import IronEye
+
+    with IronEye() as eye:                      # IRONEYE_API_KEY from the env
+        result = eye.secrets({"input": {"text": open("config.env").read()}})
+        print(result["security"]["secrets"]["secret_count"])
+
+Logging goes to the ``ironeye`` logger and is silent until you configure it.
+No credential and no payload is ever written to it.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from .client import VERSION, AsyncIronEye, IronEye, from_bytes
+from .errors import (
+    APIError,
+    AuthenticationError,
+    ComplianceError,
+    ConnectionError,
+    InvalidRequestError,
+    IronEyeError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    ServerError,
+    UpstreamError,
+)
+
+__all__ = [
+    "IronEye",
+    "AsyncIronEye",
+    "VERSION",
+    "from_bytes",
+    "IronEyeError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionError",
+    "RateLimitError",
+    "InvalidRequestError",
+    "NotFoundError",
+    "ComplianceError",
+    "UpstreamError",
+    "ServerError",
+    "ConnectionError",
+]
+
+__version__ = VERSION
+
+# A library that configures logging for its host is a library that has to be
+# undone; the handler is here only so an unconfigured application is quiet.
+logging.getLogger("ironeye").addHandler(logging.NullHandler())
+
+
+def this() -> None:
+    print(
+        "Evidence beats assertion.\n"
+        "A byte offset beats a summary.\n"
+        "Observed is not inferred, and inferred says so.\n"
+        "Refuse loudly rather than guess quietly.\n"
+        "A finding you cannot check is a rumour.\n"
+        "Nothing touches disk.\n"
+        "\n"
+        "  ...forged at Direct Softworks."
+    )

ironeye-1.0.0/src/ironeye/client.py

@@ -0,0 +1,481 @@
+"""The synchronous and asynchronous clients.
+
+Both are thin wrappers over one ``httpx`` client. Everything that decides
+behaviour -- the URL, the headers, whether a failure is worth another attempt,
+how long to wait -- lives in ``_Transport`` and is shared, so the two clients
+cannot drift apart in the only ways that would matter.
+"""
+
+from __future__ import annotations
+
+import base64 as _base64
+import json
+import logging
+import os
+import random
+import time
+from typing import Any, Literal, Mapping
+from urllib.parse import quote
+
+import httpx
+
+from .errors import APIError, ConnectionError, error_from
+from .models import AnalyzeRequest, Declaration, Envelope, Job, Subject
+
+__all__ = ["IronEye", "AsyncIronEye", "VERSION"]
+
+VERSION = "1.0.0"
+
+_DEFAULT_BASE_URL = "https://ironeye.org"
+_RETRYABLE_STATUS = frozenset({408, 425, 429, 500, 502, 503, 504})
+
+_log = logging.getLogger("ironeye")
+
+_ANALYSIS_ROUTES: dict[str, str] = {
+    "analyze": "/v1/analyze",
+    "extract": "/v1/extract",
+    "classify": "/v1/classify",
+    "pii": "/v1/pii/analyze",
+    "moderation": "/v1/moderation/analyze",
+    "malware": "/v1/malware/scan",
+    "secrets": "/v1/secrets/scan",
+    "validate": "/v1/validate",
+    "deduplicate": "/v1/deduplicate",
+    "invoices": "/v1/invoices/parse",
+}
+
+
+def _mask(key: str) -> str:
+    """Enough of the key to recognise it in a log, never enough to use it."""
+    return f"{key[:9]}..." if len(key) > 12 else "..."
+
+
+def _declaration_headers(declaration: Declaration | None) -> dict[str, str]:
+    if not declaration:
+        return {}
+    names = {
+        "legal_basis": "X-Legal-Basis",
+        "purpose": "X-Purpose",
+        "controller": "X-Controller",
+        "basis_evidence": "X-Basis-Evidence",
+        "special_condition": "X-Special-Condition",
+        "projection": "X-Projection",
+    }
+    return {names[key]: str(value) for key, value in declaration.items() if key in names and value}
+
+
+class _Transport:
+    """Everything both clients must agree on."""
+
+    def __init__(
+        self,
+        api_key: str | None,
+        base_url: str | None,
+        timeout: float,
+        max_retries: int,
+        default_headers: Mapping[str, str] | None,
+    ) -> None:
+        key = api_key or os.environ.get("IRONEYE_API_KEY")
+        if not key:
+            raise ValueError("An API key is required: pass api_key= or set IRONEYE_API_KEY.")
+        self.api_key = key
+        self.base_url = (base_url or os.environ.get("IRONEYE_BASE_URL") or _DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.headers = {
+            "accept": "application/json",
+            "authorization": f"Bearer {key}",
+            "user-agent": f"ironeye-python/{VERSION}",
+            **{k.lower(): v for k, v in (default_headers or {}).items()},
+        }
+
+    def interpret(self, response: httpx.Response, path: str, elapsed: float) -> Any:
+        request_id = response.headers.get("x-request-id", "-")
+        _log.debug(
+            "ironeye %s %s -> %s in %.0fms (request_id=%s)",
+            response.request.method,
+            path,
+            response.status_code,
+            elapsed * 1000,
+            request_id,
+        )
+        if response.status_code in (204, 205):
+            return None
+        if not response.content:
+            payload: Any = None
+        else:
+            try:
+                payload = response.json()
+            except ValueError:
+                payload = {"error": {"code": "INTERNAL", "message": response.text[:200]}}
+        if response.is_success:
+            return payload
+        raise error_from(response.status_code, payload)
+
+    def should_retry(self, error: APIError, attempt: int) -> bool:
+        return (
+            attempt < self.max_retries
+            and error.retryable
+            and error.status in _RETRYABLE_STATUS
+        )
+
+    def wait_for(self, attempt: int, response: httpx.Response | None, code: str, path: str) -> float:
+        """Retry-After is the server's own number, so it wins over the curve."""
+        advised = (response.headers.get("retry-after") if response is not None else None) or ""
+        seconds = float(advised) if advised.isdigit() else 0.25 * (2**attempt) + random.random() / 4
+        _log.warning("ironeye %s retrying after %s in %.0fms", path, code, seconds * 1000)
+        return seconds
+
+
+class _Base:
+    """The call surface, in terms of one abstract ``_request``."""
+
+    _transport: _Transport
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:  # pragma: no cover
+        raise NotImplementedError
+
+    # -- analysis ----------------------------------------------------------
+    def analyze(self, request: AnalyzeRequest, *, idempotency_key: str | None = None) -> Any:
+        return self._analysis("analyze", request, idempotency_key)
+
+    def extract(self, request: AnalyzeRequest, *, idempotency_key: str | None = None) -> Any:
+        return self._analysis("extract", request, idempotency_key)
+
+    def classify(self, request: AnalyzeRequest, *, idempotency_key: str | None = None) -> Any:
+        return self._analysis("classify", request, idempotency_key)
+
+    def pii(self, request: AnalyzeRequest, *, idempotency_key: str | None = None) -> Any:
+        return self._analysis("pii", request, idempotency_key)
+
+    def moderation(self, request: AnalyzeRequest, *, idempotency_key: str | None = None) -> Any:
+        return self._analysis("moderation", request, idempotency_key)
+
+    def malware(self, request: AnalyzeRequest, *, idempotency_key: str | None = None) -> Any:
+        return self._analysis("malware", request, idempotency_key)
+
+    def secrets(self, request: AnalyzeRequest, *, idempotency_key: str | None = None) -> Any:
+        return self._analysis("secrets", request, idempotency_key)
+
+    def validate(self, request: AnalyzeRequest, *, idempotency_key: str | None = None) -> Any:
+        return self._analysis("validate", request, idempotency_key)
+
+    def deduplicate(self, request: AnalyzeRequest, *, idempotency_key: str | None = None) -> Any:
+        return self._analysis("deduplicate", request, idempotency_key)
+
+    def invoices(self, request: AnalyzeRequest, *, idempotency_key: str | None = None) -> Any:
+        return self._analysis("invoices", request, idempotency_key)
+
+    def _analysis(self, name: str, request: AnalyzeRequest, key: str | None) -> Any:
+        headers = {"Idempotency-Key": key} if key else None
+        return self._request("POST", _ANALYSIS_ROUTES[name], json=request, headers=headers)
+
+    # -- jobs --------------------------------------------------------------
+    def create_job(self, request: AnalyzeRequest) -> Any:
+        return self._request("POST", "/v1/jobs", json=request)
+
+    def get_job(self, job_id: str) -> Any:
+        return self._request("GET", f"/v1/jobs/{quote(job_id, safe='')}")
+
+    def delete_job(self, job_id: str) -> Any:
+        return self._request("DELETE", f"/v1/jobs/{quote(job_id, safe='')}")
+
+    # -- collection --------------------------------------------------------
+    def catalogue(self) -> Any:
+        return self._request("GET", "/v1/harvest/catalogue")
+
+    def operations(self, platform: str | None = None) -> Any:
+        params = {"platform": platform} if platform else None
+        return self._request("GET", "/v1/harvest/operations", params=params)
+
+    def operation(self, op_id: str) -> Any:
+        return self._request("GET", f"/v1/harvest/operations/{quote(op_id, safe='')}")
+
+    def collect(
+        self,
+        path: str,
+        params: Mapping[str, Any] | None = None,
+        declaration: Declaration | None = None,
+    ) -> Any:
+        """Runs one collection operation, addressed by its own route.
+
+        ``path`` is what the catalogue gives: ``/v1/harvest/reddit/subreddit``.
+        """
+        return self._request(
+            "GET", path, params=dict(params or {}), headers=_declaration_headers(declaration)
+        )
+
+    def collect_post(
+        self,
+        path: str,
+        params: Mapping[str, Any] | None = None,
+        declaration: Declaration | None = None,
+    ) -> Any:
+        """``collect`` for the operations the registry declares as POST.
+
+        The parameters are identical; only where they travel changes.
+        """
+        return self._request(
+            "POST", path, json=dict(params or {}), headers=_declaration_headers(declaration)
+        )
+
+    # -- data subject rights ----------------------------------------------
+    def gdpr_notice(self) -> Any:
+        return self._request("GET", "/v1/gdpr/notice")
+
+    def erasure(self, subject: Subject) -> Any:
+        return self._request("POST", "/v1/gdpr/erasure", json=subject)
+
+    def objection(self, subject: Subject) -> Any:
+        return self._request("POST", "/v1/gdpr/objections", json=subject)
+
+    def access_request(self, subject: Subject) -> Any:
+        return self._request("POST", "/v1/gdpr/access", json=subject)
+
+    def suppression(self) -> Any:
+        return self._request("GET", "/v1/gdpr/suppression")
+
+    def unsuppress(self, subject_key: str) -> Any:
+        return self._request("DELETE", f"/v1/gdpr/suppression/{quote(subject_key, safe='')}")
+
+    # -- service -----------------------------------------------------------
+    def health(self) -> Any:
+        return self._request("GET", "/healthz")
+
+    def ready(self) -> Any:
+        return self._request("GET", "/readyz")
+
+    def features(self) -> Any:
+        return self._request("GET", "/v1/features")
+
+    def status(self) -> Any:
+        return self._request("GET", "/v1/status")
+
+    def audit_head(self) -> Any:
+        return self._request("GET", "/v1/audit/head")
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(base_url={self._transport.base_url!r}, key={_mask(self._transport.api_key)!r})"
+
+    def __invert__(self) -> Any:
+        return self.health()
+
+
+def _upload_parts(
+    file: bytes,
+    filename: str,
+    content_type: str,
+    features: list[str] | None,
+    preset: str | None,
+    options: dict[str, Any] | None,
+    output_mode: str | None,
+    retention_seconds: int | None,
+) -> tuple[dict[str, Any], dict[str, str]]:
+    files = {"file": (filename, file, content_type)}
+    data: dict[str, str] = {}
+    if features:
+        data["features"] = ",".join(features)
+    if preset:
+        data["preset"] = preset
+    if options:
+        data["options"] = json.dumps(options)
+    if output_mode:
+        data["output_mode"] = output_mode
+    if retention_seconds is not None:
+        data["retention_seconds"] = str(retention_seconds)
+    return files, data
+
+
+class IronEye(_Base):
+    """The synchronous client.
+
+    Usable as a context manager, and safe to share between threads: ``httpx``
+    handles the pooling and nothing here is per-request state.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        default_headers: Mapping[str, str] | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._transport = _Transport(api_key, base_url, timeout, max_retries, default_headers)
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self._owns_http = http_client is None
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> IronEye:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def analyze_upload(
+        self,
+        file: bytes,
+        *,
+        filename: str = "document",
+        content_type: str = "application/octet-stream",
+        features: list[str] | None = None,
+        preset: str | None = None,
+        options: dict[str, Any] | None = None,
+        output_mode: Literal["canonical", "redacted"] | None = None,
+        retention_seconds: int | None = None,
+        idempotency_key: str | None = None,
+    ) -> Envelope:
+        """Multipart, for bytes you hold already rather than base64 in a body."""
+        files, data = _upload_parts(
+            file, filename, content_type, features, preset, options, output_mode, retention_seconds
+        )
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self._request("POST", "/v1/analyze/upload", files=files, data=data, headers=headers)
+
+    def await_job(self, job_id: str, *, interval: float = 2.0, timeout: float = 300.0) -> Job:
+        """Polls until the job settles.
+
+        Nothing in the service dispatches to a callback URL, so polling is the
+        whole of the asynchronous contract.
+        """
+        deadline = time.monotonic() + timeout
+        while True:
+            job = self.get_job(job_id)
+            if job.get("status") in ("completed", "failed"):
+                return job
+            if time.monotonic() + interval > deadline:
+                raise TimeoutError(f"Job {job_id} was still {job.get('status')} after {timeout}s.")
+            time.sleep(interval)
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        transport = self._transport
+        headers = {**transport.headers, **{k: v for k, v in (kwargs.pop("headers", None) or {}).items()}}
+        url = transport.base_url + path
+        last: Exception | None = None
+        for attempt in range(transport.max_retries + 1):
+            started = time.monotonic()
+            try:
+                response = self._http.request(
+                    method, url, headers=headers, timeout=transport.timeout, **kwargs
+                )
+            except httpx.HTTPError as failure:
+                last = ConnectionError(f"{method} {path} failed: {failure}")
+                if attempt >= transport.max_retries:
+                    raise last from failure
+                time.sleep(transport.wait_for(attempt, None, "CONNECTION", path))
+                continue
+            try:
+                return transport.interpret(response, path, time.monotonic() - started)
+            except APIError as error:
+                if not transport.should_retry(error, attempt):
+                    raise
+                last = error
+                time.sleep(transport.wait_for(attempt, response, error.code, path))
+        raise last or ConnectionError(f"{method} {path} exhausted its retries.")
+
+
+class AsyncIronEye(_Base):
+    """The asynchronous client. The same surface, awaited."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        default_headers: Mapping[str, str] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._transport = _Transport(api_key, base_url, timeout, max_retries, default_headers)
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+        self._owns_http = http_client is None
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncIronEye:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def analyze_upload(
+        self,
+        file: bytes,
+        *,
+        filename: str = "document",
+        content_type: str = "application/octet-stream",
+        features: list[str] | None = None,
+        preset: str | None = None,
+        options: dict[str, Any] | None = None,
+        output_mode: Literal["canonical", "redacted"] | None = None,
+        retention_seconds: int | None = None,
+        idempotency_key: str | None = None,
+    ) -> Envelope:
+        files, data = _upload_parts(
+            file, filename, content_type, features, preset, options, output_mode, retention_seconds
+        )
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return await self._request(
+            "POST", "/v1/analyze/upload", files=files, data=data, headers=headers
+        )
+
+    async def await_job(self, job_id: str, *, interval: float = 2.0, timeout: float = 300.0) -> Job:
+        import asyncio
+
+        deadline = time.monotonic() + timeout
+        while True:
+            job = await self.get_job(job_id)
+            if job.get("status") in ("completed", "failed"):
+                return job
+            if time.monotonic() + interval > deadline:
+                raise TimeoutError(f"Job {job_id} was still {job.get('status')} after {timeout}s.")
+            await asyncio.sleep(interval)
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> Any:  # type: ignore[override]
+        import asyncio
+
+        transport = self._transport
+        headers = {**transport.headers, **{k: v for k, v in (kwargs.pop("headers", None) or {}).items()}}
+        url = transport.base_url + path
+        last: Exception | None = None
+        for attempt in range(transport.max_retries + 1):
+            started = time.monotonic()
+            try:
+                response = await self._http.request(
+                    method, url, headers=headers, timeout=transport.timeout, **kwargs
+                )
+            except httpx.HTTPError as failure:
+                last = ConnectionError(f"{method} {path} failed: {failure}")
+                if attempt >= transport.max_retries:
+                    raise last from failure
+                await asyncio.sleep(transport.wait_for(attempt, None, "CONNECTION", path))
+                continue
+            try:
+                return transport.interpret(response, path, time.monotonic() - started)
+            except APIError as error:
+                if not transport.should_retry(error, attempt):
+                    raise
+                last = error
+                await asyncio.sleep(transport.wait_for(attempt, response, error.code, path))
+        raise last or ConnectionError(f"{method} {path} exhausted its retries.")
+
+    def __invert__(self) -> Any:
+        return self.health()
+
+
+def from_bytes(data: bytes, filename: str | None = None, content_type: str | None = None) -> dict[str, Any]:
+    """Builds the ``input`` object for a JSON body out of raw bytes."""
+    source: dict[str, Any] = {"base64": _base64.b64encode(data).decode("ascii")}
+    if filename:
+        source["filename"] = filename
+    if content_type:
+        source["content_type"] = content_type
+    return source

ironeye-1.0.0/src/ironeye/errors.py

@@ -0,0 +1,118 @@
+"""The error contract, one class per family.
+
+Every attribute here is one the server actually sends. ``retryable`` is the
+server's own verdict rather than an inference from the status code: a 429 from
+a spent monthly allowance is not the same wait as a 429 from a rate limiter,
+and only the body tells them apart.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = [
+    "IronEyeError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionError",
+    "RateLimitError",
+    "InvalidRequestError",
+    "NotFoundError",
+    "ComplianceError",
+    "UpstreamError",
+    "ServerError",
+    "ConnectionError",
+]
+
+
+class IronEyeError(Exception):
+    """Base of every error this package raises."""
+
+
+class APIError(IronEyeError):
+    """An error the server described in its response body."""
+
+    def __init__(self, status: int, body: dict[str, Any]) -> None:
+        self.status = status
+        self.code: str = body.get("code", "INTERNAL")
+        self.message: str = body.get("message", "The request failed.")
+        self.retryable: bool = bool(body.get("retryable", False))
+        self.request_id: str = body.get("request_id", "-")
+        self.suggested_action: str = body.get("suggested_action", "")
+        self.doc: str = body.get("doc", "")
+        self.path: str | None = body.get("path")
+        self.meta: dict[str, Any] = body.get("meta", {})
+        super().__init__(f"{self.code}: {self.message} (request_id={self.request_id})")
+
+
+class AuthenticationError(APIError):
+    pass
+
+
+class PermissionError(APIError):  # noqa: A001 - the API's own vocabulary wins here
+    pass
+
+
+class RateLimitError(APIError):
+    pass
+
+
+class InvalidRequestError(APIError):
+    pass
+
+
+class NotFoundError(APIError):
+    pass
+
+
+class ComplianceError(APIError):
+    pass
+
+
+class UpstreamError(APIError):
+    pass
+
+
+class ServerError(APIError):
+    pass
+
+
+class ConnectionError(IronEyeError):  # noqa: A001 - shadows the builtin deliberately
+    """A transport failure, where there is no server verdict to read."""
+
+    retryable = True
+
+
+_FAMILIES: dict[str, type[APIError]] = {
+    "UNAUTHENTICATED": AuthenticationError,
+    "FORBIDDEN_SCOPE": PermissionError,
+    "PLAN_LIMITED": PermissionError,
+    "RATE_LIMITED": RateLimitError,
+    "QUOTA_EXHAUSTED": RateLimitError,
+    "TENANT_BUSY": RateLimitError,
+    "NOT_FOUND": NotFoundError,
+    "COMPLIANCE_REFUSED": ComplianceError,
+    "COLLECTION_BLOCKED": ComplianceError,
+    "SOURCE_NOT_CONFIGURED": UpstreamError,
+    "UPSTREAM_REFUSED": UpstreamError,
+    "UPSTREAM_THROTTLED": UpstreamError,
+    "INTERNAL": ServerError,
+    "DEPENDENCY_UNAVAILABLE": ServerError,
+    "SERVER_DRAINING": ServerError,
+}
+
+
+def error_from(status: int, payload: Any) -> APIError:
+    """Builds the narrowest error class the response body justifies."""
+    body = payload.get("error") if isinstance(payload, dict) else None
+    if not isinstance(body, dict) or "code" not in body:
+        return ServerError(
+            status,
+            {
+                "code": "INTERNAL",
+                "message": f"The server returned {status} with no error body.",
+                "retryable": status >= 500,
+                "suggested_action": "Retry, and quote the status if it persists.",
+            },
+        )
+    return _FAMILIES.get(body["code"], InvalidRequestError)(status, body)

ironeye-1.0.0/src/ironeye/models.py

@@ -0,0 +1,164 @@
+"""Request and response shapes, transcribed from the server's own types.
+
+They are ``TypedDict`` rather than dataclasses on purpose: a response is JSON
+the server owns, and a class that has to be kept in step with it would fail
+closed on a field the engine added this morning. These annotate; they never
+gate.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, NotRequired, TypedDict
+
+__all__ = [
+    "Source",
+    "Output",
+    "AnalyzeRequest",
+    "Evidence",
+    "Finding",
+    "ModuleResult",
+    "Envelope",
+    "Job",
+    "Declaration",
+    "Collection",
+    "Subject",
+    "Preset",
+    "LawfulBasis",
+]
+
+Preset = Literal[
+    "minimal", "standard", "business", "security", "compliance", "forensic", "media", "all-safe"
+]
+
+LawfulBasis = Literal[
+    "consent",
+    "contract",
+    "legal_obligation",
+    "vital_interests",
+    "public_task",
+    "legitimate_interests",
+]
+
+SpecialCondition = Literal[
+    "explicit_consent", "manifestly_public", "legal_claims", "research_statistics"
+]
+
+Projection = Literal["minimal", "standard", "full"]
+
+
+class Source(TypedDict, total=False):
+    """Exactly one of ``text``, ``base64`` or ``url``. Two is refused, so is none."""
+
+    text: str
+    base64: str
+    url: str
+    filename: str
+    content_type: str
+
+
+class Output(TypedDict, total=False):
+    mode: Literal["canonical", "redacted"]
+    include_findings: bool
+
+
+class AnalyzeRequest(TypedDict, total=False):
+    input: Source
+    features: list[str]
+    preset: str
+    options: dict[str, Any]
+    output: Output
+    retention_seconds: int
+    callback_url: str
+
+
+class Evidence(TypedDict, total=False):
+    text_span: tuple[int, int]
+    page: int
+    bbox: tuple[float, float, float, float]
+    time_range: tuple[float, float]
+    container_path: str
+
+
+class Finding(TypedDict):
+    id: str
+    type: str
+    category: str
+    epistemic: Literal["observed", "derived", "inferred", "validated"]
+    confidence: float
+    status: str
+    sensitive: bool
+    evidence: Evidence
+    method: dict[str, Any]
+    created_at: str
+    value: NotRequired[str | None]
+    normalized: NotRequired[Any]
+    severity: NotRequired[Literal["info", "low", "medium", "high", "critical"] | None]
+    redacted: NotRequired[bool]
+    attributes: NotRequired[dict[str, Any]]
+
+
+class ModuleResult(TypedDict, total=False):
+    status: str
+    cached: bool
+    findings: list[Finding]
+
+
+class Envelope(TypedDict, total=False):
+    """The sections are named for how the engine came to know each one."""
+
+    request_id: str
+    status: str
+    engine: dict[str, str]
+    input: dict[str, Any]
+    classification: dict[str, Any]
+    observed: dict[str, ModuleResult]
+    derived: dict[str, ModuleResult]
+    inferred: dict[str, ModuleResult]
+    validated: dict[str, ModuleResult]
+    safety: dict[str, ModuleResult]
+    privacy: dict[str, ModuleResult]
+    security: dict[str, ModuleResult]
+    compliance: dict[str, ModuleResult]
+    provenance: dict[str, Any]
+    retention: dict[str, Any]
+    actions: list[Any]
+    created_at: str
+
+
+class Job(TypedDict, total=False):
+    id: str
+    status: Literal["queued", "running", "completed", "failed"]
+    retention_seconds: int
+    created_at: str
+    result: Envelope
+
+
+class Declaration(TypedDict, total=False):
+    """What a collection call declares about itself.
+
+    Required on any operation whose ``personal_data`` flag is true: the server
+    refuses rather than assumes.
+    """
+
+    legal_basis: LawfulBasis
+    purpose: str
+    controller: str
+    basis_evidence: str
+    special_condition: SpecialCondition
+    projection: Projection
+
+
+class Collection(TypedDict, total=False):
+    request_id: str
+    operation: str
+    entity: str
+    data: Any
+    collection: dict[str, Any]
+    compliance: dict[str, Any]
+    paging: dict[str, Any]
+
+
+class Subject(TypedDict, total=False):
+    platform: str
+    identifier: str
+    reference: str