nullprotocol 0.2.0__py3-none-any.whl

nullprotocol/_common.py

@@ -0,0 +1,292 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from copy import deepcopy
+from dataclasses import dataclass
+from threading import Lock
+from typing import Any, TypeVar
+from uuid import UUID, uuid4
+from weakref import WeakKeyDictionary, WeakValueDictionary
+
+from jsonschema import Draft202012Validator, FormatChecker
+
+from ._transport import identifier, json_body, request_id, scope_id, utf16_length
+from ._types import Result
+
+Knowledge = bool | dict[str, str]
+ActionChoice = str | dict[str, str]
+
+
+def object_field(body: dict[str, Any], field: str) -> dict[str, Any]:
+    from ._errors import ProtocolError
+
+    value = body.get(field)
+    if not isinstance(value, dict):
+        raise ProtocolError(f"Missing {field} in the server response.")
+    return value
+
+
+def list_field(body: dict[str, Any], field: str) -> list[dict[str, Any]]:
+    from ._errors import ProtocolError
+
+    value = body.get(field)
+    if not isinstance(value, list) or not all(isinstance(row, dict) for row in value):
+        raise ProtocolError(f"Missing {field} in the server response.")
+    return value
+
+
+def version(value: str) -> str:
+    try:
+        UUID(value)
+    except (ValueError, TypeError, AttributeError) as exc:
+        raise ValueError("Expected a UUID version or note ID.") from exc
+    return value
+
+
+def checked_text(value: str, name: str, maximum: int) -> str:
+    if not isinstance(value, str) or not value.strip() or utf16_length(value) > maximum:
+        raise ValueError(
+            f"{name} must be a nonempty string of at most {maximum} UTF-16 characters."
+        )
+    if re.search(r"[\x00-\x1f\x7f-\x9f]", value):
+        raise ValueError(f"{name} must not contain control characters.")
+    return value
+
+
+def operation_payload(
+    operation: str,
+    values: dict[str, Any],
+    scope: str | None,
+    knowledge: Knowledge | None,
+    context_keys: list[str] | None,
+) -> dict[str, Any]:
+    body = {"operation": operation, **values}
+    if scope is not None:
+        body["conversation"] = scope
+    if knowledge is not None:
+        if type(knowledge) is bool:
+            body["knowledge"] = knowledge
+        elif isinstance(knowledge, dict) and set(knowledge) == {"query"}:
+            query = knowledge["query"]
+            if (
+                not isinstance(query, str)
+                or not query.strip()
+                or utf16_length(query.strip()) > 2000
+            ):
+                raise ValueError(
+                    "Knowledge query must have 1–2000 UTF-16 characters after trimming."
+                )
+            # The server returns knowledge_query_too_large if the byte limit is exceeded.
+            body["knowledge"] = {"query": query.strip()}
+        else:
+            raise ValueError("knowledge must be a bool or {'query': '...'}.")
+    if context_keys is not None:
+        if not isinstance(context_keys, list) or len(context_keys) > 16:
+            raise ValueError("context_keys must be a list of at most 16 keys.")
+        body["contextKeys"] = [identifier(key, "context key") for key in context_keys]
+    if len(json_body(body)) > 131072:
+        raise ValueError("The HTTP operation body exceeds 131072 UTF-8 bytes.")
+    return body
+
+
+def summary_options(content: Any, max_length: int, focus: str | None) -> dict[str, Any]:
+    if type(max_length) is not int or not 1 <= max_length <= 10000:
+        raise ValueError("max_length must be an integer from 1 to 10000.")
+    body = {"content": content, "maxLength": max_length}
+    if focus is not None:
+        if not isinstance(focus, str) or utf16_length(focus) > 1000:
+            raise ValueError("focus must have at most 1000 UTF-16 characters.")
+        body["focus"] = focus
+    return body
+
+
+def validation_options(
+    criteria: str, subject: Any, reference: Any, unset: object
+) -> dict[str, Any]:
+    if not isinstance(criteria, str) or not 1 <= utf16_length(criteria) <= 16384:
+        raise ValueError("criteria must have 1–16384 UTF-16 characters.")
+    body = {"criteria": criteria, "subject": subject}
+    if reference is not unset:
+        body["reference"] = reference
+    return body
+
+
+def schema_validator(schema: dict[str, Any]) -> Draft202012Validator:
+    if not isinstance(schema, dict):
+        raise ValueError("input_schema must be a JSON Schema object.")
+    Draft202012Validator.check_schema(schema)
+    checker = FormatChecker()
+
+    def check(value: Any) -> None:
+        if not isinstance(value, dict):
+            return
+        for ref in ("$ref", "$dynamicRef", "$recursiveRef"):
+            if ref in value and not str(value[ref]).startswith("#"):
+                raise ValueError(
+                    "Action schemas must use local references; remote refs are unsupported."
+                )
+        if "format" in value and value["format"] not in checker.checkers:
+            raise ValueError(f"Unsupported action schema format: {value['format']}")
+        # Descend through schema positions only. A property literally named
+        # format/$ref, an enum value or a default is ordinary application data.
+        for keyword in (
+            "properties",
+            "patternProperties",
+            "$defs",
+            "definitions",
+            "dependentSchemas",
+        ):
+            for child in value.get(keyword, {}).values():
+                check(child)
+        for keyword in ("allOf", "anyOf", "oneOf", "prefixItems"):
+            for child in value.get(keyword, []):
+                check(child)
+        for keyword in (
+            "items",
+            "additionalItems",
+            "additionalProperties",
+            "unevaluatedProperties",
+            "unevaluatedItems",
+            "contains",
+            "propertyNames",
+            "if",
+            "then",
+            "else",
+            "not",
+            "contentSchema",
+        ):
+            child = value.get(keyword)
+            if isinstance(child, list):
+                for item in child:
+                    check(item)
+            else:
+                check(child)
+        for child in value.get("dependencies", {}).values():
+            if isinstance(child, dict):
+                check(child)
+
+    check(schema)
+    return Draft202012Validator(deepcopy(schema), format_checker=checker)
+
+
+@dataclass
+class RegisteredAction:
+    handler: Callable[..., Any]
+    description: str | None
+    schema: dict[str, Any] | None
+    validator: Draft202012Validator | None
+    guard: Callable[..., Any] | None
+
+
+@dataclass
+class MadeDecision:
+    snapshot: Result[Any]
+    input: Any
+    executed: bool = False
+
+
+_AgentT = TypeVar("_AgentT", bound="AgentState")
+
+
+class AgentState:
+    def __init__(self, agent_id: str, scope: str | None) -> None:
+        self.agent_id = identifier(agent_id, "agent ID")
+        self.scope = scope_id(scope)
+        self._actions: dict[str, RegisteredAction] = {}
+        self._decisions: WeakKeyDictionary[Result[Any], MadeDecision] = WeakKeyDictionary()
+        self._decision_ids: WeakValueDictionary[str, MadeDecision] = WeakValueDictionary()
+        self._lock = Lock()
+
+    @property
+    def _path(self) -> str:
+        return f"/agents/{self.agent_id}"
+
+    def register_action(
+        self: _AgentT,
+        name: str,
+        handler: Callable[..., Any],
+        *,
+        description: str | None = None,
+        input_schema: dict[str, Any] | None = None,
+        guard: Callable[..., Any] | None = None,
+    ) -> _AgentT:
+        checked_text(name, "Action name", 64)
+        if not callable(handler) or (guard is not None and not callable(guard)):
+            raise ValueError("handler and guard must be callable.")
+        if description is not None and (
+            not isinstance(description, str) or utf16_length(description) > 1000
+        ):
+            raise ValueError("Action description must have at most 1000 UTF-16 characters.")
+        validator = schema_validator(input_schema) if input_schema is not None else None
+        self._actions[name] = RegisteredAction(
+            handler,
+            description,
+            deepcopy(input_schema),
+            validator,
+            guard,
+        )
+        return self
+
+    def _choices(self, context: Any, actions: list[ActionChoice]) -> dict[str, Any]:
+        if not isinstance(actions, list) or not 1 <= len(actions) <= 32:
+            raise ValueError("actions must contain 1–32 action choices.")
+        choices, schemas = [], {}
+        for offered in actions:
+            if isinstance(offered, str):
+                name = offered
+                description = None
+            elif isinstance(offered, dict) and set(offered) <= {"action", "description"}:
+                name = offered.get("action", "")
+                description = offered.get("description")
+            else:
+                raise ValueError(
+                    "Use action names or {'action': name, 'description': text} choices."
+                )
+            checked_text(name, "Action name", 64)
+            registered = self._actions.get(name)
+            if description is None and registered is not None:
+                description = registered.description
+            choice = {"action": name}
+            if description is not None:
+                if not isinstance(description, str) or utf16_length(description) > 1000:
+                    raise ValueError("Action description must have at most 1000 UTF-16 characters.")
+                choice["description"] = description
+            choices.append(choice)
+            if registered is not None and registered.schema is not None:
+                schemas[name] = deepcopy(registered.schema)
+        # The HTTP endpoint accepts action descriptions, not schemas. Send schema
+        # contracts as structured task data and enforce them locally before execution.
+        prepared = {"task": context, "actionParameterSchemas": schemas} if schemas else context
+        return {"context": prepared, "actions": choices}
+
+    def _remember(self, result: Result[Any], original: Any) -> Result[Any]:
+        if result.success:
+            snapshot = Result.from_response(
+                {"result": result.raw, "operationId": result.operation_id},
+                result.request_id,
+            )
+            with self._lock:
+                key = result.operation_id or "request:" + result.request_id
+                made = self._decision_ids.get(key)
+                if made is None:
+                    made = MadeDecision(snapshot, deepcopy(original))
+                    self._decision_ids[key] = made
+                self._decisions[result] = made
+        return result
+
+    def _consume(self, result: Result[Any]) -> tuple[MadeDecision | None, str | None]:
+        if not isinstance(result, Result):
+            return None, "not_a_decision"
+        with self._lock:
+            made = self._decisions.get(result)
+            if made is None:
+                return None, "not_a_decision"
+            if made.executed:
+                return made, "already_executed"
+            made.executed = True
+            return made, None
+
+    @staticmethod
+    def _task_id(value: str | None) -> str:
+        return request_id(str(uuid4()) if value is None else value)

nullprotocol/_errors.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class NullProtocolError(Exception):
+    """Base SDK error. Failed model operations are returned as Result, not raised."""
+
+
+class APIError(NullProtocolError):
+    """An HTTP failure. Keep request_id when retrying an uncertain run."""
+
+    def __init__(
+        self,
+        status_code: int,
+        code: str,
+        *,
+        request_id: str | None = None,
+        details: dict[str, Any] | None = None,
+        retry_after: str | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.code = code
+        self.request_id = request_id
+        self.details = details or {}
+        self.retry_after = retry_after
+        super().__init__(f"NullProtocol HTTP {status_code}: {code}")
+
+
+class TransportError(NullProtocolError):
+    """The response was not received. A run may have completed: retain request_id."""
+
+    def __init__(self, message: str, *, request_id: str | None = None) -> None:
+        self.request_id = request_id
+        super().__init__(message)
+
+
+class ProtocolError(NullProtocolError):
+    """The server response does not match the expected response contract."""
+
+    def __init__(self, message: str, *, request_id: str | None = None) -> None:
+        self.request_id = request_id
+        super().__init__(message)

nullprotocol/_knowledge.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ._common import checked_text, list_field, object_field, version
+from ._transport import AsyncTransport, Transport
+
+
+def _fields(
+    name: str | None, text: str | None, *, update: bool = False, if_version: str | None = None
+) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    if name is not None or not update:
+        if not isinstance(name, str):
+            raise ValueError("Knowledge name must be text.")
+        result["name"] = checked_text(name.strip(), "Knowledge name", 120)
+    if text is not None or not update:
+        if not isinstance(text, str) or not text.strip() or "\0" in text:
+            raise ValueError("Knowledge text must be nonempty UTF-8 text without NUL characters.")
+        if len(text.encode("utf-8")) > 1048576:
+            raise ValueError("A Knowledge document holds up to 1 MiB of UTF-8 text.")
+        result["text"] = text
+    if update:
+        if not result:
+            raise ValueError("Supply a new name or text to update a Knowledge document.")
+        if not isinstance(if_version, str):
+            raise ValueError("if_version is required; read the document's current version first.")
+        result["ifVersion"] = version(if_version)
+    return result
+
+
+class _Documents:
+    def __init__(self, transport: Transport, path: str, scope: str) -> None:
+        self._transport, self._path, self._scope = transport, path, scope
+
+    def _all(self) -> list[dict[str, Any]]:
+        return list_field(self._transport.request("GET", self._path), "sources")
+
+    def list(self) -> list[dict[str, Any]]:
+        """List documents owned by this scope. Connections are listed separately."""
+        return [source for source in self._all() if source.get("scope") == self._scope]
+
+    def get(self, source_id: str) -> dict[str, Any]:
+        return object_field(
+            self._transport.request("GET", self._path + "/" + version(source_id)), "source"
+        )
+
+    def add(self, *, name: str, text: str) -> dict[str, Any]:
+        """Save text and begin preparation. Inspect get(id)['state'] for readiness."""
+        return self._transport.request("POST", self._path, body=_fields(name, text))
+
+    def update(
+        self, source_id: str, *, if_version: str, name: str | None = None, text: str | None = None
+    ) -> dict[str, Any]:
+        return self._transport.request(
+            "PUT",
+            self._path + "/" + version(source_id),
+            body=_fields(name, text, update=True, if_version=if_version),
+        )
+
+    def delete(self, source_id: str, *, if_version: str) -> None:
+        self._transport.request(
+            "DELETE", self._path + "/" + version(source_id), body={"ifVersion": version(if_version)}
+        )
+
+    def retry(self, source_id: str) -> dict[str, Any]:
+        """Explicitly retry failed preparation; this can make embedding requests."""
+        return self._transport.request(
+            "POST", self._path + "/" + version(source_id) + "/retry", body={}
+        )
+
+
+class KnowledgeLibrary(_Documents):
+    """The Space's shared library. Adding a source does not connect it to an agent."""
+
+    def __init__(self, transport: Transport) -> None:
+        super().__init__(transport, "/knowledge", "space")
+
+    def usage(self) -> dict[str, Any]:
+        """Embedding usage over 30 days; unknown sums remain None, known sums are strings."""
+        return object_field(self._transport.request("GET", self._path), "usage")
+
+
+class AgentKnowledge(_Documents):
+    def __init__(self, transport: Transport, agent_id: str) -> None:
+        super().__init__(transport, f"/agents/{agent_id}/knowledge", "agent")
+        self._links = f"/agents/{agent_id}/knowledge-links"
+
+    def connections(self) -> list[dict[str, Any]]:
+        return [s for s in self._all() if s.get("scope") == "space" and s.get("attached")]
+
+    def connect(self, space_source_id: str) -> dict[str, Any]:
+        return self._transport.request("PUT", self._links + "/" + version(space_source_id), body={})
+
+    def disconnect(self, space_source_id: str) -> dict[str, Any]:
+        return self._transport.request(
+            "DELETE", self._links + "/" + version(space_source_id), body={}
+        )
+
+
+class _AsyncDocuments:
+    def __init__(self, transport: AsyncTransport, path: str, scope: str) -> None:
+        self._transport, self._path, self._scope = transport, path, scope
+
+    async def _all(self) -> list[dict[str, Any]]:
+        return list_field(await self._transport.request("GET", self._path), "sources")
+
+    async def list(self) -> list[dict[str, Any]]:
+        return [source for source in await self._all() if source.get("scope") == self._scope]
+
+    async def get(self, source_id: str) -> dict[str, Any]:
+        return object_field(
+            await self._transport.request("GET", self._path + "/" + version(source_id)), "source"
+        )
+
+    async def add(self, *, name: str, text: str) -> dict[str, Any]:
+        return await self._transport.request("POST", self._path, body=_fields(name, text))
+
+    async def update(
+        self, source_id: str, *, if_version: str, name: str | None = None, text: str | None = None
+    ) -> dict[str, Any]:
+        return await self._transport.request(
+            "PUT",
+            self._path + "/" + version(source_id),
+            body=_fields(name, text, update=True, if_version=if_version),
+        )
+
+    async def delete(self, source_id: str, *, if_version: str) -> None:
+        await self._transport.request(
+            "DELETE", self._path + "/" + version(source_id), body={"ifVersion": version(if_version)}
+        )
+
+    async def retry(self, source_id: str) -> dict[str, Any]:
+        return await self._transport.request(
+            "POST", self._path + "/" + version(source_id) + "/retry", body={}
+        )
+
+
+class AsyncKnowledgeLibrary(_AsyncDocuments):
+    def __init__(self, transport: AsyncTransport) -> None:
+        super().__init__(transport, "/knowledge", "space")
+
+    async def usage(self) -> dict[str, Any]:
+        return object_field(await self._transport.request("GET", self._path), "usage")
+
+
+class AsyncAgentKnowledge(_AsyncDocuments):
+    def __init__(self, transport: AsyncTransport, agent_id: str) -> None:
+        super().__init__(transport, f"/agents/{agent_id}/knowledge", "agent")
+        self._links = f"/agents/{agent_id}/knowledge-links"
+
+    async def connections(self) -> list[dict[str, Any]]:
+        return [s for s in await self._all() if s.get("scope") == "space" and s.get("attached")]
+
+    async def connect(self, space_source_id: str) -> dict[str, Any]:
+        return await self._transport.request(
+            "PUT", self._links + "/" + version(space_source_id), body={}
+        )
+
+    async def disconnect(self, space_source_id: str) -> dict[str, Any]:
+        return await self._transport.request(
+            "DELETE", self._links + "/" + version(space_source_id), body={}
+        )

nullprotocol/_stores.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ._common import list_field, object_field, version
+from ._knowledge import AsyncKnowledgeLibrary, KnowledgeLibrary
+from ._transport import _UNSET, AsyncTransport, Transport, identifier
+
+
+def _context_body(value: Any, inclusion: str | None, if_version: Any) -> dict[str, Any]:
+    body = {"value": value}
+    if inclusion is not None:
+        if inclusion not in ("always", "selected"):
+            raise ValueError("inclusion must be 'always' or 'selected'.")
+        body["inclusion"] = inclusion
+    if if_version is not _UNSET:
+        body["ifVersion"] = None if if_version is None else version(if_version)
+    return body
+
+
+class ContextStore:
+    def __init__(self, transport: Transport, path: str, scope: str | None = None) -> None:
+        self._transport, self._path = transport, path
+        self._params = {"conversation": scope} if scope is not None else None
+
+    def list(self) -> list[dict[str, Any]]:
+        return list_field(
+            self._transport.request("GET", self._path, params=self._params), "entries"
+        )
+
+    def get(self, key: str) -> dict[str, Any]:
+        return object_field(
+            self._transport.request(
+                "GET",
+                self._path + "/" + identifier(key, "context key"),
+                params=self._params,
+            ),
+            "entry",
+        )
+
+    def set(
+        self,
+        key: str,
+        value: Any,
+        *,
+        inclusion: str | None = None,
+        if_version: Any = _UNSET,
+    ) -> dict[str, Any]:
+        return object_field(
+            self._transport.request(
+                "PUT",
+                self._path + "/" + identifier(key, "context key"),
+                params=self._params,
+                body=_context_body(value, inclusion, if_version),
+            ),
+            "entry",
+        )
+
+    def delete(self, key: str) -> None:
+        self._transport.request(
+            "DELETE",
+            self._path + "/" + identifier(key, "context key"),
+            params=self._params,
+        )
+
+
+class AsyncContextStore:
+    def __init__(self, transport: AsyncTransport, path: str, scope: str | None = None) -> None:
+        self._transport, self._path = transport, path
+        self._params = {"conversation": scope} if scope is not None else None
+
+    async def list(self) -> list[dict[str, Any]]:
+        return list_field(
+            await self._transport.request(
+                "GET",
+                self._path,
+                params=self._params,
+            ),
+            "entries",
+        )
+
+    async def get(self, key: str) -> dict[str, Any]:
+        return object_field(
+            await self._transport.request(
+                "GET",
+                self._path + "/" + identifier(key, "context key"),
+                params=self._params,
+            ),
+            "entry",
+        )
+
+    async def set(
+        self,
+        key: str,
+        value: Any,
+        *,
+        inclusion: str | None = None,
+        if_version: Any = _UNSET,
+    ) -> dict[str, Any]:
+        return object_field(
+            await self._transport.request(
+                "PUT",
+                self._path + "/" + identifier(key, "context key"),
+                params=self._params,
+                body=_context_body(value, inclusion, if_version),
+            ),
+            "entry",
+        )
+
+    async def delete(self, key: str) -> None:
+        await self._transport.request(
+            "DELETE",
+            self._path + "/" + identifier(key, "context key"),
+            params=self._params,
+        )
+
+
+def _note(text: str, scope: str | None) -> dict[str, Any]:
+    if not isinstance(text, str) or not text.strip() or len(text.strip().encode()) > 4096:
+        raise ValueError("A note must be nonempty text of at most 4096 UTF-8 bytes.")
+    return {"text": text, **({"conversation": scope} if scope is not None else {})}
+
+
+class MemoryStore:
+    def __init__(self, transport: Transport, path: str, scope: str | None) -> None:
+        self._transport, self._path, self._scope = transport, path, scope
+
+    def list(self) -> list[dict[str, Any]]:
+        return list_field(
+            self._transport.request(
+                "GET",
+                self._path,
+                params={"conversation": self._scope} if self._scope else None,
+            ),
+            "notes",
+        )
+
+    def add(self, text: str) -> dict[str, Any]:
+        return object_field(
+            self._transport.request(
+                "POST",
+                self._path,
+                body=_note(text, self._scope),
+            ),
+            "note",
+        )
+
+    def delete(self, note_id: str) -> None:
+        self._transport.request("DELETE", self._path + "/" + version(note_id))
+
+
+class AsyncMemoryStore:
+    def __init__(self, transport: AsyncTransport, path: str, scope: str | None) -> None:
+        self._transport, self._path, self._scope = transport, path, scope
+
+    async def list(self) -> list[dict[str, Any]]:
+        return list_field(
+            await self._transport.request(
+                "GET",
+                self._path,
+                params={"conversation": self._scope} if self._scope else None,
+            ),
+            "notes",
+        )
+
+    async def add(self, text: str) -> dict[str, Any]:
+        return object_field(
+            await self._transport.request(
+                "POST",
+                self._path,
+                body=_note(text, self._scope),
+            ),
+            "note",
+        )
+
+    async def delete(self, note_id: str) -> None:
+        await self._transport.request("DELETE", self._path + "/" + version(note_id))
+
+
+class SpaceContextStore(ContextStore):
+    def __init__(self, transport: Transport) -> None:
+        super().__init__(transport, "/context")
+        self.knowledge = KnowledgeLibrary(transport)
+
+
+class AsyncSpaceContextStore(AsyncContextStore):
+    def __init__(self, transport: AsyncTransport) -> None:
+        super().__init__(transport, "/context")
+        self.knowledge = AsyncKnowledgeLibrary(transport)