upp-python 0.1.0__py3-none-any.whl

upp/rpc/codec.py

@@ -0,0 +1,112 @@
+"""UPP JSON-RPC 2.0 Codec.
+
+Provides functions for encoding and decoding JSON-RPC 2.0 messages as
+JSON strings. The codec handles serialization/deserialization between
+:class:`JsonRpcRequest`/:class:`JsonRpcResponse` Pydantic models and
+their JSON wire format.
+
+Usage::
+
+    from upp.rpc.codec import encode_request, decode_response
+
+    wire = encode_request("upp/ingest", {"entity_key": "u1", "text": "..."}, request_id=1)
+    response = decode_response(wire_response)
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from upp.rpc.messages import JsonRpcError, JsonRpcRequest, JsonRpcResponse
+
+__all__ = [
+    "decode_request",
+    "decode_response",
+    "encode_request",
+    "encode_response",
+]
+
+
+def encode_request(
+    method: str,
+    params: dict[str, Any],
+    request_id: int | str,
+) -> str:
+    """Encode a JSON-RPC 2.0 request as a JSON string.
+
+    Args:
+        method: The method name (e.g., ``"upp/ingest"``).
+        params: The method parameters as a dictionary.
+        request_id: Unique request identifier.
+
+    Returns:
+        A JSON string representing the full JSON-RPC 2.0 request.
+    """
+    request = JsonRpcRequest(
+        id=request_id,
+        method=method,
+        params=params,
+    )
+    return request.model_dump_json()
+
+
+def decode_request(data: str) -> JsonRpcRequest:
+    """Decode a JSON string into a :class:`JsonRpcRequest`.
+
+    Args:
+        data: A JSON string representing a JSON-RPC 2.0 request.
+
+    Returns:
+        A validated :class:`JsonRpcRequest` instance.
+
+    Raises:
+        pydantic.ValidationError: If the JSON does not conform to the
+            JSON-RPC 2.0 request schema.
+        json.JSONDecodeError: If the string is not valid JSON.
+    """
+    parsed = json.loads(data)
+    return JsonRpcRequest.model_validate(parsed)
+
+
+def encode_response(
+    request_id: int | str | None,
+    result: dict[str, Any] | None = None,
+    error: JsonRpcError | None = None,
+) -> str:
+    """Encode a JSON-RPC 2.0 response as a JSON string.
+
+    Either ``result`` or ``error`` should be provided, but not both.
+
+    Args:
+        request_id: The matching request identifier.
+        result: The result value on success.
+        error: The error object on failure.
+
+    Returns:
+        A JSON string representing the full JSON-RPC 2.0 response.
+    """
+    response = JsonRpcResponse(
+        id=request_id,
+        result=result,
+        error=error,
+    )
+    return response.model_dump_json()
+
+
+def decode_response(data: str) -> JsonRpcResponse:
+    """Decode a JSON string into a :class:`JsonRpcResponse`.
+
+    Args:
+        data: A JSON string representing a JSON-RPC 2.0 response.
+
+    Returns:
+        A validated :class:`JsonRpcResponse` instance.
+
+    Raises:
+        pydantic.ValidationError: If the JSON does not conform to the
+            JSON-RPC 2.0 response schema.
+        json.JSONDecodeError: If the string is not valid JSON.
+    """
+    parsed = json.loads(data)
+    return JsonRpcResponse.model_validate(parsed)

upp/rpc/errors.py

@@ -0,0 +1,127 @@
+"""UPP Error Codes and Exception Class.
+
+Defines all standard JSON-RPC 2.0 error codes, UPP-specific error codes,
+and the :class:`UppError` exception class used throughout the protocol.
+
+Standard JSON-RPC Error Codes:
+    -32700  Parse error
+    -32600  Invalid Request
+    -32601  Method not found
+    -32602  Invalid params
+    -32603  Internal error
+
+UPP-Specific Error Codes (-32001 to -32099):
+    -32001  User not found
+    -32002  Ontology not found
+    -32003  Ingest failed
+    -32004  Extraction failed
+"""
+
+from __future__ import annotations
+
+from upp.rpc.messages import JsonRpcError
+
+__all__ = [
+    # Standard JSON-RPC error codes
+    "INTERNAL_ERROR",
+    "INVALID_PARAMS",
+    "INVALID_REQUEST",
+    "METHOD_NOT_FOUND",
+    "PARSE_ERROR",
+    # UPP-specific error codes
+    "EXTRACTION_FAILED",
+    "ONTOLOGY_NOT_FOUND",
+    "INGEST_FAILED",
+    "USER_NOT_FOUND",
+    # Exception class
+    "UppError",
+]
+
+# ---------------------------------------------------------------------------
+# Standard JSON-RPC 2.0 Error Codes
+# ---------------------------------------------------------------------------
+
+#: Invalid JSON received by the server.
+PARSE_ERROR: int = -32700
+
+#: The JSON is valid but not a valid JSON-RPC 2.0 request.
+INVALID_REQUEST: int = -32600
+
+#: The requested method does not exist or is not available.
+METHOD_NOT_FOUND: int = -32601
+
+#: Invalid method parameter(s).
+INVALID_PARAMS: int = -32602
+
+#: Internal JSON-RPC error.
+INTERNAL_ERROR: int = -32603
+
+# ---------------------------------------------------------------------------
+# UPP-Specific Error Codes (-32001 to -32099)
+# ---------------------------------------------------------------------------
+
+#: The specified ``entity_key`` does not exist.
+USER_NOT_FOUND: int = -32001
+
+#: The requested ontology does not exist.
+ONTOLOGY_NOT_FOUND: int = -32002
+
+#: Error persisting events during ingestion.
+INGEST_FAILED: int = -32003
+
+#: Error extracting events from text.
+EXTRACTION_FAILED: int = -32004
+
+
+# ---------------------------------------------------------------------------
+# Exception Class
+# ---------------------------------------------------------------------------
+
+
+class UppError(Exception):
+    """Exception representing a UPP protocol error.
+
+    Can be raised by any backend or the client when a protocol-level
+    error occurs. Provides a :meth:`to_jsonrpc_error` method for
+    converting to a :class:`JsonRpcError`.
+
+    Attributes:
+        code: The numeric error code.
+        message: A human-readable description of the error.
+        data: Optional additional structured error data.
+    """
+
+    def __init__(
+        self,
+        code: int,
+        message: str,
+        data: dict[str, object] | None = None,
+    ) -> None:
+        """Initialize a UPP error.
+
+        Args:
+            code: The numeric error code.
+            message: A human-readable description.
+            data: Optional structured data providing additional context.
+        """
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.data = data
+
+    def to_jsonrpc_error(self) -> JsonRpcError:
+        """Convert this exception to a :class:`JsonRpcError` object.
+
+        Returns:
+            A :class:`JsonRpcError` suitable for inclusion in a
+            :class:`JsonRpcResponse`.
+        """
+        return JsonRpcError(
+            code=self.code,
+            message=self.message,
+            data=self.data,
+        )
+
+    def __repr__(self) -> str:
+        """Return a developer-friendly string representation."""
+        return f"UppError(code={self.code}, message={self.message!r})"

upp/rpc/messages.py

@@ -0,0 +1,354 @@
+"""UPP JSON-RPC 2.0 Message Types and Operation Models.
+
+Defines Pydantic models for the four JSON-RPC 2.0 message types and
+typed request/response models for all ten UPP operations.
+
+JSON-RPC Message Types:
+    JsonRpcRequest, JsonRpcResponse, JsonRpcError, JsonRpcNotification
+
+Operation Request/Response Models:
+    IngestRequest/IngestResponse, RetrieveRequest/RetrieveResponse,
+    EventsRequest/EventsResponse, DeleteRequest/DeleteResponse,
+    InfoRequest/InfoResponse, LabelsRequest/LabelsResponse,
+    ExportRequest/ExportResponse, ImportRequest/ImportResponse
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from upp.models.events import Event, StoredEvent, TaskResult
+from upp.models.labels import LabelDefinition
+
+__all__ = [
+    # JSON-RPC base types
+    "JsonRpcError",
+    "JsonRpcNotification",
+    "JsonRpcRequest",
+    "JsonRpcResponse",
+    # Operation request/response models
+    "ContextualizeRequest",
+    "ContextualizeResponse",
+    "DeleteRequest",
+    "DeleteResponse",
+    "EventsRequest",
+    "EventsResponse",
+    "ExportRequest",
+    "ExportResponse",
+    "GetTasksRequest",
+    "GetTasksResponse",
+    "ImportRequest",
+    "ImportResponse",
+    "InfoRequest",
+    "InfoResponse",
+    "LabelsRequest",
+    "LabelsResponse",
+    "RetrieveRequest",
+    "RetrieveResponse",
+    "IngestRequest",
+    "IngestResponse",
+]
+
+
+# ---------------------------------------------------------------------------
+# JSON-RPC 2.0 Base Types
+# ---------------------------------------------------------------------------
+
+
+class JsonRpcError(BaseModel):
+    """JSON-RPC 2.0 error object.
+
+    Attributes:
+        code: A number indicating the error type.
+        message: A short, human-readable description of the error.
+        data: Additional structured data about the error (optional).
+    """
+
+    code: int = Field(description="A number indicating the error type.")
+    message: str = Field(description="A short, human-readable description of the error.")
+    data: dict[str, Any] | None = Field(
+        default=None,
+        description="Additional structured data about the error.",
+    )
+
+
+class JsonRpcRequest(BaseModel):
+    """JSON-RPC 2.0 request message.
+
+    Attributes:
+        jsonrpc: Protocol version, always ``"2.0"``.
+        id: Unique request identifier.
+        method: The name of the method to invoke.
+        params: Method parameters as a dictionary.
+    """
+
+    jsonrpc: Literal["2.0"] = Field(
+        default="2.0",
+        description='JSON-RPC protocol version. Always "2.0".',
+    )
+    id: int | str = Field(description="Unique request identifier.")
+    method: str = Field(description="The name of the method to invoke.")
+    params: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Method parameters as a dictionary.",
+    )
+
+
+class JsonRpcResponse(BaseModel):
+    """JSON-RPC 2.0 response message.
+
+    Contains either ``result`` (success) or ``error`` (failure), not both.
+
+    Attributes:
+        jsonrpc: Protocol version, always ``"2.0"``.
+        id: Matching request identifier.
+        result: The result value on success.
+        error: The error object on failure.
+    """
+
+    jsonrpc: Literal["2.0"] = Field(
+        default="2.0",
+        description='JSON-RPC protocol version. Always "2.0".',
+    )
+    id: int | str | None = Field(default=None, description="Matching request identifier.")
+    result: dict[str, Any] | None = Field(
+        default=None,
+        description="The result value on success.",
+    )
+    error: JsonRpcError | None = Field(
+        default=None,
+        description="The error object on failure.",
+    )
+
+
+class JsonRpcNotification(BaseModel):
+    """JSON-RPC 2.0 notification message (fire-and-forget, no ``id``).
+
+    Attributes:
+        jsonrpc: Protocol version, always ``"2.0"``.
+        method: The name of the method to invoke.
+        params: Method parameters as a dictionary.
+    """
+
+    jsonrpc: Literal["2.0"] = Field(
+        default="2.0",
+        description='JSON-RPC protocol version. Always "2.0".',
+    )
+    method: str = Field(description="The name of the method to invoke.")
+    params: dict[str, Any] | None = Field(
+        default=None,
+        description="Method parameters as a dictionary.",
+    )
+
+
+# ---------------------------------------------------------------------------
+# UPP Operation Request/Response Models
+# ---------------------------------------------------------------------------
+
+
+class IngestRequest(BaseModel):
+    """Request model for ``upp/ingest``.
+
+    Attributes:
+        entity_key: Identifier of the user.
+        text: Text from which to extract events.
+    """
+
+    entity_key: str = Field(description="Identifier of the user.")
+    text: str = Field(description="Text from which to extract events.")
+
+
+class IngestResponse(BaseModel):
+    """Response model for ``upp/ingest``.
+
+    Attributes:
+        events: The stored events with server-assigned metadata.
+    """
+
+    events: list[StoredEvent] = Field(description="The stored events.")
+
+
+class RetrieveRequest(BaseModel):
+    """Request model for ``upp/retrieve``.
+
+    Attributes:
+        entity_key: Identifier of the user.
+        query: Free-text query for relevance matching.
+    """
+
+    entity_key: str = Field(description="Identifier of the user.")
+    query: str = Field(description="Free-text query for relevance matching.")
+
+
+class RetrieveResponse(BaseModel):
+    """Response model for ``upp/retrieve``.
+
+    Attributes:
+        events: Relevant events ranked by the server.
+    """
+
+    events: list[Event] = Field(description="Relevant events ranked by the server.")
+
+
+class EventsRequest(BaseModel):
+    """Request model for ``upp/events``.
+
+    Attributes:
+        entity_key: Identifier of the user.
+    """
+
+    entity_key: str = Field(description="Identifier of the user.")
+
+
+class EventsResponse(BaseModel):
+    """Response model for ``upp/events``.
+
+    Attributes:
+        events: All stored events for the user.
+    """
+
+    events: list[StoredEvent] = Field(description="All stored events for the user.")
+
+
+class DeleteRequest(BaseModel):
+    """Request model for ``upp/delete``.
+
+    Attributes:
+        entity_key: Identifier of the user.
+        event_ids: Specific event IDs to delete. If not provided, all events are deleted.
+    """
+
+    entity_key: str = Field(description="Identifier of the user.")
+    event_ids: list[str] | None = Field(
+        default=None,
+        description="Specific event IDs to delete. If omitted, all events are deleted.",
+    )
+
+
+class DeleteResponse(BaseModel):
+    """Response model for ``upp/delete``.
+
+    Attributes:
+        deleted_count: Number of events deleted.
+    """
+
+    deleted_count: int = Field(description="Number of events deleted.")
+
+
+class InfoRequest(BaseModel):
+    """Request model for ``upp/info``. No parameters required."""
+
+    pass
+
+
+class InfoResponse(BaseModel):
+    """Response model for ``upp/info``.
+
+    Attributes:
+        protocol_version: Semantic version of the UPP protocol.
+        ontology: The ontology identifier for this server instance.
+        operations: List of supported operations.
+        conformance_level: Server conformance level (1=Minimal, 2=Full, 3=Portable).
+    """
+
+    protocol_version: str = Field(description="Semantic version of the UPP protocol.")
+    ontology: str = Field(description="The ontology identifier for this server instance.")
+    operations: list[str] = Field(description="Supported operations.")
+    conformance_level: int = Field(
+        ge=1,
+        le=3,
+        description=("Server conformance level. 1: Minimal (ingest, retrieve, info). 2: Full (+ events, delete, labels). 3: Portable (+ export, import)."),
+    )
+
+
+class LabelsRequest(BaseModel):
+    """Request model for ``upp/labels``. No parameters required."""
+
+    pass
+
+
+class LabelsResponse(BaseModel):
+    """Response model for ``upp/labels``.
+
+    Attributes:
+        labels: Label definitions from the ontology.
+    """
+
+    labels: list[LabelDefinition] = Field(description="Label definitions from the ontology.")
+
+
+class ExportRequest(BaseModel):
+    """Request model for ``upp/export``.
+
+    Attributes:
+        entity_key: Identifier of the user.
+    """
+
+    entity_key: str = Field(description="Identifier of the user.")
+
+
+class ExportResponse(BaseModel):
+    """Response model for ``upp/export``.
+
+    Attributes:
+        file: Path to the exported JSON file.
+        event_count: Number of events exported.
+        exported_at: Timestamp of the export.
+    """
+
+    file: str = Field(description="Path to the exported JSON file.")
+    event_count: int = Field(description="Number of events exported.")
+    exported_at: datetime = Field(description="Timestamp of the export.")
+
+
+class ImportRequest(BaseModel):
+    """Request model for ``upp/import``.
+
+    Attributes:
+        entity_key: Identifier of the destination user.
+        file: Path to the JSON file containing events to import.
+    """
+
+    entity_key: str = Field(description="Identifier of the destination user.")
+    file: str = Field(description="Path to the JSON file containing events to import.")
+
+
+class ImportResponse(BaseModel):
+    """Response model for ``upp/import``.
+
+    Attributes:
+        imported_count: Number of events successfully imported.
+        skipped_count: Number of events skipped during import.
+    """
+
+    imported_count: int = Field(description="Number of events successfully imported.")
+    skipped_count: int = Field(description="Number of events skipped during import.")
+
+
+class ContextualizeRequest(BaseModel):
+    """Request model for ``upp/contextualize``."""
+
+    entity_key: str = Field(description="Identifier of the user.")
+    text: str = Field(description="Text to retrieve context for and extract events from.")
+
+
+class ContextualizeResponse(BaseModel):
+    """Response model for ``upp/contextualize``."""
+
+    events: list[StoredEvent] = Field(description="Relevant existing events.")
+    task_id: str = Field(description="Reference to the background ingest task.")
+
+
+class GetTasksRequest(BaseModel):
+    """Request model for ``upp/get_tasks``."""
+
+    task_ids: list[str] = Field(description="One or more task IDs to check.")
+
+
+class GetTasksResponse(BaseModel):
+    """Response model for ``upp/get_tasks``."""
+
+    tasks: list[TaskResult] = Field(description="Status of each requested task.")

upp/rpc/methods.py

@@ -0,0 +1,73 @@
+"""UPP JSON-RPC Method Constants.
+
+Defines the method name constants for all ten UPP operations.
+All method names use the ``upp/`` prefix as specified by the protocol.
+
+Operations:
+    5 Core: ingest, retrieve, events, delete, contextualize
+    3 Discovery: info, labels, get_tasks
+    2 Portability: export, import
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "ALL_METHODS",
+    "UPP_CONTEXTUALIZE",
+    "UPP_DELETE",
+    "UPP_EVENTS",
+    "UPP_EXPORT",
+    "UPP_GET_TASKS",
+    "UPP_IMPORT",
+    "UPP_INFO",
+    "UPP_LABELS",
+    "UPP_RETRIEVE",
+    "UPP_INGEST",
+]
+
+# Core operations
+UPP_INGEST: str = "upp/ingest"
+"""Extract and ingest events from text."""
+
+UPP_RETRIEVE: str = "upp/retrieve"
+"""Retrieve relevant events given a query."""
+
+UPP_EVENTS: str = "upp/events"
+"""List all stored events for a user."""
+
+UPP_DELETE: str = "upp/delete"
+"""Delete events for compliance (GDPR, CCPA)."""
+
+# Discovery operations
+UPP_INFO: str = "upp/info"
+"""Return server metadata."""
+
+UPP_LABELS: str = "upp/labels"
+"""List label definitions from an ontology."""
+
+# Portability operations
+UPP_EXPORT: str = "upp/export"
+"""Export events for migration."""
+
+UPP_IMPORT: str = "upp/import"
+"""Import events from another server."""
+
+UPP_CONTEXTUALIZE: str = "upp/contextualize"
+"""Retrieve context and ingest events in the background."""
+
+UPP_GET_TASKS: str = "upp/get_tasks"
+"""Check status of background tasks."""
+
+#: All UPP method names.
+ALL_METHODS: list[str] = [
+    UPP_INGEST,
+    UPP_RETRIEVE,
+    UPP_EVENTS,
+    UPP_DELETE,
+    UPP_INFO,
+    UPP_LABELS,
+    UPP_EXPORT,
+    UPP_IMPORT,
+    UPP_CONTEXTUALIZE,
+    UPP_GET_TASKS,
+]