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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spot-sdk-python
-Version: 2.0.0b11
+Version: 2.0.0b12
 Summary: SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers
 License: Apache-2.0
 Author: SPOT Project
@@ -51,7 +51,7 @@ plugins share:
 ## Install
 
 ```bash
-pip install spot-sdk-python==2.0.0b11
+pip install spot-sdk-python==2.0.0b12
 ```
 
 Python 3.11 to 3.15. Version 2 implements plugin contract 2, for

{spot_sdk_python-2.0.0b11 → spot_sdk_python-2.0.0b12}/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.0b12
 ```
 
 Python 3.11 to 3.15. Version 2 implements plugin contract 2, for

{spot_sdk_python-2.0.0b11 → spot_sdk_python-2.0.0b12}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "spot-sdk-python"
-version = "2.0.0b11"
+version = "2.0.0b12"
 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"

{spot_sdk_python-2.0.0b11 → spot_sdk_python-2.0.0b12}/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.0b12}/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.0b12}/spot_sdk/knowledge.py

@@ -64,8 +64,8 @@ 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. 'employee:alice@co.com'). "
+            "Upsert is idempotent on (source, id)."
         ),
     )
     content: str = Field(
@@ -88,7 +88,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 +106,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 +269,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 +284,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.0b12/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.0b12}/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)."""