spot-sdk-python 2.0.0b6__tar.gz → 2.0.0b8__tar.gz

{spot_sdk_python-2.0.0b6 → spot_sdk_python-2.0.0b8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spot-sdk-python
-Version: 2.0.0b6
+Version: 2.0.0b8
 Summary: SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers
 License: Apache-2.0
 Author: SPOT Project
@@ -13,12 +13,13 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3.15
-Requires-Dist: fastapi (>=0.115.3,<1)
-Requires-Dist: httpx (>=0.25,<1)
+Requires-Dist: fastapi (>=0.133.0,<1)
+Requires-Dist: httpx2 (>=2.13.1,<3)
 Requires-Dist: idna (>=3.11,<4)
 Requires-Dist: pydantic (>=2.10,<3.0)
 Requires-Dist: pydantic-settings (>=2.0.0,<3.0.0)
 Requires-Dist: selectolax (>=1.0,<1.1)
+Requires-Dist: starlette (>=1.7.0,<2)
 Project-URL: Homepage, https://sonn.lu
 Description-Content-Type: text/markdown
 
@@ -50,7 +51,7 @@ plugins share:
 ## Install
 
 ```bash
-pip install spot-sdk-python==2.0.0b6
+pip install spot-sdk-python==2.0.0b8
 ```
 
 Python 3.11 to 3.15. Version 2 implements plugin contract 2, for
@@ -75,7 +76,7 @@ from spot_sdk.signals import AUTH_DMARC_FAIL
 MANIFEST = Manifest(
     id="analyzer-dmarc",
     version="1.0.0",
-    kinds=[PluginKind.ANALYZER],
+    kind=PluginKind.ANALYZER,
     egress=Egress.NONE,
 )
 

{spot_sdk_python-2.0.0b6 → spot_sdk_python-2.0.0b8}/README.md

@@ -26,7 +26,7 @@ plugins share:
 ## Install
 
 ```bash
-pip install spot-sdk-python==2.0.0b6
+pip install spot-sdk-python==2.0.0b8
 ```
 
 Python 3.11 to 3.15. Version 2 implements plugin contract 2, for
@@ -51,7 +51,7 @@ from spot_sdk.signals import AUTH_DMARC_FAIL
 MANIFEST = Manifest(
     id="analyzer-dmarc",
     version="1.0.0",
-    kinds=[PluginKind.ANALYZER],
+    kind=PluginKind.ANALYZER,
     egress=Egress.NONE,
 )
 

{spot_sdk_python-2.0.0b6 → spot_sdk_python-2.0.0b8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "spot-sdk-python"
-version = "2.0.0b6"
+version = "2.0.0b8"
 description = "SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers"
 authors = ["SPOT Project <spot@sonn.lu>"]
 license = "Apache-2.0"
@@ -18,14 +18,15 @@ packages = [
 python = ">=3.11,<3.16"
 pydantic = "^2.10"
 pydantic-settings = "^2.0.0"
-httpx = ">=0.25,<1"
+httpx2 = ">=2.13.1,<3"
 selectolax = ">=1.0,<1.1"
 idna = ">=3.11,<4"
-fastapi = ">=0.115.3,<1"
+fastapi = ">=0.133.0,<1"
+starlette = ">=1.7.0,<2"
 
 [tool.poetry.group.dev.dependencies]
-pytest = "^7.4.0"
-pytest-asyncio = "^0.21.0"
+pytest = "^9.0.3"
+pytest-asyncio = "^1.3.0"
 pytest-cov = "^4.1.0"
 mypy = "^1.5.0"
 

{spot_sdk_python-2.0.0b6 → spot_sdk_python-2.0.0b8}/spot_sdk/__init__.py

@@ -47,7 +47,7 @@ if TYPE_CHECKING:
     from .knowledge import KnowledgeClient, KnowledgeDocument, chunk_text, content_hash
     from .llm import LLMClient, LLMOutputError, LLMToolCall, LLMToolCalls, LLMToolRound
 
-# The modules that import FastAPI, Starlette or httpx load on first use, so importing
+# The modules that import FastAPI, Starlette or httpx2 load on first use, so importing
 # `spot_sdk.mime` or the models stays light (PEP 562).
 _LAZY = {
     **dict.fromkeys(("PluginHealth", "SyncState", "create_plugin_app"), ".app"),

{spot_sdk_python-2.0.0b6 → spot_sdk_python-2.0.0b8}/spot_sdk/app.py

@@ -15,6 +15,10 @@ An ``async def`` handler, or an object whose ``__call__`` is ``async def``,
 runs on the event loop; any other callable runs in a worker thread, so it may
 block. Either way the clients send the call's ``X-Correlation-ID`` on to SPOT.
 
+A plugin that loads a model gives ``load``: run in a daemon thread once the app
+starts, it makes the plugin ``starting`` until it returns, and the analyzer
+answers ``unknown`` meanwhile; then ``analyze`` gets what it returned.
+
 Neither the logs nor the error answers hold the request's content: a
 handler's exception is logged by its type and place only, and an invalid
 request is answered with the fields refused, never the values sent.
@@ -29,11 +33,12 @@ from __future__ import annotations
 import asyncio
 import hmac
 import inspect
+import threading
 import traceback
-from collections.abc import Awaitable, Callable, Iterator
-from contextlib import contextmanager
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
+from contextlib import asynccontextmanager, contextmanager
 from datetime import UTC, datetime
-from typing import Any, Literal, TypeAlias, TypeVar
+from typing import Any, Generic, Literal, TypeAlias, TypeVar, overload
 
 from fastapi import APIRouter, Depends, FastAPI, HTTPException, Request, Response
 from fastapi.responses import JSONResponse
@@ -55,6 +60,7 @@ logger = get_logger(__name__)
 
 SettingsT = TypeVar("SettingsT", bound=PluginSettings)
 ModelT = TypeVar("ModelT", bound=BaseModel)
+LoadedT = TypeVar("LoadedT")
 
 AnalyzeHandler: TypeAlias = Callable[
     [AnalyzeRequest, SettingsT], AnalyzerVerdict | Awaitable[AnalyzerVerdict]
@@ -74,6 +80,12 @@ action idempotent (a ticket keyed by the job id).
 """
 SyncHandler: TypeAlias = Callable[[SettingsT], int | Awaitable[int]]
 """``sync(settings) -> int``: the number of documents written."""
+Loader: TypeAlias = Callable[[SettingsT], LoadedT]
+"""``load(settings) -> object``: a model, say, loaded once in a daemon thread."""
+LoadedAnalyzeHandler: TypeAlias = Callable[
+    [AnalyzeRequest, SettingsT, LoadedT], AnalyzerVerdict | Awaitable[AnalyzerVerdict]
+]
+"""``analyze(request, settings, loaded) -> AnalyzerVerdict``, with what ``load`` returned."""
 
 
 class SyncState(BaseModel):
@@ -117,6 +129,13 @@ class PluginHealth(BaseModel):
     )
 
 
+class HealthAnswer(PluginHealth):
+    """``GET /health``'s body: the plugin's state and the version of its
+    manifest. ``reason`` is left out when there is none."""
+
+    version: str = Field(description="The manifest's version")
+
+
 class ErrorAnswer(BaseModel):
     """An error the app answers itself: 401 without the plugin's own token, 500
     when the handler fails. It never holds the request's content."""
@@ -152,8 +171,10 @@ _SCHEMAS = "#/components/schemas/{model}"
 _HEALTH_CHECK_FAILED = PluginHealth(
     status="unhealthy", reason="the health check failed"
 )
+_LOADING = PluginHealth(status="starting", reason="loading")
 
 
+@overload
 def create_plugin_app(
     manifest: Manifest,
     settings_cls: type[SettingsT],
@@ -163,12 +184,40 @@ def create_plugin_app(
     sync: SyncHandler[SettingsT] | None = None,
     lifespan: Lifespan[FastAPI] | None = None,
     health: HealthCheck | None = None,
+    load: None = None,
+) -> FastAPI: ...
+
+
+@overload
+def create_plugin_app(
+    manifest: Manifest,
+    settings_cls: type[SettingsT],
+    *,
+    load: Loader[SettingsT, LoadedT],
+    analyze: LoadedAnalyzeHandler[SettingsT, LoadedT],
+    respond: RespondHandler[SettingsT] | None = None,
+    sync: SyncHandler[SettingsT] | None = None,
+    lifespan: Lifespan[FastAPI] | None = None,
+    health: HealthCheck | None = None,
+) -> FastAPI: ...
+
+
+def create_plugin_app(
+    manifest: Manifest,
+    settings_cls: type[SettingsT],
+    *,
+    analyze: Callable[..., AnalyzerVerdict | Awaitable[AnalyzerVerdict]] | None = None,
+    respond: RespondHandler[SettingsT] | None = None,
+    sync: SyncHandler[SettingsT] | None = None,
+    lifespan: Lifespan[FastAPI] | None = None,
+    health: HealthCheck | None = None,
+    load: Loader[SettingsT, Any] | None = None,
 ) -> FastAPI:
     """Build the plugin's app; the settings are read once, here.
 
-    Each kind the manifest declares needs its handler (analyzer: ``analyze``,
-    responder: ``respond``, context provider: ``sync``; a mail retriever has
-    none), and each handler its kind, or ``ValueError`` is raised.
+    The manifest's kind needs its handler (analyzer: ``analyze``, responder:
+    ``respond``, context provider: ``sync``; a mail retriever has none), and
+    each handler its kind, or ``ValueError`` is raised.
 
     ``lifespan`` is passed to FastAPI as is: an async context manager run
     around the app's life, to load a model at startup, say.
@@ -181,6 +230,16 @@ def create_plugin_app(
     ``PluginHealth``, makes the plugin ``unhealthy`` for a fixed reason, and
     is logged as the handlers are: never with the exception's message.
 
+    ``load(settings)``, a plain function, loads what the analyzer needs (a
+    model) once the app starts, after ``lifespan``'s startup, in a daemon
+    thread: the app answers meanwhile. Until it returns, the plugin is
+    ``starting`` (``loading``) and ``/internal/analyze`` answers ``unknown``;
+    when it raises, ``unhealthy`` for good, with the exception's type
+    (``the load failed (OSError)``), logged as the handlers' failures are.
+    Then ``analyze(request, settings, loaded)`` gets what it returned, and
+    ``health``, if given, reports the plugin's state. ``load`` needs
+    ``analyze``, and may not be async, or ``ValueError`` is raised.
+
     ``POST /internal/sync`` answers 202 at once and runs ``sync`` in the
     background. While a sync runs, another call starts nothing and answers
     202 with the running sync's state.
@@ -189,7 +248,7 @@ def create_plugin_app(
     components of that document alone, so read it from this app: another
     FastAPI app that includes its routes leaves their ``$ref`` dangling.
     """
-    _check_kinds(manifest, {"analyze": analyze, "respond": respond, "sync": sync})
+    _check_kind(manifest, {"analyze": analyze, "respond": respond, "sync": sync})
     settings = settings_cls()
     if not settings.spot_plugin_token.get_secret_value():
         logger.warning(
@@ -197,6 +256,17 @@ def create_plugin_app(
             "mounts it as /run/secrets/spot_plugin_token; outside a container, set "
             "SPOT_PLUGIN_TOKEN."
         )
+    if load is not None:
+        if analyze is None:
+            raise ValueError(
+                "load is given, but no analyze handler to get what it loads"
+            )
+        if _is_async(load):
+            raise ValueError("load runs in a thread: a plain function, not async")
+        loading = _BackgroundLoad(load, settings)
+        lifespan = loading.lifespan(lifespan)
+        health = loading.health(health)
+        analyze = loading.analyze(analyze)
     app = _PluginApp(
         title=manifest.id,
         version=manifest.version,
@@ -204,13 +274,10 @@ def create_plugin_app(
         lifespan=lifespan,
     )
 
-    @app.get("/health")
-    async def health_route() -> dict[str, str]:
+    @app.get("/health", response_model_exclude_none=True)
+    async def health_route() -> HealthAnswer:
         state = await _health(health)
-        answer = {"status": state.status, "version": manifest.version}
-        if state.reason is not None:
-            answer["reason"] = state.reason
-        return answer
+        return HealthAnswer(**state.model_dump(), version=manifest.version)
 
     @app.get("/manifest")
     async def get_manifest() -> Manifest:
@@ -331,10 +398,10 @@ _HANDLER_KINDS = {
 """The kind each handler serves; a mail retriever has no handler."""
 
 
-def _check_kinds(manifest: Manifest, handlers: dict[str, object]) -> None:
-    """Each kind the manifest declares has its handler, and each handler its kind."""
+def _check_kind(manifest: Manifest, handlers: dict[str, object]) -> None:
+    """The manifest's kind has its handler, and each handler its kind."""
     for name, kind in _HANDLER_KINDS.items():
-        declared = kind in manifest.kinds
+        declared = kind is manifest.kind
         given = handlers[name] is not None
         if declared and not given:
             raise ValueError(
@@ -346,6 +413,75 @@ def _check_kinds(manifest: Manifest, handlers: dict[str, object]) -> None:
             )
 
 
+class _BackgroundLoad(Generic[LoadedT]):
+    """Runs ``load`` in a daemon thread once the app starts, and holds what it
+    returned; the plugin's state is ``starting`` until then."""
+
+    _loaded: LoadedT
+
+    def __init__(self, load: Loader[Any, LoadedT], settings: PluginSettings) -> None:
+        self._load = load
+        self._settings = settings
+        self.state = _LOADING
+
+    def lifespan(self, lifespan: Lifespan[FastAPI] | None) -> Lifespan[FastAPI]:
+        """``lifespan``, with the load started after its startup: once the
+        plugin has set its logging up, say."""
+
+        @asynccontextmanager
+        async def loading(app: FastAPI) -> AsyncIterator[Any]:
+            if lifespan is None:
+                self._start()
+                yield None
+                return
+            async with lifespan(app) as state:
+                self._start()
+                yield state
+
+        return loading
+
+    def health(self, check: HealthCheck | None) -> HealthCheck:
+        """The plugin's state: the load's until it succeeded, then ``check``'s."""
+
+        async def health() -> PluginHealth:
+            if self.state.status != "healthy":
+                return self.state
+            return await _health(check)
+
+        return health
+
+    def analyze(
+        self, handler: LoadedAnalyzeHandler[Any, LoadedT]
+    ) -> AnalyzeHandler[Any]:
+        """``handler``, given what the load returned; ``unknown`` until then."""
+
+        async def analyze(
+            request: AnalyzeRequest, settings: PluginSettings
+        ) -> AnalyzerVerdict:
+            state = self.state
+            if state.status != "healthy":
+                return AnalyzerVerdict.unknown(state.reason or state.status)
+            verdict: AnalyzerVerdict = await _run(
+                handler, request, settings, self._loaded
+            )
+            return verdict
+
+        return analyze
+
+    def _start(self) -> None:
+        threading.Thread(target=self._run, name="load", daemon=True).start()
+
+    def _run(self) -> None:
+        try:
+            self._loaded = self._load(self._settings)
+        except Exception as error:
+            _log_failure("load", error)
+            reason = f"the load failed ({type(error).__name__})"
+            self.state = PluginHealth(status="unhealthy", reason=reason)
+        else:
+            self.state = _HEALTHY
+
+
 class _SyncRunner:
     """Runs the sync handler in the background, one run at a time."""
 
@@ -443,18 +579,20 @@ async def _parse(request: Request, model: type[ModelT]) -> ModelT:
 
 
 async def _run(handler: Callable[..., Any], *args: Any) -> Any:
-    """Await an async handler; run any other in a worker thread, in this context.
-
-    A handler is async when it is an ``async def`` function, or an object whose
-    ``__call__`` is one, as FastAPI tells them apart.
-    """
-    if inspect.iscoroutinefunction(handler) or inspect.iscoroutinefunction(
-        getattr(handler, "__call__", None)
-    ):
+    """Await an async handler; run any other in a worker thread, in this context."""
+    if _is_async(handler):
         return await handler(*args)
     return await run_in_threadpool(handler, *args)
 
 
+def _is_async(handler: Callable[..., Any]) -> bool:
+    """Whether ``handler`` is an ``async def`` function, or an object whose
+    ``__call__`` is one, as FastAPI tells them apart."""
+    return inspect.iscoroutinefunction(handler) or inspect.iscoroutinefunction(
+        getattr(handler, "__call__", None)
+    )
+
+
 @contextmanager
 def _correlated(request: Request) -> Iterator[None]:
     """Make the call's ``X-Correlation-ID`` the one the clients send."""

spot_sdk_python-2.0.0b8/spot_sdk/artifacts.py

@@ -0,0 +1,205 @@
+"""A model's files, from a local path or an archive downloaded once.
+
+``fetch(url)`` turns what a setting names into a local path: a local path as
+it is, or the directory an http(s) archive (``.tar.gz``, ``.tgz``, ``.tar`` or
+``.zip``) is extracted into. An archive is downloaded once into a cache, one
+directory per URL. It is downloaded and extracted in a temporary directory
+beside the cache, then renamed into place: a stop half-way leaves nothing that
+the next start would take for the model.
+
+A URL's userinfo, query and fragment, where its credentials or a presigned
+URL's signature are, never reach a log line or an error.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import shutil
+import stat
+import tarfile
+import tempfile
+import urllib.error
+import urllib.request
+import zipfile
+from pathlib import Path
+from typing import IO, Literal
+from urllib.parse import urlsplit
+
+from .logging import get_logger
+from .urls import redact
+
+logger = get_logger(__name__)
+
+CACHE = Path.home() / ".cache" / "spot-sdk" / "artifacts"
+"""Where ``fetch`` keeps archives by default, one directory per URL."""
+
+# How an archive is opened, by the end of its URL's path: a tarfile mode, or zip
+_TarMode = Literal["r:gz", "r:"]
+_ArchiveFormat = _TarMode | Literal["zip"]
+_FORMATS: dict[str, _ArchiveFormat] = {
+    ".tar.gz": "r:gz",
+    ".tgz": "r:gz",
+    ".tar": "r:",
+    ".zip": "zip",
+}
+# A URL's scheme (RFC 3986): a local path has none
+_SCHEME = re.compile(r"[A-Za-z][A-Za-z0-9+.-]*:")
+# How long the server may stay silent during the download, in seconds
+_TIMEOUT_S = 60
+# The file types a zip member may have: none given, a file, a directory
+_ZIP_KINDS = (0, stat.S_IFREG, stat.S_IFDIR)
+
+
+class FetchError(Exception):
+    """An archive could not be fetched. The message names the URL without its
+    userinfo, query and fragment, and why: of a failed download, the error's
+    type only, as its text can quote the whole URL."""
+
+
+def fetch(url: str, *, cache: Path = CACHE) -> Path:
+    """A local path for ``url``: itself when it is no URL, else the
+    directory its archive is extracted into, under ``cache``.
+
+    A URL is anything with a scheme, or that starts with ``//``. It must be
+    one ``spot_sdk.urls.redact`` can show safely, be http or https, name a
+    host, hold no credentials (a presigned URL gives access), and its path
+    end with ``.tar.gz``, ``.tgz``, ``.tar`` or ``.zip``. The archive is
+    downloaded once: the next call with the same URL returns the same
+    directory at once, and so does a call that finds another process put it
+    in place meanwhile. Only files and directories are extracted: a member
+    that would land outside the directory, a link or a special file is
+    refused, and nothing is kept. ``FetchError`` says why, and is logged at
+    ERROR, as a plugin logs a failed load by its type only.
+    """
+    if not (_SCHEME.match(url) or url.startswith("//")):
+        return Path(url)
+    try:
+        shown = redact(url)
+    except ValueError as error:
+        # Its text quotes nothing of the URL
+        raise _failure(f"fetch refuses the URL: {error}") from None
+    parts = urlsplit(url)
+    if parts.scheme not in ("http", "https") or not parts.hostname:
+        raise _failure(f"{shown}: not an http or https URL with a host")
+    if "@" in parts.netloc:
+        raise _failure(
+            f"{shown}: a URL's credentials are never sent: give access with a "
+            "presigned URL"
+        )
+    archive_format = _archive_format(parts.path)
+    if archive_format is None:
+        raise _failure(f"{shown}: not a .tar.gz, .tgz, .tar or .zip archive")
+    entry = cache / hashlib.sha256(url.encode()).hexdigest()
+    if entry.is_dir():
+        return entry
+    cache.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix=".", dir=cache) as temporary:
+        archive = Path(temporary) / "archive"
+        extracted = Path(temporary) / "extracted"
+        logger.info("Downloading %s", shown)
+        try:
+            _download(url, archive)
+        except Exception as error:
+            # The type only: the error's text can quote the URL, credentials
+            # included (http.client's InvalidURL does)
+            raise _failure(
+                f"{shown} could not be downloaded ({type(error).__name__})"
+            ) from None
+        try:
+            _extract(archive, extracted, archive_format)
+        except Exception as error:
+            # A local file's error: its text holds nothing of the URL
+            raise _failure(f"{shown} could not be extracted: {error}") from error
+        try:
+            extracted.rename(entry)
+        except OSError as error:
+            # Another process put the same URL's archive in place meanwhile
+            if not entry.is_dir():
+                raise _failure(f"{shown} could not be cached: {error}") from error
+    logger.info("Extracted %s into %s", shown, entry)
+    return entry
+
+
+def _failure(message: str) -> FetchError:
+    """``FetchError(message)``, logged."""
+    logger.error("%s", message)
+    return FetchError(message)
+
+
+def _archive_format(path: str) -> _ArchiveFormat | None:
+    """The archive's format, by the end of the URL's path; ``None`` for
+    another file."""
+    name = path.lower()
+    for suffix, archive_format in _FORMATS.items():
+        if name.endswith(suffix):
+            return archive_format
+    return None
+
+
+def _download(url: str, archive: Path) -> None:
+    try:
+        answer = urllib.request.urlopen(url, timeout=_TIMEOUT_S)
+    except urllib.error.HTTPError as error:
+        error.close()  # it holds the server's answer, and its connection
+        raise
+    with answer, archive.open("wb") as file:
+        shutil.copyfileobj(answer, file)
+
+
+def _extract(archive: Path, target: Path, archive_format: _ArchiveFormat) -> None:
+    """Extract the archive's files and directories into ``target``."""
+    target.mkdir()
+    if archive_format == "zip":
+        _extract_zip(archive, target)
+    else:
+        _extract_tar(archive, target, archive_format)
+
+
+def _extract_zip(archive: Path, target: Path) -> None:
+    with zipfile.ZipFile(archive) as zipped:
+        for info in zipped.infolist():
+            path = _destination(target, info.filename)
+            # The file type, as the member's external attributes give it: none
+            # from a zip made elsewhere than Unix, which holds files only
+            if stat.S_IFMT(info.external_attr >> 16) not in _ZIP_KINDS:
+                raise _not_a_file(info.filename)
+            if info.is_dir():
+                path.mkdir(parents=True, exist_ok=True)
+                continue
+            with zipped.open(info) as data:
+                _write(path, data)
+
+
+def _extract_tar(archive: Path, target: Path, mode: _TarMode) -> None:
+    with tarfile.open(archive, mode) as tarred:
+        for member in tarred:
+            path = _destination(target, member.name)
+            if member.isdir():
+                path.mkdir(parents=True, exist_ok=True)
+                continue
+            data = tarred.extractfile(member) if member.isfile() else None
+            if data is None:
+                raise _not_a_file(member.name)
+            with data:
+                _write(path, data)
+
+
+def _not_a_file(name: str) -> ValueError:
+    return ValueError(f"the member {name!r} is neither a file nor a directory")
+
+
+def _destination(target: Path, name: str) -> Path:
+    """Where the member ``name`` lands in ``target``; refused outside it."""
+    path = (target / name).resolve()
+    if not path.is_relative_to(target.resolve()):
+        raise ValueError(
+            f"the member {name!r} would land outside the archive's directory"
+        )
+    return path
+
+
+def _write(path: Path, data: IO[bytes]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("wb") as file:
+        shutil.copyfileobj(data, file)