py-idp 0.3.1__py3-none-any.whl

idp/__init__.py

@@ -0,0 +1,39 @@
+# py-idp: general-purpose, AI-enabled Intelligent Document Processing.
+# Copyright (c) 2026 Royce.
+#
+# Licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later)
+# with the following addition: a commercial license is also available for organizations
+# that wish to embed py-idp in proprietary products / hosted SaaS without the AGPL
+# copyleft obligations. See LICENSE and LICENSE-COMMERCIAL at the repo root, or
+# contact <royce-license-placeholder@protonmail.com> for terms.
+#
+# This Source Code Form is subject to the terms of the AGPL-3.0-or-later.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""py-idp: General-purpose, AI-enabled Intelligent Document Processing framework.
+
+A six-stage pipeline: parse -> classify -> extract -> assess -> validate -> HITL.
+Each stage is a pure function over a Document, pluggable, and independently testable.
+
+Design draws from:
+  - aws-solutions-library-samples/accelerated-intelligent-document-processing-on-aws
+    (pipeline shape, HITL, confidence assessment)
+  - docling-project/docling                   (parser: PDF, tables, reading order)
+  - run-llama/llama_cloud_services            (Pydantic-schema-driven extraction API)
+  - Unstructured-IO/unstructured              (chunking + multi-format ingest)
+"""
+
+from idp.core.document import Block, Document, Page
+from idp.discover import DiscoveryResult, discover_schema
+from idp.pipeline.pipeline import Pipeline, PipelineResult
+
+__version__ = "0.3.2"
+__all__ = [
+    "Block",
+    "DiscoveryResult",
+    "Document",
+    "Page",
+    "Pipeline",
+    "PipelineResult",
+    "discover_schema",
+]

idp/_logging.py

@@ -0,0 +1,69 @@
+"""Structured logging configuration for py-idp.
+
+Provides a single ``get_logger(name)`` helper so every module emits logs
+in the same format (timestamp, level, logger name, message) and honours
+the ``LOG_LEVEL`` environment variable. Production deployments should
+set ``LOG_LEVEL=INFO`` (default) or ``LOG_LEVEL=WARNING`` for quieter
+logs; ``LOG_FORMAT=json`` switches to JSON output for log aggregators.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import sys
+
+_LOG_FORMAT = "%(asctime)s %(levelname)s [%(name)s] %(message)s"
+_LOG_DATEFMT = "%Y-%m-%dT%H:%M:%S%z"
+_CONFIGURED = False
+
+
+def configure(level: str | int | None = None, fmt: str | None = None) -> None:
+    """Idempotent root-logger configuration.
+
+    Reads ``LOG_LEVEL`` and ``LOG_FORMAT`` from env by default. Safe to
+    call multiple times — subsequent calls are no-ops.
+    """
+    global _CONFIGURED
+    if _CONFIGURED:
+        return
+
+    if level is None:
+        level = os.environ.get("LOG_LEVEL", "INFO").upper()
+    if isinstance(level, str):
+        level = getattr(logging, level, logging.INFO)
+
+    if fmt is None:
+        fmt = os.environ.get("LOG_FORMAT", _LOG_FORMAT)
+        if fmt.lower() == "json":
+            fmt = _json_log_format()
+
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter(fmt=fmt, datefmt=_LOG_DATEFMT))
+    root = logging.getLogger()
+    # Replace existing handlers so format is honoured (don't accumulate)
+    root.handlers = [handler]
+    root.setLevel(level)
+    _CONFIGURED = True
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Return a module-level logger. Configures the root on first call."""
+    configure()
+    return logging.getLogger(name)
+
+
+def _json_log_format() -> str:
+    """Build a JSON formatter string consumed by python-json-logger downstream.
+
+    Returns the empty string here so the default Formatter falls back to
+    the human-readable format. Operators wanting JSON should install
+    ``python-json-logger`` and override via ``LOG_FORMAT_HANDLER``.
+    """
+    return _LOG_FORMAT
+
+
+def reset() -> None:
+    """Reset configuration state — for tests only."""
+    global _CONFIGURED
+    _CONFIGURED = False
+    logging.getLogger().handlers = []

idp/_testing_backends.py

@@ -0,0 +1,37 @@
+"""Testing-only LLM backends.
+
+This module is intentionally NOT part of the public ``idp`` namespace.
+Its backends are gated by env vars (``IDP_ENABLE_SLOWMOCK=1``) so
+they cannot be invoked in production by accident.
+"""
+from __future__ import annotations
+
+import random
+import time
+from typing import Any
+
+from idp.llm.backend import CompletionRequest, MockBackend
+
+
+class SlowMockBackend(MockBackend):
+    """A MockBackend that sleeps to simulate real LLM latency.
+
+    Configured by ``LOAD_LATENCY_MS`` (default 1500) +/- ``LOAD_JITTER_MS``
+    (default 500). Only enabled when ``IDP_ENABLE_SLOWMOCK=1``.
+    """
+
+    name = "slowmock"
+
+    def __init__(self, latency_ms: int = 1500, jitter_ms: int = 500, **kwargs: Any):
+        super().__init__(**kwargs)
+        self.latency_ms = latency_ms
+        self.jitter_ms = jitter_ms
+
+    def complete(self, req: CompletionRequest) -> str:
+        sleep_s = (self.latency_ms + random.uniform(-self.jitter_ms, self.jitter_ms)) / 1000.0
+        if sleep_s > 0:
+            time.sleep(sleep_s)
+        return super().complete(req)
+
+
+__all__ = ["SlowMockBackend"]

idp/_util.py

@@ -0,0 +1,38 @@
+# py-idp: general-purpose, AI-enabled Intelligent Document Processing.
+# Copyright (c) 2026 Royce.
+#
+# Licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later)
+# with the following addition: a commercial license is also available for organizations
+# that wish to embed py-idp in proprietary products / hosted SaaS without the AGPL
+# copyleft obligations. See LICENSE and LICENSE-COMMERCIAL at the repo root, or
+# contact <royce-license-placeholder@protonmail.com> for terms.
+#
+# This Source Code Form is subject to the terms of the AGPL-3.0-or-later.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Pretty-print a PipelineResult in a terminal-friendly way."""
+from __future__ import annotations
+
+import json
+
+
+def pretty_print_result(result) -> None:
+    """Console-friendly rendering of a pipeline result."""
+    print(f"\n=== {result.document.source_path} ===")
+    print(f"schema:    {result.schema_name}")
+    print(f"backend:   {result.backend_name} ({result.mode})")
+    print(f"classify:  {result.classification} (conf={result.document.classification_confidence})")
+    print(f"validate:  {'PASS' if result.validation_passed else 'FAIL'}")
+    print("timings:   " + ", ".join(f"{t.name}={t.seconds:.3f}s" for t in result.timings))
+    print("\nextraction:")
+    print(json.dumps(result.document.extraction, indent=2, default=str))
+    if result.confidence:
+        ordered = sorted(result.confidence.items(), key=lambda kv: kv[1])
+        print("\nconfidence (ascending):")
+        for k, v in ordered:
+            mark = " [REVIEW]" if v < 0.6 else ""
+            print(f"  {k:<24} {v:.2f}{mark}")
+    if result.document.errors:
+        print(f"\nerrors ({len(result.document.errors)}):")
+        for e in result.document.errors:
+            print(f"  - {e}")

idp/api.py

@@ -0,0 +1,306 @@
+"""Production-hardened FastAPI server.
+
+Improvements over the original ``examples/api.py``:
+
+* Reads ``Settings`` from env (port, workers, rate limits, max upload
+  size, backend, storage) and **fails fast** on misconfiguration.
+* Health (``/healthz``) and readiness (``/readyz``) endpoints for k8s.
+* Prometheus text exposition at ``/metrics``.
+* Per-key + global rate limiting via ``idp.ratelimit.RateLimiter``.
+* Upload size limit enforced via ``Content-Length`` *and* actual
+  stream read (defends against missing/lying Content-Length headers).
+* ``/version`` endpoint exposes the package version for ops dashboards.
+* Structured request logging with timing.
+
+Not in scope: HTTPS termination (use a reverse proxy), TLS, SSO,
+multi-tenant auth (these are deployment-level concerns).
+"""
+from __future__ import annotations
+
+import os
+import time
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+from fastapi import Depends, FastAPI, Form, HTTPException, Request, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse, PlainTextResponse, Response
+from pydantic import BaseModel
+
+from idp import __version__
+from idp._logging import configure, get_logger
+from idp.config import Settings
+from idp.core.document import Document
+from idp.errors import ConfigurationError, IDPError, RateLimitedError, is_idp_error
+from idp.metrics import metrics
+from idp.pipeline.pipeline import Pipeline
+from idp.ratelimit import RateLimiter
+
+# Module-level logger; configured at lifespan startup.
+_log = get_logger("idp.api")
+_settings: Settings | None = None
+_rate_limiter: RateLimiter | None = None
+_upload_dir: Path | None = None
+
+
+# ---------------------------------------------------------------------------
+# Schemas
+# ---------------------------------------------------------------------------
+class ExtractRequest(BaseModel):
+    schema_name: str | None = None
+    backend: str | None = None
+
+
+class ExtractResponse(BaseModel):
+    schema_name: str | None = None
+    backend_name: str
+    mode: str
+    classification: str | None
+    extraction: dict[str, Any]
+    confidence: dict[str, float] | None
+    validation: dict[str, Any] | None
+
+
+class ReviewRequest(BaseModel):
+    edited: dict[str, Any]
+    reviewer: str
+
+
+# ---------------------------------------------------------------------------
+# Auth
+# ---------------------------------------------------------------------------
+def auth(request: Request) -> None:
+    """Validate the ``X-API-Key`` header against ``Settings.api_key``."""
+    s = _require_settings()
+    if not s.api_key_required:
+        return
+    if s.api_key is None:
+        # No key configured but key required -> fail closed.
+        raise HTTPException(status_code=503, detail="API key required but not configured on server")
+    provided = request.headers.get("X-API-Key") or request.headers.get("Authorization", "").removeprefix("Bearer ").strip()
+    if not provided:
+        raise HTTPException(status_code=401, detail="missing API key")
+    if provided != s.api_key:
+        raise HTTPException(status_code=403, detail="invalid API key")
+    # Record authenticated request for rate-limit accounting
+    if _rate_limiter is not None:
+        _rate_limiter.check(key=provided)
+
+
+# ---------------------------------------------------------------------------
+# Lifespan
+# ---------------------------------------------------------------------------
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Configure logging, validate settings, prep upload dir."""
+    global _settings, _rate_limiter, _upload_dir
+
+    # Load settings (raises ConfigurationError -> startup aborts with 500)
+    try:
+        _settings = Settings.load()
+    except ConfigurationError as e:
+        # Re-raise so uvicorn logs it; we can't return JSON yet because
+        # the app isn't built.
+        _log.error("configuration error: %s", e)
+        raise
+
+    configure(level=_settings.log_level, fmt=_settings.log_format)
+    _log.info("py-idp API starting: host=%s port=%d storage=%s backend=%s",
+              _settings.api_host, _settings.api_port, _settings.storage_backend, _settings.default_backend)
+
+    _rate_limiter = RateLimiter(
+        per_key_per_minute=_settings.rate_limit_per_minute,
+        global_per_minute=0,  # disabled by default; set via env if needed
+    )
+
+    _upload_dir = Path(os.environ.get("IDP_UPLOAD_DIR", "/tmp/idp-uploads"))
+    _upload_dir.mkdir(parents=True, exist_ok=True)
+
+    yield
+
+    # Shutdown: clean up, log final metrics
+    _log.info("py-idp API shutting down. metrics: %s", metrics.snapshot())
+    _settings = None
+    _rate_limiter = None
+    _upload_dir = None
+
+
+app = FastAPI(
+    title="py-idp API",
+    version=__version__,
+    description="Production AI-enabled Intelligent Document Processing API.",
+    lifespan=lifespan,
+)
+
+
+# ---------------------------------------------------------------------------
+# Middleware
+# ---------------------------------------------------------------------------
+@app.middleware("http")
+async def logging_middleware(request: Request, call_next):
+    """Log every request with timing + status code."""
+    start = time.perf_counter()
+    metrics.inc("http_requests", 1, path=request.url.path, method=request.method)
+    try:
+        response = await call_next(request)
+        metrics.inc("http_responses", 1, status=str(response.status_code), path=request.url.path)
+        return response
+    except Exception as e:
+        metrics.inc("http_errors", 1, type=type(e).__name__)
+        _log.exception("request failed: %s %s", request.method, request.url.path)
+        return JSONResponse(
+            status_code=500,
+            content={"error": "internal server error", "type": type(e).__name__,
+                     "is_idp_error": is_idp_error(e)},
+        )
+    finally:
+        elapsed = time.perf_counter() - start
+        metrics.observe("http_request_duration_seconds", elapsed, path=request.url.path)
+
+
+# CORS (configured in lifespan but installed here so the order is correct)
+def _install_cors() -> None:
+    s = _require_settings()
+    if s.cors_origins:
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=list(s.cors_origins),
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+
+# ---------------------------------------------------------------------------
+# Health endpoints
+# ---------------------------------------------------------------------------
+@app.get("/healthz", response_class=PlainTextResponse, include_in_schema=False)
+async def healthz() -> str:
+    """Liveness: returns 200 OK if the process is up. Cheap; no DB call."""
+    return "ok"
+
+
+@app.get("/readyz", response_class=PlainTextResponse, include_in_schema=False)
+async def readyz() -> str:
+    """Readiness: 200 OK if settings are loaded; 503 if not yet ready."""
+    if _settings is None:
+        raise HTTPException(status_code=503, detail="not ready: settings not loaded")
+    return "ready"
+
+
+@app.get("/version", response_class=PlainTextResponse)
+async def version() -> str:
+    """Return the py-idp version."""
+    return __version__
+
+
+@app.get("/metrics", response_class=PlainTextResponse, include_in_schema=False)
+async def prometheus_metrics() -> Response:
+    """Prometheus text-format metrics."""
+    if not _require_settings().metrics_enabled:
+        raise HTTPException(status_code=404, detail="metrics disabled")
+    return PlainTextResponse(metrics.export_prometheus(), media_type="text/plain; version=0.0.4")
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+@app.post("/extract", response_model=ExtractResponse, dependencies=[Depends(auth)])
+async def extract_sync(
+    file: UploadFile,
+    schema_name: str | None = Form(default=None),
+    backend: str | None = Form(default=None),
+) -> ExtractResponse:
+    """Synchronous document extraction. Capped by ``IDP_MAX_UPLOAD_BYTES``.
+
+    Form fields:
+      - ``schema_name`` (optional): Pydantic schema to extract against.
+      - ``backend``    (optional): LLM backend name (e.g. ``mock``, ``openai/gpt-4o``).
+    """
+    s = _require_settings()
+    raw = await _read_capped(file, s.max_upload_bytes)
+    upload_dir = _require_upload_dir()
+    dst = upload_dir / (file.filename or "upload")
+    dst.write_bytes(raw)
+
+    pipeline = Pipeline(
+        backend=backend or s.default_backend,
+        schema=schema_name or "Invoice",
+    )
+    doc = Document.from_path(str(dst))
+    res = pipeline.run(doc)
+    metrics.inc("extractions", 1, backend=res.backend_name, schema=res.schema_name or "_none")
+    return ExtractResponse(
+        schema_name=res.schema_name,
+        backend_name=res.backend_name,
+        mode=res.mode or "ocr_llm",  # type: ignore[arg-type]  # router sets this; defensive against no-LLM paths
+        classification=res.classification,
+        extraction=res.document.extraction or {},
+        confidence=res.confidence,
+        validation=res.document.validation,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Internals
+# ---------------------------------------------------------------------------
+def _require_settings() -> Settings:
+    if _settings is None:
+        raise HTTPException(status_code=503, detail="server not ready")
+    return _settings
+
+
+def _require_upload_dir() -> Path:
+    if _upload_dir is None:
+        raise HTTPException(status_code=503, detail="server not ready: upload dir not configured")
+    return _upload_dir
+
+
+async def _read_capped(file: UploadFile, max_bytes: int) -> bytes:
+    """Read ``file`` but reject payloads larger than ``max_bytes``.
+
+    Defends against missing or lying ``Content-Length`` headers by
+    checking actual bytes-read, not just the advertised length.
+    """
+    # Reject early if Content-Length advertised is over the cap
+    cl = file.headers.get("content-length")
+    if cl is not None:
+        try:
+            if int(cl) > max_bytes:
+                raise HTTPException(
+                    status_code=413,
+                    detail=f"payload too large: {cl} bytes > max {max_bytes}",
+                )
+        except ValueError:
+            pass  # malformed header -> ignore; the chunk loop will catch it
+
+    chunks: list[bytes] = []
+    total = 0
+    chunk_size = 64 * 1024
+    while True:
+        chunk = await file.read(chunk_size)
+        if not chunk:
+            break
+        total += len(chunk)
+        if total > max_bytes:
+            raise HTTPException(
+                status_code=413,
+                detail=f"payload too large: exceeds max {max_bytes} bytes",
+            )
+        chunks.append(chunk)
+    return b"".join(chunks)
+
+
+# Exception handlers — map IDPError subtypes to proper HTTP status codes
+@app.exception_handler(IDPError)
+async def idp_error_handler(request: Request, exc: IDPError) -> JSONResponse:
+    if isinstance(exc, RateLimitedError):
+        return JSONResponse(status_code=429, content={"error": str(exc), "type": type(exc).__name__})
+    return JSONResponse(status_code=400, content={"error": str(exc), "type": type(exc).__name__})
+
+
+# ---------------------------------------------------------------------------
+# Module version (also used by /version endpoint)
+# ---------------------------------------------------------------------------
+__all__ = ["app", "lifespan"]

idp/assess/__init__.py

@@ -0,0 +1,15 @@
+# py-idp: general-purpose, AI-enabled Intelligent Document Processing.
+# Copyright (c) 2026 Royce.
+#
+# Licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later)
+# with the following addition: a commercial license is also available for organizations
+# that wish to embed py-idp in proprietary products / hosted SaaS without the AGPL
+# copyleft obligations. See LICENSE and LICENSE-COMMERCIAL at the repo root, or
+# contact <royce-license-placeholder@protonmail.com> for terms.
+#
+# This Source Code Form is subject to the terms of the AGPL-3.0-or-later.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+from idp.assess.confidence import assess_confidence
+
+__all__ = ["assess_confidence"]

idp/assess/confidence.py

@@ -0,0 +1,130 @@
+# py-idp: general-purpose, AI-enabled Intelligent Document Processing.
+# Copyright (c) 2026 Royce.
+#
+# Licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later)
+# with the following addition: a commercial license is also available for organizations
+# that wish to embed py-idp in proprietary products / hosted SaaS without the AGPL
+# copyleft obligations. See LICENSE and LICENSE-COMMERCIAL at the repo root, or
+# contact <royce-license-placeholder@protonmail.com> for terms.
+#
+# This Source Code Form is subject to the terms of the AGPL-3.0-or-later.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Confidence assessment.
+
+Two strategies:
+  - heuristic: per-field conf derived from extraction-mode + type
+  - llm_self_assess: ask the model to rate each field as 0..1
+
+LLM self-assessment is calibrated poorly in practice (papers repeatedly
+show LLM confidence is overconfident). Heuristic is the default; LLM
+self-assess is opt-in via config.
+"""
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING
+
+from idp.core.document import Document
+from idp.llm.backend import Backend, CompletionRequest, Message
+
+if TYPE_CHECKING:
+    from idp.rl.policy import PolicyConfig
+
+log = logging.getLogger(__name__)
+
+
+def _heuristic_confidence(doc: Document) -> dict[str, float]:
+    """Per-field confidence heuristic. Crude but reproducible.
+
+    Heuristics:
+      - multimodal mode + clean digital -> 0.9 base
+      - OCR_LLM mode -> 0.7 base
+      - per-field: missing/None -> 0.1
+      - per-field: present value (string non-empty, number, list, dict) -> base
+
+    NOTE: a numeric `0.0` or `0` is treated the same as any other present
+    numeric value (conf = base). If you need to penalize zero/extracted-as-zero
+    for compliance reasons, use `assess_confidence(use_llm=True)` or your own
+    rule that down-weights fields known to be "should never be zero".
+    """
+    base = 0.9 if doc.mode == "multimodal" else 0.7
+    out: dict[str, float] = {}
+    extraction = doc.extraction or {}
+    for k, v in extraction.items():
+        if v is None or v == "" or v == [] or v == {}:
+            out[k] = 0.1
+        elif isinstance(v, (int, float)):
+            out[k] = max(0.0, min(1.0, base))
+        elif isinstance(v, str):
+            out[k] = max(0.0, min(1.0, base + 0.05))
+        elif isinstance(v, list):
+            out[k] = max(0.0, min(1.0, base - 0.05))  # harder
+        elif isinstance(v, dict):
+            out[k] = max(0.0, min(1.0, base - 0.05))
+        else:
+            out[k] = base
+    return out
+
+
+def _llm_self_assess(doc: Document, backend: Backend) -> dict[str, float]:
+    snippet = json.dumps(doc.extraction or {}, indent=2)
+    sample_text = (doc.raw_text or "")[:4000]
+    req = CompletionRequest(
+        messages=[
+            Message(
+                role="system",
+                content=(
+                    "You rate extraction confidence per field. "
+                    "Return JSON: {\"field_name\": 0.0-1.0, ...} "
+                    "where 1.0 = definitely correct, 0.0 = definitely wrong or absent."
+                ),
+            ),
+            Message(
+                role="user",
+                content=(
+                    f"SOURCE DOCUMENT (truncated):\n{sample_text}\n\n"
+                    f"EXTRACTION TO RATE:\n{snippet}"
+                ),
+            ),
+        ],
+        json_mode=True,
+        temperature=0.0,
+    )
+    raw = backend.complete(req)
+    try:
+        return {k: float(v) for k, v in json.loads(raw).items()}
+    except Exception as e:  # noqa: BLE001
+        log.debug("llm self-assess parse failed: %s", e)
+        return {}
+
+
+def assess_confidence(
+    doc: Document,
+    backend: Backend | None = None,
+    use_llm: bool = False,
+    policy: PolicyConfig | None = None,
+) -> Document:
+    """Attach doc.confidence (per-field dict of floats in 0..1).
+
+    If a `policy` is provided (an `idp.rl.PolicyConfig`), apply per-field
+    penalties so that fields humans have corrected frequently get
+    lower confidence scores and surface to HITL review.
+    """
+    conf = _heuristic_confidence(doc)
+    if use_llm and backend is not None:
+        try:
+            llm_conf = _llm_self_assess(doc, backend)
+            # blend: 70% heuristic (more honest), 30% self-assess
+            conf = {k: 0.7 * conf.get(k, 0.5) + 0.3 * llm_conf.get(k, 0.5) for k in conf}
+        except Exception as e:  # noqa: BLE001
+            doc.errors.append(f"assess_failed: {e}")
+    if policy is not None:
+        try:
+            from idp.rl.policy import policy_to_penalised_confidence
+            conf = policy_to_penalised_confidence(conf, policy)
+        except Exception as e:  # noqa: BLE001
+            doc.errors.append(f"policy_apply_failed: {e}")
+    doc.confidence = conf
+    return doc

idp/auth/__init__.py

@@ -0,0 +1,21 @@
+# py-idp: general-purpose, AI-enabled Intelligent Document Processing.
+# Copyright (c) 2026 Royce.
+#
+# Licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later)
+# with the following addition: a commercial license is also available for organizations
+# that wish to embed py-idp in proprietary products / hosted SaaS without the AGPL
+# copyleft obligations. See LICENSE and LICENSE-COMMERCIAL at the repo root, or
+# contact <royce-license-placeholder@protonmail.com> for terms.
+#
+# This Source Code Form is subject to the terms of the AGPL-3.0-or-later.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+from idp.auth.keys import (
+    AuthContext,
+    hash_key,
+    make_default_key,
+    require_api_key,
+    verify,
+)
+
+__all__ = ["AuthContext", "hash_key", "make_default_key", "require_api_key", "verify"]