spot-sdk-python 2.0.0b11__tar.gz → 2.0.0b13__tar.gz

{spot_sdk_python-2.0.0b11 → spot_sdk_python-2.0.0b13}/PKG-INFO

@@ -1,25 +1,24 @@
 Metadata-Version: 2.4
 Name: spot-sdk-python
-Version: 2.0.0b11
+Version: 2.0.0b13
 Summary: SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers
-License: Apache-2.0
 Author: SPOT Project
-Author-email: spot@sonn.lu
-Requires-Python: >=3.11,<3.16
-Classifier: License :: OSI Approved :: Apache Software License
+Author-email: SPOT Project <spot@sonn.lu>
+License-Expression: Apache-2.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 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.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)
+Requires-Dist: pydantic>=2.10,<3
+Requires-Dist: pydantic-settings>=2.0.0,<3
+Requires-Dist: httpx2>=2.13.1,<3
+Requires-Dist: selectolax>=1.0,<1.1
+Requires-Dist: idna>=3.11,<4
+Requires-Dist: fastapi>=0.133.0,<1
+Requires-Dist: starlette>=1.7.0,<2
+Requires-Python: >=3.11, <3.16
 Project-URL: Homepage, https://sonn.lu
 Description-Content-Type: text/markdown
 
@@ -51,7 +50,7 @@ plugins share:
 ## Install
 
 ```bash
-pip install spot-sdk-python==2.0.0b11
+pip install spot-sdk-python==2.0.0b13
 ```
 
 Python 3.11 to 3.15. Version 2 implements plugin contract 2, for
@@ -116,4 +115,3 @@ token=...)`.
 ## License
 
 Apache License 2.0.
-

{spot_sdk_python-2.0.0b11 → spot_sdk_python-2.0.0b13}/README.md

@@ -26,7 +26,7 @@ plugins share:
 ## Install
 
 ```bash
-pip install spot-sdk-python==2.0.0b11
+pip install spot-sdk-python==2.0.0b13
 ```
 
 Python 3.11 to 3.15. Version 2 implements plugin contract 2, for

spot_sdk_python-2.0.0b13/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["uv_build>=0.12.22,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "spot-sdk-python"
+version = "2.0.0b13"
+description = "SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11,<3.16"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+]
+dependencies = [
+    "pydantic>=2.10,<3",
+    "pydantic-settings>=2.0.0,<3",
+    "httpx2>=2.13.1,<3",
+    "selectolax>=1.0,<1.1",
+    "idna>=3.11,<4",
+    "fastapi>=0.133.0,<1",
+    "starlette>=1.7.0,<2",
+]
+
+[[project.authors]]
+name = "SPOT Project"
+email = "spot@sonn.lu"
+
+[project.urls]
+Homepage = "https://sonn.lu"
+
+[tool.uv.build-backend]
+module-name = "spot_sdk"
+module-root = ""
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "N",
+    "W",
+]
+ignore = ["E501"]

spot_sdk_python-2.0.0b13/pyproject.toml.orig

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["uv_build>=0.12.22,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "spot-sdk-python"
+version = "2.0.0b13"
+description = "SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [{ name = "SPOT Project", email = "spot@sonn.lu" }]
+requires-python = ">=3.11,<3.16"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+]
+dependencies = [
+    "pydantic>=2.10,<3",
+    "pydantic-settings>=2.0.0,<3",
+    "httpx2>=2.13.1,<3",
+    "selectolax>=1.0,<1.1",
+    "idna>=3.11,<4",
+    "fastapi>=0.133.0,<1",
+    "starlette>=1.7.0,<2",
+]
+
+[project.urls]
+Homepage = "https://sonn.lu"
+
+[tool.uv.build-backend]
+module-name = "spot_sdk"
+module-root = ""
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+ignore = ["E501"]  # Line too long

{spot_sdk_python-2.0.0b11 → spot_sdk_python-2.0.0b13}/spot_sdk/__init__.py

@@ -25,6 +25,7 @@ from .orchestrator import (
     RespondRequest,
     StageOutcome,
 )
+from .proxy import PROXY_SECRET, apply_proxy_credentials
 from .retriever import ActionReport, IngestionRequest, IngestionResult, IngestionStatus
 from .settings import PluginSettings
 from .verdict import AnalyzerVerdict, Score, Signal, VerdictClass
@@ -127,9 +128,11 @@ __all__ = [
     "SettingType",
     # Plugin runtime
     "CorrelationMiddleware",
+    "PROXY_SECRET",
     "PluginHealth",
     "PluginSettings",
     "SyncState",
+    "apply_proxy_credentials",
     "create_plugin_app",
     # Clients
     "LLMClient",

{spot_sdk_python-2.0.0b11 → spot_sdk_python-2.0.0b13}/spot_sdk/app.py

@@ -58,6 +58,7 @@ from .correlation import HEADER, adopt
 from .logging import get_logger
 from .manifest import Manifest, PluginKind
 from .orchestrator import AnalyzeRequest, RespondRequest
+from .proxy import apply_proxy_credentials
 from .settings import PluginSettings
 from .verdict import AnalyzerVerdict
 
@@ -220,6 +221,10 @@ def create_plugin_app(
 ) -> FastAPI:
     """Build the plugin's app; the settings are read once, here.
 
+    First, the egress proxy's credentials, which core mounts as a secret
+    file, go back into the proxy variables (``apply_proxy_credentials``), so
+    the plugin's HTTP clients reach an authenticated proxy.
+
     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.
@@ -253,6 +258,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.
     """
+    apply_proxy_credentials()
     _check_kind(manifest, {"analyze": analyze, "respond": respond, "sync": sync})
     settings = settings_cls()
     if not settings.spot_plugin_token.get_secret_value():

{spot_sdk_python-2.0.0b11 → spot_sdk_python-2.0.0b13}/spot_sdk/knowledge.py

@@ -64,8 +64,9 @@ class KnowledgeDocument(BaseModel):
     id: str = Field(
         ...,
         description=(
-            "Stable unique id (e.g. 'employee:alice@co.com', "
-            "'wiki:page-123#chunk-4'). Upsert is idempotent on this key."
+            "Stable id, unique within its source, e.g. a key of the source's own or a "
+            "keyed hash. It appears in URL paths and logs, so it never holds personal "
+            "data such as an email address. Upsert is idempotent on (source, id)."
         ),
     )
     content: str = Field(
@@ -88,7 +89,10 @@ class KnowledgeDocument(BaseModel):
     )
     source: str = Field(
         default="",
-        description="Provider that produced the document (audit + future ownership).",
+        description=(
+            "The provider that wrote it: its plugin id, set by the store for a "
+            "plugin's write."
+        ),
     )
     updated_at: datetime | None = None
     expires_at: datetime | None = Field(
@@ -103,6 +107,16 @@ class KnowledgeDocument(BaseModel):
     )
 
 
+def _documents_path(source: str) -> str:
+    """The store's path of a source's documents, the source quoted."""
+    return f"/sources/{quote(source, safe='')}/documents"
+
+
+def _document_path(source: str, doc_id: str) -> str:
+    """The store's path of one of a source's documents, both parts quoted."""
+    return f"{_documents_path(source)}/{quote(doc_id, safe='')}"
+
+
 class _QueryAnswer(BaseModel):
     """The store's answer to ``POST /query``."""
 
@@ -256,8 +270,10 @@ class KnowledgeClient:
         await self._call("POST", "/bulk-upsert", json=payload)
 
     async def delete(self, doc_id: str) -> None:
-        """Delete a document by id."""
-        await self._call("DELETE", f"/documents/{quote(doc_id, safe='')}")
+        """Delete one of the plugin's own documents, by its id within the plugin's source."""
+        if not self.source:
+            raise ValueError("delete needs the plugin's id: set SPOT_PLUGIN_ID")
+        await self._call("DELETE", _document_path(self.source, doc_id))
 
     async def replace_source(self, docs: list[KnowledgeDocument]) -> None:
         """Make ``docs`` the plugin's whole set of documents.
@@ -269,8 +285,7 @@ class KnowledgeClient:
         if not self.source:
             raise ValueError("replace_source needs the plugin's id: set SPOT_PLUGIN_ID")
         payload = {"documents": [d.model_dump(mode="json") for d in docs]}
-        path = f"/sources/{quote(self.source, safe='')}/documents"
-        await self._call("PUT", path, json=payload)
+        await self._call("PUT", _documents_path(self.source), json=payload)
 
     # ------------------------------------------------------------------ #
     # Read side: analyzers

{spot_sdk_python-2.0.0b11 → spot_sdk_python-2.0.0b13}/spot_sdk/mime.py

@@ -38,7 +38,9 @@ import base64
 import binascii
 import codecs
 import email
+import functools
 import hashlib
+import ipaddress
 import json
 import math
 import re
@@ -54,8 +56,8 @@ from email.utils import decode_params, getaddresses, parsedate_to_datetime, unqu
 from html import unescape as unescape_html
 from itertools import chain
 from typing import Any, Literal, NamedTuple, TypeAlias, TypeVar, cast
+from urllib.parse import SplitResult
 from urllib.parse import unquote as unquote_url
-from urllib.parse import urlsplit
 from uuid import UUID
 
 import idna
@@ -519,6 +521,38 @@ _MAX_LABEL = 4 * 63
 _MAX_A_LABEL = 63
 # The most characters idna maps a call (from 3.17).
 _IDNA_INPUT = 1024
+# NFC reorders a run of combining marks (of a canonical combining class
+# other than 0) in time quadratic in it. A label with more marks in a
+# row than an A-label holds characters maps to no DNS label: NFC composes at
+# most 3 of them into the character before (U+1F8F), and the 61 or more left
+# are code points an A-label spells with a character each at least, after its
+# "xn--": 65 characters.
+_MAX_MARKS = _MAX_A_LABEL
+_MARK_RUN = re.compile(rb"(?<![^\x00])[^\x00]{%d}" % (_MAX_MARKS + 1))
+# The characters UTS 46 maps to other marks than their own class counts (idna
+# 3.20, Unicode 14.0 and 15.1): to two, to marks though they are of class 0,
+# or to an iota, no mark.
+_MARK_READINGS = str.maketrans(
+    {
+        "\u0344": "\u0308\u0301",
+        "\u0345": "\u03b9",
+        "\u0f73": "\u0f71\u0f72",
+        "\u0f75": "\u0f71\u0f74",
+        "\u0f81": "\u0f71\u0f80",
+        "\uff9e": "\u3099",
+        "\uff9f": "\u309a",
+    }
+)
+# Python's urlsplit reads a URL without its leading C0 controls and spaces,
+# and without its tabs and line breaks. Its netloc follows "//", after the
+# scheme if any, up to the first of "/?#".
+_URL_LEADING = "".join(map(chr, range(0x21)))
+_URL_REMOVED = "\t\r\n"
+_NETLOC = re.compile(r"(?:[A-Za-z][A-Za-z0-9+.-]*:)?//([^/?#]*)")
+# What urlsplit refuses NFKC to make of a netloc's characters.
+_URL_DELIMITERS = frozenset("/?#@:")
+# An IPvFuture address, in brackets (RFC 3986).
+_IPV_FUTURE = re.compile(r"v[a-fA-F0-9]+\..+")
 
 
 # A parameter as email.utils decodes it: a value, or an RFC 2231
@@ -1532,11 +1566,26 @@ def _domain(host: str) -> str:
     A host that can be no DNS name (``_can_be_dns_name``) reaches no
     resolver: it is only lower-cased, neither mapped nor decoded. That bounds
     the work a host costs: CPython reorders combining marks for NFC in time
-    quadratic in their run, and a run ends at a dot.
+    quadratic in their run, and a longer run than ``_MAX_MARKS`` makes no DNS
+    name.
 
     It reads the host, and does not decide whether a browser would accept it:
     a label against the Bidi rule, or with a joiner out of context, is read
-    all the same."""
+    all the same.
+
+    A host of at most ``_MAX_DOMAIN`` characters is read once while it stays
+    among the last 256 the process read: a hostile message repeats one host
+    up to MAX_URLS times (sdk#27). UTS 46 maps a character to at most 18, so
+    the cache holds 19 MiB at most. A longer host is read each time: it is a
+    DNS name only once its invisible characters or its trailing dots are
+    removed."""
+    if len(host) > _MAX_DOMAIN:
+        return _read_domain(host)
+    return _cached_domain(host)
+
+
+def _read_domain(host: str) -> str:
+    """``host`` read as ``_domain`` reads it, each time."""
     host = host.rstrip(_DOT_CHARACTERS)
     if not _can_be_dns_name(host):
         return host.lower()
@@ -1549,19 +1598,37 @@ def _domain(host: str) -> str:
     return ".".join(map(_decoded, labels))
 
 
+_cached_domain = functools.lru_cache(maxsize=256)(_read_domain)
+
+
 def _can_be_dns_name(host: str) -> bool:
     """Whether ``host`` may map to a DNS name, counted on what a resolver could
     see: without its invisible characters (``visible``, which holds all those
     UTS 46 removes) and its trailing dots, it keeps at most ``_MAX_DOMAIN``
-    characters, and each label at most ``_MAX_LABEL``. UTS 46 maps any other
+    characters, each label at most ``_MAX_LABEL``, and at most ``_MAX_MARKS``
+    combining marks in a row as UTS 46 maps them. UTS 46 maps any other
     character to one or more, so the count never exceeds the mapped host's
-    before NFC. It only counts: the host is read as UTS 46 maps it."""
+    before NFC. The joiners, the only invisible characters UTS 46 keeps, may
+    split a run counted whole: no ASCII either, they leave the label as long
+    in its A-label. It only counts: the host is read as UTS 46 maps it."""
     counted = visible(host).rstrip(_DOT_CHARACTERS)
-    return len(counted) <= _MAX_DOMAIN and all(
-        len(label) <= _MAX_LABEL for label in _DOTS.split(counted)
+    return (
+        len(counted) <= _MAX_DOMAIN
+        and all(len(label) <= _MAX_LABEL for label in _DOTS.split(counted))
+        and not _too_many_marks(counted)
     )
 
 
+def _too_many_marks(text: str) -> bool:
+    """Whether ``text`` holds more than ``_MAX_MARKS`` combining marks in a row,
+    as UTS 46 maps them (``_MARK_READINGS``). In linear time: the classes, all
+    under 256, are matched as bytes, from the start of each run."""
+    if text.isascii():
+        return False
+    classes = bytes(map(unicodedata.combining, text.translate(_MARK_READINGS)))
+    return _MARK_RUN.search(classes) is not None
+
+
 def _mapped(label: str) -> str:
     """A label mapped as UTS 46 maps it; as written, lower-cased, when it does
     not map."""
@@ -1878,19 +1945,76 @@ def url_host(text: str) -> str:
     dropped. A label UTS 46 does not map stays as written, lower-cased, a
     host browsers refuse (a space, a slash, a label against the Bidi rule) is
     kept as read, and a host that can be no DNS name is only lower-cased:
-    never an exception. That is a host that keeps over 1 012 characters, or a
-    label over 252, once its invisible characters are removed: a DNS name
-    holds 253, a label 63, and NFC composes at most 4 code points into one.
-    An A-label over 63 characters stays encoded.
+    never an exception. That is a host that keeps over 1 012 characters, a
+    label over 252, or over 63 combining marks in a row, once its invisible
+    characters are removed: a DNS name holds 253, a label 63, NFC composes at
+    most 4 code points into one, and an A-label spells each code point that is
+    not ASCII with a character at least. An A-label over 63 characters stays
+    encoded.
+
+    The host is found as CPython 3.11's urlsplit reads it (3.13 also accepts
+    an IPvFuture ``V``), its ``.hostname``, and none where urlsplit refuses the
+    URL, but in linear time: urlsplit puts the netloc in NFKC to refuse a
+    character NFKC turns into a delimiter (U+2100 is ``a/c``), in time
+    quadratic in a run of combining marks.
     """
     if text[:4].lower() == "www.":
         text = "http://" + text
+    # Browsers read a backslash as a slash in web URLs.
+    host = _hostname(text.replace("\\", "/"))
+    return _domain(_clean(unquote_url(host))) if host else ""
+
+
+def _hostname(url: str) -> str | None:
+    """``urlsplit(url).hostname``, as CPython 3.11's urlsplit reads it (3.13
+    also accepts an IPvFuture ``V``); None where urlsplit refuses ``url``: a
+    bracket without its pair, brackets misplaced or around no IPv6 or IPvFuture
+    address (``_accepted_brackets``), or a character NFKC turns into a
+    delimiter. That last is checked a character at a time: NFKC composes no
+    delimiter, and the netloc's own ``@`` and ``:`` do not count."""
+    netloc = _netloc(url)
+    if ("[" in netloc) != ("]" in netloc):
+        return None
+    if "[" in netloc and not _accepted_brackets(netloc.rpartition("@")[2]):
+        return None
+    if any(
+        not _URL_DELIMITERS.isdisjoint(unicodedata.normalize("NFKD", character))
+        for character in set(netloc)
+        if not character.isascii()
+    ):
+        return None
+    return SplitResult("", netloc, "", "", "").hostname
+
+
+def _netloc(url: str) -> str:
+    """The netloc urlsplit reads in ``url``, unchecked; "" when it has none."""
+    url = url.lstrip(_URL_LEADING)
+    for removed in _URL_REMOVED:
+        url = url.replace(removed, "")
+    found = _NETLOC.match(url)
+    return found.group(1) if found else ""
+
+
+def _accepted_brackets(hostinfo: str) -> bool:
+    """Whether urlsplit accepts the brackets of a netloc whose ``hostinfo``
+    follows its last ``@``: nothing before them, only a port after them, and an
+    IPv6 or IPvFuture address in them. With the brackets in the userinfo, the
+    host itself must be such an address."""
+    before, bracket, bracketed = hostinfo.partition("[")
+    if not bracket:
+        host = before.partition(":")[0]
+    elif before:
+        return False
+    else:
+        host, _, port = bracketed.partition("]")
+        if port and not port.startswith(":"):
+            return False
+    if host.startswith("v"):
+        return _IPV_FUTURE.fullmatch(host) is not None
     try:
-        # Browsers read a backslash as a slash in web URLs.
-        host = urlsplit(text.replace("\\", "/")).hostname
+        return ipaddress.ip_address(host).version == 6
     except ValueError:
-        return ""
-    return _domain(_clean(unquote_url(host))) if host else ""
+        return False
 
 
 def _url(

spot_sdk_python-2.0.0b13/spot_sdk/proxy.py

@@ -0,0 +1,94 @@
+"""The egress proxy's credentials, from a secret file.
+
+Core never puts the proxy's user and password in a plugin's environment: it
+forwards each proxy variable without them, and mounts them as the file
+``/run/secrets/spot_proxy_credentials``, ``user:password`` as a URL carries
+them (percent-encoded). :func:`apply_proxy_credentials`, which
+:func:`spot_sdk.create_plugin_app` calls first, puts them back into the
+process's proxy variables, so its HTTP clients reach the proxy
+authenticated. They are never logged.
+"""
+
+from __future__ import annotations
+
+import os
+import unicodedata
+from collections.abc import MutableMapping
+from pathlib import Path
+from urllib.parse import urlsplit, urlunsplit
+
+from .settings import SECRETS_DIR
+
+PROXY_SECRET = "spot_proxy_credentials"
+"""The file, in the secrets directory, that holds the proxy's ``user:password``."""
+
+PROXY_VARIABLES = (
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "ALL_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "all_proxy",
+)
+"""The variables of the proxy URLs that HTTP clients read."""
+
+# What a URL's user and password cannot hold as written: they end it.
+_DELIMITERS = frozenset("/?#[]")
+
+
+def apply_proxy_credentials(
+    secrets_dir: Path | None = None, environ: MutableMapping[str, str] | None = None
+) -> bool:
+    """Put the proxy's credentials into each proxy variable whose URL names no user.
+
+    The credentials are the first line of ``secrets_dir / PROXY_SECRET``
+    (by default in ``/run/secrets``), and they go into the proxy variables
+    of ``environ`` (by default the process's). Core writes the file only
+    when every proxy variable it forwards carried these same credentials,
+    so each gets them. A URL that already names a user keeps it. A value
+    without a scheme (``proxy.example:3128``) is left as it is: a client
+    that reads it reaches the proxy without them. Every variable is left as
+    it is when the file is empty.
+
+    Returns:
+        Whether the file exists.
+
+    Raises:
+        ValueError: the file is not UTF-8, or its first line holds ``/``,
+            ``?``, ``#``, ``[``, ``]`` or a control character, which a URL
+            carries percent-encoded; the error names the file, never what it
+            holds.
+    """
+    path = (SECRETS_DIR if secrets_dir is None else secrets_dir) / PROXY_SECRET
+    if not path.is_file():
+        return False
+    credentials = _read_credentials(path)
+    if credentials is None:
+        # Raised here, where no local holds the file's content.
+        raise ValueError(f"{path} does not hold user:password as a URL carries them")
+    if not credentials:
+        return True
+    variables = os.environ if environ is None else environ
+    for name in PROXY_VARIABLES:
+        parts = urlsplit(variables.get(name, ""))
+        if parts.netloc and "@" not in parts.netloc:
+            netloc = f"{credentials}@{parts.netloc}"
+            variables[name] = urlunsplit(parts._replace(netloc=netloc))
+    return True
+
+
+def _read_credentials(path: Path) -> str | None:
+    """The file's first line, stripped; None when it is not UTF-8, or holds
+    ``/``, ``?``, ``#``, ``[``, ``]`` or a control character, which a URL
+    carries percent-encoded."""
+    try:
+        lines = path.read_bytes().decode("utf-8").splitlines()
+    except UnicodeDecodeError:
+        return None
+    credentials = lines[0].strip() if lines else ""
+    if any(
+        char in _DELIMITERS or unicodedata.category(char) == "Cc"
+        for char in credentials
+    ):
+        return None
+    return credentials

{spot_sdk_python-2.0.0b11 → spot_sdk_python-2.0.0b13}/spot_sdk/testing/fake_knowledge_client.py

@@ -1,7 +1,8 @@
 """In-memory fake of :class:`spot_sdk.knowledge.KnowledgeClient` for tests.
 
-No HTTP, no embedding, no vector math — just a dict keyed by ``id``
-that supports the same methods. ``fetch()`` does naive substring
+No HTTP, no embedding, no vector math — just a dict keyed by
+``(source, id)``, as a document's id is unique within its source, that
+supports the same methods. ``fetch()`` does naive substring
 matching over content + tag-expression filtering, which is enough for
 plugin unit tests to assert that an analyzer reads documents out of the
 store.
@@ -23,7 +24,8 @@ from __future__ import annotations
 import re
 from typing import TYPE_CHECKING
 
-from ..knowledge import KnowledgeDocument
+from ..clients import SpotAPIError
+from ..knowledge import KnowledgeDocument, _document_path
 from ..workflow import RetrievalLimits
 
 if TYPE_CHECKING:
@@ -36,7 +38,7 @@ class FakeKnowledgeClient:
     def __init__(
         self, retrieval_limits: RetrievalLimits | None = None, *, source: str = ""
     ) -> None:
-        self._docs: dict[str, KnowledgeDocument] = {}
+        self._docs: dict[tuple[str, str], KnowledgeDocument] = {}
         self.retrieval_limits = retrieval_limits or RetrievalLimits()
         self.source = source
 
@@ -49,13 +51,34 @@ class FakeKnowledgeClient:
     # --- write side ---------------------------------------------------- #
 
     async def upsert(self, doc: KnowledgeDocument) -> None:
-        self.add(doc)
+        await self.bulk_upsert([doc])
 
     async def bulk_upsert(self, docs: list[KnowledgeDocument]) -> None:
+        """Store the documents, as the store does for a plugin's write.
+
+        With a source, a batch holding another source's document is refused
+        whole, before anything is stored, and a document without one takes
+        the client's. Without a source (a core-like caller), the documents
+        are stored as given.
+        """
+        if self.source:
+            self._refuse_other_sources(docs)
+            docs = [
+                d if d.source else d.model_copy(update={"source": self.source})
+                for d in docs
+            ]
         self.add(*docs)
 
     async def delete(self, doc_id: str) -> None:
-        self._docs.pop(doc_id, None)
+        """Delete the client's own document of this id; it needs a source, as the client does.
+
+        A document the source does not hold raises ``SpotAPIError`` 404, as
+        the store answers.
+        """
+        if not self.source:
+            raise ValueError("delete needs a source: FakeKnowledgeClient(source=...)")
+        if self._docs.pop((self.source, doc_id), None) is None:
+            raise SpotAPIError("DELETE", _document_path(self.source, doc_id), 404)
 
     async def replace_source(self, docs: list[KnowledgeDocument]) -> None:
         """Keep ``docs`` as the source's documents, as the store does: an empty
@@ -64,13 +87,16 @@ class FakeKnowledgeClient:
             raise ValueError(
                 "replace_source needs a source: FakeKnowledgeClient(source=...)"
             )
+        self._refuse_other_sources(docs)
+        for key in [key for key in self._docs if key[0] == self.source]:
+            del self._docs[key]
+        self.add(*(d.model_copy(update={"source": self.source}) for d in docs))
+
+    def _refuse_other_sources(self, docs: list[KnowledgeDocument]) -> None:
+        """Refuse documents naming another source than the client's: the store answers 403."""
         foreign = sorted({d.source for d in docs} - {"", self.source})
         if foreign:
             raise ValueError(f"documents of another source: {foreign}")
-        for doc_id in [i for i, d in self._docs.items() if d.source == self.source]:
-            del self._docs[doc_id]
-        for d in docs:
-            self._docs[d.id] = d.model_copy(update={"source": self.source})
 
     # --- read side ----------------------------------------------------- #
 
@@ -107,9 +133,9 @@ class FakeKnowledgeClient:
     # --- test helpers -------------------------------------------------- #
 
     def add(self, *docs: KnowledgeDocument) -> None:
-        """Store documents as they are, without awaiting (test helper)."""
+        """Store documents as they are, by source and id, without awaiting (test helper)."""
         for d in docs:
-            self._docs[d.id] = d
+            self._docs[d.source, d.id] = d
 
     def all(self) -> list[KnowledgeDocument]:
         """Return all stored documents (test helper)."""

{spot_sdk_python-2.0.0b11 → spot_sdk_python-2.0.0b13}/spot_sdk/workflow.py

@@ -15,6 +15,10 @@ ResponseMode = Literal["observe", "enforce"]
 DECISIVE_SIGNAL_PATTERN = r"^[a-z0-9_]+(\.[a-z0-9_]+)*\.([a-z0-9_]+|\*)$"
 """A signal name, or a prefix ending in ``.*``."""
 
+# A workflow id goes into URLs, log lines and the commit messages of the config
+# history: letters, digits, dots, underscores and hyphens only (sdk#26)
+WORKFLOW_ID_PATTERN = r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+
 
 class FailureStrategy(StrEnum):
     """Strategy for handling analyzer failures."""
@@ -163,7 +167,11 @@ class VerdictPolicy(BaseModel):
 class Workflow(BaseModel):
     """Complete workflow configuration for email analysis."""
 
-    id: str = Field(..., description="Workflow ID")
+    id: str = Field(
+        ...,
+        pattern=WORKFLOW_ID_PATTERN,
+        description="Workflow ID: a letter or digit, then up to 127 letters, digits, dots, underscores or hyphens",
+    )
     name: str = Field(..., description="Workflow name")
     version: int = Field(default=1, ge=1, description="Workflow version")
     description: str = Field(default="", description="Workflow description")

spot_sdk_python-2.0.0b11/pyproject.toml

@@ -1,38 +0,0 @@
-[build-system]
-requires = ["poetry-core"]
-build-backend = "poetry.core.masonry.api"
-
-[tool.poetry]
-name = "spot-sdk-python"
-version = "2.0.0b11"
-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"
-homepage = "https://sonn.lu"
-readme = "README.md"
-packages = [
-    {include = "spot_sdk"}
-]
-
-[tool.poetry.dependencies]
-python = ">=3.11,<3.16"
-pydantic = "^2.10"
-pydantic-settings = "^2.0.0"
-httpx2 = ">=2.13.1,<3"
-selectolax = ">=1.0,<1.1"
-idna = ">=3.11,<4"
-fastapi = ">=0.133.0,<1"
-starlette = ">=1.7.0,<2"
-
-[tool.poetry.group.dev.dependencies]
-pytest = "^9.0.3"
-pytest-asyncio = "^1.3.0"
-pytest-cov = "^4.1.0"
-mypy = "^1.5.0"
-
-[tool.ruff]
-target-version = "py311"
-
-[tool.ruff.lint]
-select = ["E", "F", "I", "N", "W"]
-ignore = ["E501"]  # Line too long