upp-python 0.1.0__py3-none-any.whl

upp/__init__.py

@@ -0,0 +1,183 @@
+"""UPP — Universal Personalization Protocol Python Reference Implementation.
+
+This package provides the Python reference implementation of the Universal
+Personalization Protocol (UPP) data models, backend interfaces, JSON-RPC
+support, and a high-level client.
+
+Quick Start::
+
+    from upp import UPPClient, OntologyUserV1
+    from upp import Event, StoredEvent, LabelDefinition
+    from upp import EventStatus, SourceType, SensitivityTier
+
+Backend Protocols::
+
+    from upp import IngestBackend, RetrieverBackend, OntologyBackend
+
+All public types are re-exported from sub-packages for convenience.
+"""
+
+from importlib.metadata import version as _pkg_version
+
+__version__ = _pkg_version("upp-python")
+
+# --- Backend Protocols ---
+from upp.backends import (
+    IngestBackend,
+    OntologyBackend,
+    RetrieverBackend,
+)
+
+# --- Client ---
+from upp.client import UPPClient
+
+# --- Models ---
+from upp.models import (
+    Cardinality,
+    ContextualizeResult,
+    Durability,
+    Event,
+    EventStatus,
+    LabelDefinition,
+    SensitivityTier,
+    SourceType,
+    StoredEvent,
+    TaskResult,
+    TaskStatus,
+)
+
+# --- Ontologies ---
+from upp.ontologies.user_v1 import OntologyUserV1
+
+# --- RPC ---
+from upp.rpc import (
+    ALL_METHODS,
+    EXTRACTION_FAILED,
+    INGEST_FAILED,
+    INTERNAL_ERROR,
+    INVALID_PARAMS,
+    INVALID_REQUEST,
+    METHOD_NOT_FOUND,
+    ONTOLOGY_NOT_FOUND,
+    PARSE_ERROR,
+    UPP_CONTEXTUALIZE,
+    UPP_DELETE,
+    UPP_EVENTS,
+    UPP_EXPORT,
+    UPP_GET_TASKS,
+    UPP_IMPORT,
+    UPP_INFO,
+    UPP_INGEST,
+    UPP_LABELS,
+    UPP_RETRIEVE,
+    USER_NOT_FOUND,
+    ContextualizeRequest,
+    ContextualizeResponse,
+    DeleteRequest,
+    DeleteResponse,
+    EventsRequest,
+    EventsResponse,
+    ExportRequest,
+    ExportResponse,
+    GetTasksRequest,
+    GetTasksResponse,
+    ImportRequest,
+    ImportResponse,
+    InfoRequest,
+    InfoResponse,
+    IngestRequest,
+    IngestResponse,
+    JsonRpcError,
+    JsonRpcNotification,
+    JsonRpcRequest,
+    JsonRpcResponse,
+    LabelsRequest,
+    LabelsResponse,
+    RetrieveRequest,
+    RetrieveResponse,
+    UppError,
+    decode_request,
+    decode_response,
+    encode_request,
+    encode_response,
+)
+
+__all__ = [
+    "__version__",
+    # Enumerations
+    "Cardinality",
+    "Durability",
+    "EventStatus",
+    "SensitivityTier",
+    "SourceType",
+    "TaskStatus",
+    # Core entities
+    "ContextualizeResult",
+    "Event",
+    "LabelDefinition",
+    "StoredEvent",
+    "TaskResult",
+    # Backend protocols
+    "OntologyBackend",
+    "RetrieverBackend",
+    "IngestBackend",
+    # RPC message types
+    "JsonRpcError",
+    "JsonRpcNotification",
+    "JsonRpcRequest",
+    "JsonRpcResponse",
+    # RPC operation models
+    "ContextualizeRequest",
+    "ContextualizeResponse",
+    "DeleteRequest",
+    "DeleteResponse",
+    "EventsRequest",
+    "EventsResponse",
+    "ExportRequest",
+    "ExportResponse",
+    "GetTasksRequest",
+    "GetTasksResponse",
+    "ImportRequest",
+    "ImportResponse",
+    "InfoRequest",
+    "InfoResponse",
+    "LabelsRequest",
+    "LabelsResponse",
+    "IngestRequest",
+    "IngestResponse",
+    "RetrieveRequest",
+    "RetrieveResponse",
+    # RPC method constants
+    "ALL_METHODS",
+    "UPP_CONTEXTUALIZE",
+    "UPP_DELETE",
+    "UPP_EVENTS",
+    "UPP_EXPORT",
+    "UPP_GET_TASKS",
+    "UPP_IMPORT",
+    "UPP_INFO",
+    "UPP_LABELS",
+    "UPP_INGEST",
+    "UPP_RETRIEVE",
+    # RPC error codes
+    "EXTRACTION_FAILED",
+    "INTERNAL_ERROR",
+    "INVALID_PARAMS",
+    "INVALID_REQUEST",
+    "METHOD_NOT_FOUND",
+    "ONTOLOGY_NOT_FOUND",
+    "INGEST_FAILED",
+    "PARSE_ERROR",
+    "USER_NOT_FOUND",
+    # Exception
+    "UppError",
+    # Codec
+    "decode_request",
+    "decode_response",
+    "encode_request",
+    "encode_response",
+    # Client
+    "UPPClient",
+    # Ontology
+    "OntologyUserV1",
+]

upp/backends/__init__.py

@@ -0,0 +1,23 @@
+"""UPP Backend Interfaces.
+
+This package defines the abstract backend protocols for the Universal
+Personalization Protocol. Each backend is a :class:`typing.Protocol`
+decorated with :func:`typing.runtime_checkable`.
+
+Backend Protocols:
+    IngestBackend — Persists and retrieves stored events.
+    RetrieverBackend — Intelligent retrieval of relevant context.
+    OntologyBackend — Label definitions and server metadata.
+"""
+
+from __future__ import annotations
+
+from upp.backends.ingest import IngestBackend
+from upp.backends.ontology import OntologyBackend
+from upp.backends.retriever import RetrieverBackend
+
+__all__ = [
+    "OntologyBackend",
+    "RetrieverBackend",
+    "IngestBackend",
+]

upp/backends/ingest.py

@@ -0,0 +1,122 @@
+"""UPP Ingest Backend Protocol.
+
+Defines the :class:`IngestBackend` protocol for extracting and persisting
+personal events from free text. The backend manages the full lifecycle of
+events following an immutable event-sourcing pattern.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from upp.models.events import Event, StoredEvent, TaskResult
+
+__all__ = [
+    "IngestBackend",
+]
+
+
+@runtime_checkable
+class IngestBackend(Protocol):
+    """Protocol for pluggable event ingestion.
+
+    An ingest backend receives free text, extracts relevant personal
+    facts, classifies them with ontology labels, handles supersession
+    for singular-cardinality labels, and persists the resulting events.
+
+    Implementations may use any extraction strategy (LLM, NLP, rules)
+    and any backing storage (in-memory, SQLite, PostgreSQL, Redis, etc.).
+    """
+
+    async def ingest(
+        self,
+        entity_key: str,
+        text: str,
+    ) -> list[StoredEvent]:
+        """Extract and persist events from free text.
+
+        The backend MUST:
+
+        1. Analyze the input text and extract relevant personal facts.
+        2. Classify each fact with one or more ontology labels.
+        3. Assign a UUID v4 ``id`` and a UTC ``created_at`` timestamp.
+        4. For singular-cardinality labels, mark existing valid events
+           with the same label as superseded.
+
+        Args:
+            entity_key: Unique identifier of the user.
+            text: Free text from which to extract events.
+
+        Returns:
+            A list of :class:`StoredEvent` objects with server-assigned metadata.
+        """
+        ...
+
+    async def delete_events(
+        self,
+        entity_key: str,
+        event_ids: list[str] | None = None,
+    ) -> int:
+        """Delete events for a user.
+
+        If ``event_ids`` is ``None``, deletes ALL events for the user
+        (right to erasure). Otherwise, deletes only the specified events.
+
+        Args:
+            entity_key: Unique identifier of the user.
+            event_ids: Optional list of specific event IDs to delete.
+                If ``None``, all events for the user are deleted.
+
+        Returns:
+            Number of events deleted.
+        """
+        ...
+
+    async def import_events(
+        self,
+        entity_key: str,
+        events: list[Event],
+    ) -> list[StoredEvent]:
+        """Import events for a user.
+
+        Persists events that were previously exported from another
+        UPP-compatible server.
+
+        Args:
+            entity_key: Unique identifier of the user.
+            events: Events to import.
+
+        Returns:
+            A list of :class:`StoredEvent` objects with server-assigned metadata.
+        """
+        ...
+
+    async def schedule_ingest(
+        self,
+        entity_key: str,
+        text: str,
+    ) -> str:
+        """Schedule an ingest operation to run in the background.
+
+        Args:
+            entity_key: Unique identifier of the user.
+            text: Free text from which to extract events.
+
+        Returns:
+            A task_id that can be used with get_tasks to check status.
+        """
+        ...
+
+    async def get_tasks(
+        self,
+        task_ids: list[str],
+    ) -> list[TaskResult]:
+        """Check the status of background tasks.
+
+        Args:
+            task_ids: One or more task IDs to check.
+
+        Returns:
+            A list of TaskResult objects with status and results.
+        """
+        ...

upp/backends/ontology.py

@@ -0,0 +1,41 @@
+"""UPP Ontology Backend Protocol.
+
+Defines the :class:`OntologyBackend` protocol for accessing ontology
+metadata, label definitions, and server information.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from upp.models.labels import LabelDefinition
+
+__all__ = [
+    "OntologyBackend",
+]
+
+
+@runtime_checkable
+class OntologyBackend(Protocol):
+    """Protocol for pluggable ontology backends.
+
+    An ontology backend provides access to label definitions, the
+    ontology identifier, and server information for the ``upp/info``
+    operation.
+    """
+
+    def get_labels(self) -> list[LabelDefinition]:
+        """Return all label definitions for the ontology.
+
+        Returns:
+            A list of :class:`LabelDefinition` objects.
+        """
+        ...
+
+    def get_version(self) -> str:
+        """Return the ontology identifier for this server instance.
+
+        Returns:
+            The ontology identifier string (e.g., ``"user/v1"``).
+        """
+        ...

upp/backends/retriever.py

@@ -0,0 +1,79 @@
+"""UPP Retriever Backend Protocol.
+
+Defines the :class:`RetrieverBackend` protocol for retrieving relevant
+structured context given a free-text query. The retriever is responsible
+for scoring, ranking, and selecting the most relevant events.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from upp.models.events import StoredEvent
+
+__all__ = [
+    "RetrieverBackend",
+]
+
+
+@runtime_checkable
+class RetrieverBackend(Protocol):
+    """Protocol for pluggable intelligent retrieval.
+
+    A retriever takes a user key and a free-text query, then returns
+    the most relevant events ranked by the implementation's scoring
+    algorithm.
+    """
+
+    async def retrieve(
+        self,
+        entity_key: str,
+        query: str,
+    ) -> list[StoredEvent]:
+        """Retrieve relevant events for a user given a query.
+
+        The retriever MUST interpret the query and return events
+        ranked by relevance.
+
+        Args:
+            entity_key: Unique identifier of the user.
+            query: Free-text query describing what information is needed.
+
+        Returns:
+            A list of :class:`StoredEvent` objects ranked by relevance.
+        """
+        ...
+
+    async def get_events(
+        self,
+        entity_key: str,
+    ) -> list[StoredEvent]:
+        """Get all stored events for a user.
+
+        Returns events of all statuses for transparency.
+
+        Args:
+            entity_key: Unique identifier of the user.
+
+        Returns:
+            All stored events for the user.
+        """
+        ...
+
+    async def export_events(
+        self,
+        entity_key: str,
+    ) -> list[StoredEvent]:
+        """Export all events for a user.
+
+        Returns events of all statuses (valid, staged, superseded) to
+        provide a complete audit trail suitable for migration between
+        vendors.
+
+        Args:
+            entity_key: Unique identifier of the user.
+
+        Returns:
+            All stored events for export.
+        """
+        ...

upp/client.py

@@ -0,0 +1,148 @@
+"""UPP Client — High-Level Protocol Client.
+
+Provides :class:`UPPClient`, the primary entry point for the UPP Python
+reference implementation. The client accepts pluggable backends and
+exposes methods for all ten UPP operations.
+
+"""
+
+from __future__ import annotations
+
+import logging
+from importlib.metadata import version as _pkg_version
+from typing import Any
+
+from upp.backends.ingest import IngestBackend
+from upp.backends.ontology import OntologyBackend
+from upp.backends.retriever import RetrieverBackend
+from upp.models.client import UPPClientProtocol
+from upp.models.events import ContextualizeResult, Event, StoredEvent, TaskResult
+from upp.models.labels import LabelDefinition
+
+__all__ = [
+    "UPPClient",
+]
+
+logger = logging.getLogger(__name__)
+
+
+class UPPClient(UPPClientProtocol):
+    """High-level UPP protocol client.
+
+    Orchestrates backend interfaces to implement all ten UPP
+    operations. The client is backend-agnostic — any combination of
+    backends satisfying the respective Protocol interfaces can be
+    injected.
+    """
+
+    def __init__(
+        self,
+        *,
+        ingest: IngestBackend,
+        retriever: RetrieverBackend,
+        ontology: OntologyBackend,
+    ) -> None:
+        """Initialize the UPP client with pluggable backends.
+
+        Args:
+            ingest: Backend for event ingestion.
+            retriever: Backend for intelligent retrieval.
+            ontology: Backend for ontology access and server metadata.
+        """
+        self._ingest = ingest
+        self._retriever = retriever
+        self._ontology = ontology
+
+    # ── Core (write) ─────────────────────────────────────────────────
+
+    async def ingest(
+        self,
+        entity_key: str,
+        text: str,
+    ) -> list[StoredEvent]:
+        """upp/ingest — Extract and ingest events from text."""
+        logger.info(f"Ingesting text for entity '{entity_key}'")
+        return await self._ingest.ingest(entity_key, text)
+
+    async def delete_events(
+        self,
+        entity_key: str,
+        event_ids: list[str] | None = None,
+    ) -> int:
+        """upp/delete_events — Delete events (GDPR/CCPA compliance)."""
+        logger.info(f"Deleting events for entity '{entity_key}' with event_ids={event_ids}")
+        return await self._ingest.delete_events(entity_key, event_ids)
+
+    # ── Core (read) ──────────────────────────────────────────────────
+
+    async def retrieve(
+        self,
+        entity_key: str,
+        query: str,
+    ) -> list[StoredEvent]:
+        """upp/retrieve — Intelligent search for relevant events."""
+        logger.info(f"Retrieving events for entity '{entity_key}'")
+        return await self._retriever.retrieve(entity_key, query)
+
+    async def get_events(
+        self,
+        entity_key: str,
+    ) -> list[StoredEvent]:
+        """upp/get_events — Raw listing of stored events."""
+        logger.info(f"Getting events for entity '{entity_key}'")
+        return await self._retriever.get_events(entity_key)
+
+    async def contextualize(
+        self,
+        entity_key: str,
+        text: str,
+    ) -> ContextualizeResult:
+        """upp/contextualize — Retrieve context and ingest in the background."""
+        logger.info(f"Contextualizing text for entity '{entity_key}'")
+        # Retrieve existing relevant events synchronously
+        events = await self._retriever.retrieve(entity_key, text)
+        # Schedule background ingest and get task reference
+        task_id = await self._ingest.schedule_ingest(entity_key, text)
+        return ContextualizeResult(events=events, task_id=task_id)
+
+    # ── Discovery ────────────────────────────────────────────────────
+
+    def info(self) -> dict[str, Any]:
+        """upp/info — Server metadata and capabilities."""
+        logger.info("Fetching server info")
+        return {
+            "protocol_version": _pkg_version("upp-python"),
+            "ontology": self._ontology.get_version(),
+        }
+
+    def get_labels(self) -> list[LabelDefinition]:
+        """upp/get_labels — Available labels in the ontology."""
+        logger.info("Fetching label definitions from ontology")
+        return self._ontology.get_labels()
+
+    async def get_tasks(
+        self,
+        task_ids: list[str],
+    ) -> list[TaskResult]:
+        """upp/get_tasks — Check status of background tasks."""
+        logger.info(f"Getting task status for {len(task_ids)} task(s)")
+        return await self._ingest.get_tasks(task_ids)
+
+    # ── Portability ──────────────────────────────────────────────────
+
+    async def export_events(
+        self,
+        entity_key: str,
+    ) -> list[StoredEvent]:
+        """upp/export_events — Export events for migration."""
+        logger.info(f"Exporting events for entity '{entity_key}'")
+        return await self._retriever.export_events(entity_key)
+
+    async def import_events(
+        self,
+        entity_key: str,
+        events: list[Event],
+    ) -> list[StoredEvent]:
+        """upp/import_events — Import events from another server."""
+        logger.info(f"Importing {len(events)} events for entity '{entity_key}'")
+        return await self._ingest.import_events(entity_key, events)

upp/models/__init__.py

@@ -0,0 +1,38 @@
+"""UPP Data Models.
+
+This package contains all data model definitions for the Universal
+Personalization Protocol (UPP) Python reference implementation.
+
+Enumerations:
+    EventStatus, SourceType, SensitivityTier, Cardinality, Durability
+
+Core Entities:
+    Event, StoredEvent, LabelDefinition
+"""
+
+from upp.models.enums import (
+    Cardinality,
+    Durability,
+    EventStatus,
+    SensitivityTier,
+    SourceType,
+    TaskStatus,
+)
+from upp.models.events import ContextualizeResult, Event, StoredEvent, TaskResult
+from upp.models.labels import LabelDefinition
+
+__all__ = [
+    # Enumerations
+    "Cardinality",
+    "Durability",
+    "EventStatus",
+    "SensitivityTier",
+    "SourceType",
+    "TaskStatus",
+    # Core entities
+    "ContextualizeResult",
+    "Event",
+    "LabelDefinition",
+    "StoredEvent",
+    "TaskResult",
+]