upp-python 0.1.0__py3-none-any.whl

upp/models/client.py

@@ -0,0 +1,113 @@
+"""UPP Client Protocol.
+
+Defines :class:`UPPClientProtocol`, the top-level interface that any
+UPP-compliant client must satisfy.  It declares all ten operations
+specified by the Universal Personalization Protocol.
+
+Design note — why this Protocol does NOT inherit from the backend protocols
+(``IngestBackend``, ``RetrieverBackend``, ``OntologyBackend``):
+
+    Backends are *infrastructure* components — each one owns a single
+    responsibility (persistence, retrieval, ontology metadata).  A client
+    is an *orchestrator*: it delegates to backends but lives at a higher
+    abstraction level.  Inheriting from the backend protocols would
+    conflate these two roles and allow a client instance to be passed
+    where a backend is expected, creating a misleading extra layer of
+    indirection.
+
+    Instead, ``UPPClientProtocol`` declares the same method signatures
+    independently.  This keeps the type hierarchy honest — a client *is
+    not* a backend — while still guaranteeing that every compliant client
+    exposes the full set of UPP operations.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from upp.models.events import ContextualizeResult, Event, StoredEvent, TaskResult
+from upp.models.labels import LabelDefinition
+
+
+@runtime_checkable
+class UPPClientProtocol(Protocol):
+    """Top-level protocol for a UPP-compliant client.
+
+    Any implementation that satisfies this protocol exposes the ten
+    operations defined by the Universal Personalization Protocol:
+
+    Core (write):
+        1. ingest         — Persist extracted events.
+        2. delete_events  — Delete events (GDPR / CCPA compliance).
+
+    Core (read + write):
+        3. retrieve       — Intelligent, query-driven event retrieval.
+        4. get_events     — Raw listing of all stored events.
+        5. contextualize  — Retrieve context and ingest in the background.
+
+    Discovery:
+        6. info           — Server metadata and capabilities.
+        7. get_labels     — Available labels in the ontology.
+        8. get_tasks      — Check status of background tasks.
+
+    Portability:
+        9. export_events  — Export events for migration.
+       10. import_events  — Import events from another server.
+    """
+
+    # ── Core (write) ─────────────────────────────────────────────────
+
+    async def ingest(
+        self,
+        entity_key: str,
+        text: str,
+    ) -> list[StoredEvent]: ...
+
+    async def delete_events(
+        self,
+        entity_key: str,
+        event_ids: list[str] | None = None,
+    ) -> int: ...
+
+    # ── Core (read) ──────────────────────────────────────────────────
+
+    async def retrieve(
+        self,
+        entity_key: str,
+        query: str,
+    ) -> list[StoredEvent]: ...
+
+    async def get_events(
+        self,
+        entity_key: str,
+    ) -> list[StoredEvent]: ...
+
+    async def contextualize(
+        self,
+        entity_key: str,
+        text: str,
+    ) -> ContextualizeResult: ...
+
+    # ── Discovery ────────────────────────────────────────────────────
+
+    def info(self) -> dict[str, Any]: ...
+
+    def get_labels(self) -> list[LabelDefinition]: ...
+
+    async def get_tasks(
+        self,
+        task_ids: list[str],
+    ) -> list[TaskResult]: ...
+
+    # ── Portability ──────────────────────────────────────────────────
+
+    async def export_events(
+        self,
+        entity_key: str,
+    ) -> list[StoredEvent]: ...
+
+    async def import_events(
+        self,
+        entity_key: str,
+        events: list[Event],
+    ) -> list[StoredEvent]: ...

upp/models/enums.py

@@ -0,0 +1,124 @@
+"""UPP Enumerations.
+
+Defines the enumeration types used throughout the Universal Personalization
+Protocol. All enums inherit from ``str`` and ``enum.Enum`` so they
+serialize naturally to their string values in JSON.
+
+Enumerations:
+    EventStatus: Lifecycle state of a stored event.
+    SourceType: Provenance classification of an extracted fact.
+    SensitivityTier: Privacy classification for ontology labels.
+    Cardinality: Whether a label accepts one or many values.
+    Durability: Expected lifespan of a fact.
+"""
+
+from __future__ import annotations
+
+import enum
+
+__all__ = [
+    "Cardinality",
+    "Durability",
+    "EventStatus",
+    "SensitivityTier",
+    "SourceType",
+    "TaskStatus",
+]
+
+
+class EventStatus(enum.StrEnum):
+    """Lifecycle state of a stored event.
+
+    Events follow an immutable event-sourcing pattern:
+
+    - ``VALID`` — Active and authoritative.
+    - ``STAGED`` — Low confidence, pending reinforcement.
+    - ``SUPERSEDED`` — Replaced by a newer event, retained for audit.
+    """
+
+    VALID = "valid"
+    """Current, retrievable event."""
+
+    STAGED = "staged"
+    """Low-confidence event awaiting reinforcement."""
+
+    SUPERSEDED = "superseded"
+    """Replaced by a newer event. Retained for audit trail."""
+
+
+class SourceType(enum.StrEnum):
+    """Classifies how a fact was obtained.
+
+    Source types indicate the provenance of an extracted fact.
+    """
+
+    USER_STATED = "user_stated"
+    """The user explicitly stated this fact."""
+
+    AGENT_OBSERVED = "agent_observed"
+    """The agent observed or derived this fact from conversation context."""
+
+    INFERRED = "inferred"
+    """The system inferred this fact from indirect signals."""
+
+
+class SensitivityTier(enum.StrEnum):
+    """Privacy classification for ontology labels.
+
+    Ordered from least to most sensitive:
+    ``TIER_PUBLIC < TIER_WORK < TIER_PERSONAL < TIER_SENSITIVE < TIER_INTERNAL``
+    """
+
+    TIER_PUBLIC = "tier_public"
+    """Safe to share broadly."""
+
+    TIER_WORK = "tier_work"
+    """Professional context."""
+
+    TIER_PERSONAL = "tier_personal"
+    """Personal but non-sensitive."""
+
+    TIER_SENSITIVE = "tier_sensitive"
+    """Sensitive personal data."""
+
+    TIER_INTERNAL = "tier_internal"
+    """Never shared externally."""
+
+
+class Cardinality(enum.StrEnum):
+    """Defines whether a label accepts one or many concurrent values.
+
+    Cardinality determines supersession behavior: singular labels cause
+    new events to supersede old ones, while plural labels accumulate.
+    """
+
+    SINGULAR = "singular"
+    """Only one value at a time. New values supersede old ones."""
+
+    PLURAL = "plural"
+    """Multiple values coexist. New values are added alongside existing ones."""
+
+
+class Durability(enum.StrEnum):
+    """Indicates how long a fact is expected to remain valid.
+
+    Ordering (longest to shortest): ``PERMANENT > TRANSIENT > EPHEMERAL``
+    """
+
+    PERMANENT = "permanent"
+    """Unlikely to change over a person's lifetime."""
+
+    TRANSIENT = "transient"
+    """Changes over months or years."""
+
+    EPHEMERAL = "ephemeral"
+    """Changes frequently — days or weeks."""
+
+
+class TaskStatus(enum.StrEnum):
+    """Status of a background task."""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"

upp/models/events.py

@@ -0,0 +1,124 @@
+"""UPP Event Models.
+
+Defines the core event entities in the Universal Personalization Protocol:
+
+- :class:`Event` — The atomic unit of extracted personal information.
+- :class:`StoredEvent` — An Event after persistence, enriched with server metadata.
+
+Both models are immutable (frozen). Events follow an event-sourcing pattern
+where they are never modified after creation.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from upp.models.enums import EventStatus, SourceType, TaskStatus
+
+__all__ = [
+    "ContextualizeResult",
+    "Event",
+    "StoredEvent",
+    "TaskResult",
+]
+
+
+class Event(BaseModel):
+    """An atomic unit of extracted personal information.
+
+    Events are produced by the extraction pipeline and consumed by the
+    store layer. They are immutable — once created, they are never modified.
+
+    Attributes:
+        value: The extracted fact as natural-language text.
+        labels: One or more ontology label keys this fact maps to.
+        confidence: Extraction confidence score in [0.0, 1.0].
+        source_type: Provenance classification of the fact.
+    """
+
+    model_config = {"frozen": True}
+
+    value: str = Field(
+        min_length=1,
+        description="The extracted fact as natural-language text.",
+    )
+    labels: list[str] = Field(
+        min_length=1,
+        description="One or more ontology label keys this fact maps to.",
+    )
+    confidence: float = Field(
+        ge=0.0,
+        le=1.0,
+        description="Extraction confidence score in [0.0, 1.0].",
+    )
+    source_type: SourceType = Field(
+        description="Provenance classification: user_stated, agent_observed, or inferred.",
+    )
+    valid_from: str | None = Field(
+        default=None,
+        description="ISO-8601 start of the fact's validity window.",
+    )
+    valid_until: str | None = Field(
+        default=None,
+        description="ISO-8601 end of the fact's validity window.",
+    )
+
+
+class StoredEvent(Event):
+    """A persisted event with server-assigned metadata.
+
+    Extends :class:`Event` with fields assigned by the server upon
+    persistence: unique ID, user key, lifecycle status, creation
+    timestamp, and optional supersession reference.
+
+    Like ``Event``, ``StoredEvent`` is immutable.
+
+    Attributes:
+        id: Unique event identifier (UUID v4).
+        entity_key: Unique identifier of the user who owns this event.
+        status: Lifecycle status (valid, staged, superseded).
+        created_at: Timestamp of creation.
+        superseded_by: ID of the event that replaced this one.
+    """
+
+    id: str = Field(
+        description="Unique event identifier (UUID v4).",
+    )
+    entity_key: str = Field(
+        description="Unique identifier of the user who owns this event.",
+    )
+    status: EventStatus = Field(
+        default=EventStatus.VALID,
+        description="Lifecycle status: valid, staged, or superseded.",
+    )
+    created_at: datetime = Field(
+        description="Timestamp of creation (UTC).",
+    )
+    superseded_by: str | None = Field(
+        default=None,
+        description="ID of the event that replaced this one (if superseded).",
+    )
+
+
+class TaskResult(BaseModel):
+    """Status and result of a background task."""
+
+    model_config = {"frozen": True}
+
+    task_id: str = Field(description="The task identifier.")
+    status: TaskStatus = Field(description="Current task status.")
+    result: list[StoredEvent] | None = Field(default=None, description="Resulting events when completed.")
+    error: str | None = Field(default=None, description="Error message when failed.")
+    created_at: datetime = Field(description="When the task was created (UTC).")
+    completed_at: datetime | None = Field(default=None, description="When the task finished (UTC).")
+
+
+class ContextualizeResult(BaseModel):
+    """Result of a contextualize operation."""
+
+    model_config = {"frozen": True}
+
+    events: list[StoredEvent] = Field(description="Relevant existing events.")
+    task_id: str = Field(description="Reference to the background ingest task.")

upp/models/labels.py

@@ -0,0 +1,71 @@
+"""UPP Label Definition Model.
+
+Defines the :class:`LabelDefinition` model — the fundamental unit of the
+UPP ontology taxonomy. Labels categorize personal facts using the 5W+H
+framework (Who, What, Where, When, Why, How) plus Preferences, Relationships,
+and Meta categories.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from upp.models.enums import Cardinality, Durability, SensitivityTier
+
+__all__ = [
+    "LabelDefinition",
+]
+
+
+class LabelDefinition(BaseModel):
+    """Schema definition for a single ontology label.
+
+    A ``LabelDefinition`` describes a category of personal fact in the
+    UPP taxonomy, including its privacy sensitivity, cardinality
+    (singular vs. plural), and expected durability.
+
+    Attributes:
+        name: Machine-readable label key (e.g., ``"who_name"``).
+        display_name: Human-readable name (e.g., ``"Name"``).
+        description: Concise description of what this label captures.
+        category: Top-level grouping (WHO, WHAT, WHERE, WHEN, WHY, HOW, PREF, REL, META).
+        sensitivity: Privacy sensitivity tier.
+        cardinality: Whether the label accepts one or many values.
+        durability: Expected lifespan of facts under this label.
+        examples: Optional example values to guide classification.
+    """
+
+    model_config = {"frozen": True}
+
+    name: str = Field(
+        description="Machine-readable label key (e.g., 'who_name').",
+    )
+    display_name: str = Field(
+        description="Human-readable name (e.g., 'Name').",
+    )
+    description: str = Field(
+        description="Concise description of what this label captures.",
+    )
+    classification_guidance: str | None = Field(
+        default=None,
+        description="Classification and disambiguation guidance for label extraction.",
+    )
+    category: str = Field(
+        description=("Top-level grouping defined by the ontology (e.g., user/v1 uses WHO, WHAT, WHERE, etc.)."),
+    )
+    sensitivity: SensitivityTier = Field(
+        description="Privacy sensitivity tier.",
+    )
+    cardinality: Cardinality = Field(
+        description="Whether the label accepts one value (singular) or many (plural).",
+    )
+    durability: Durability = Field(
+        description="Expected lifespan: permanent, transient, or ephemeral.",
+    )
+    examples: list[str] = Field(
+        description="Example values to guide classification and extraction.",
+    )
+    anti_examples: list[str] | None = Field(
+        default=None,
+        description="Counter-examples to clarify label boundaries and prevent misclassification.",
+    )

upp/ontologies/user_v1.py

@@ -0,0 +1,112 @@
+"""UPP user/v1 Ontology — Loader and Implementation.
+
+Provides :class:`OntologyUserV1`, an implementation of
+:class:`~upp.backends.ontology.OntologyBackend` backed by
+``ontologies/user/v1.json``.
+
+Usage::
+
+    from upp.ontologies.user_v1 import OntologyUserV1
+
+    ontology = OntologyUserV1()
+    all_labels = ontology.get_labels()
+    label = ontology.get_label_by_name("who_name")
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from upp.backends.ontology import OntologyBackend
+from upp.models.labels import LabelDefinition
+
+__all__ = ["OntologyUserV1"]
+
+#: Default path to the ontology file, resolved relative to this package.
+_DEFAULT_ONTOLOGY_PATH = Path(__file__).resolve().parent.parent.parent.parent.parent.parent / "ontologies" / "user" / "v1.json"
+
+# Module-level cache
+_cached_labels: list[LabelDefinition] | None = None
+_cached_labels_by_name: dict[str, LabelDefinition] | None = None
+
+
+def _load_labels(path: Path | None = None) -> list[LabelDefinition]:
+    """Load label definitions from the ontology JSON file.
+
+    Args:
+        path: Optional path to the ontology file.
+
+    Returns:
+        A list of :class:`LabelDefinition` objects.
+
+    Raises:
+        FileNotFoundError: If the ontology file does not exist.
+        json.JSONDecodeError: If the file contains invalid JSON.
+    """
+    ontology_path = path or _DEFAULT_ONTOLOGY_PATH
+
+    if not ontology_path.exists():
+        raise FileNotFoundError(
+            f"Default ontology file not found at {ontology_path}. Ensure the ontologies/user/v1.json file exists in the UPP repository root."
+        )
+
+    raw = json.loads(ontology_path.read_text(encoding="utf-8"))
+    raw_labels = raw.get("labels", [])
+
+    labels: list[LabelDefinition] = []
+
+    # Support both array format and dict format
+    if isinstance(raw_labels, list):
+        for label_data in raw_labels:
+            labels.append(LabelDefinition.model_validate(label_data))
+    elif isinstance(raw_labels, dict):
+        for key, label_data in raw_labels.items():
+            if "name" not in label_data:
+                label_data["name"] = key
+            labels.append(LabelDefinition.model_validate(label_data))
+
+    return labels
+
+
+def _ensure_loaded() -> tuple[list[LabelDefinition], dict[str, LabelDefinition]]:
+    """Ensure labels are loaded and cached.
+
+    Returns:
+        Tuple of (labels list, labels-by-name dict).
+    """
+    global _cached_labels, _cached_labels_by_name
+    if _cached_labels is None:
+        _cached_labels = _load_labels()
+        _cached_labels_by_name = {label.name: label for label in _cached_labels}
+    return _cached_labels, _cached_labels_by_name  # type: ignore[return-value]
+
+
+class OntologyUserV1(OntologyBackend):
+    """Ontology implementation backed by ontologies/user/v1.json."""
+
+    def get_labels(self) -> list[LabelDefinition]:
+        """Return all label definitions for the ontology."""
+        labels, _ = _ensure_loaded()
+        return list(labels)
+
+    def get_label_by_name(self, name: str) -> LabelDefinition:
+        """Get a label definition by its name.
+
+        Args:
+            name: The name of the label to retrieve.
+
+        Returns:
+            The :class:`LabelDefinition` with the specified name.
+
+        Raises:
+            KeyError: If no label with the given name exists.
+        """
+        _, labels_by_name = _ensure_loaded()
+        if name not in labels_by_name:
+            raise KeyError(f"Label with name '{name}' not found in ontology.")
+        return labels_by_name[name]
+
+    def get_version(self) -> str:
+        """Return the ontology identifier for this server instance."""
+        return "user/v1"

upp/rpc/__init__.py

@@ -0,0 +1,137 @@
+"""UPP JSON-RPC 2.0 Support.
+
+This package provides JSON-RPC 2.0 message types, codec functions,
+method constants, error definitions, and typed request/response models
+for all ten UPP operations.
+
+Message Types:
+    JsonRpcRequest, JsonRpcResponse, JsonRpcError, JsonRpcNotification
+
+Operation Models:
+    IngestRequest/Response, RetrieveRequest/Response, EventsRequest/Response,
+    DeleteRequest/Response, InfoRequest/Response, LabelsRequest/Response,
+    ExportRequest/Response, ImportRequest/Response
+
+Codec:
+    encode_request, decode_request, encode_response, decode_response
+
+Methods:
+    UPP_INGEST, UPP_RETRIEVE, UPP_EVENTS, UPP_DELETE,
+    UPP_INFO, UPP_LABELS, UPP_EXPORT, UPP_IMPORT, ALL_METHODS
+
+Errors:
+    UppError, standard and UPP-specific error code constants
+"""
+
+from __future__ import annotations
+
+from upp.rpc.codec import decode_request, decode_response, encode_request, encode_response
+from upp.rpc.errors import (
+    EXTRACTION_FAILED,
+    INGEST_FAILED,
+    INTERNAL_ERROR,
+    INVALID_PARAMS,
+    INVALID_REQUEST,
+    METHOD_NOT_FOUND,
+    ONTOLOGY_NOT_FOUND,
+    PARSE_ERROR,
+    USER_NOT_FOUND,
+    UppError,
+)
+from upp.rpc.messages import (
+    ContextualizeRequest,
+    ContextualizeResponse,
+    DeleteRequest,
+    DeleteResponse,
+    EventsRequest,
+    EventsResponse,
+    ExportRequest,
+    ExportResponse,
+    GetTasksRequest,
+    GetTasksResponse,
+    ImportRequest,
+    ImportResponse,
+    InfoRequest,
+    InfoResponse,
+    IngestRequest,
+    IngestResponse,
+    JsonRpcError,
+    JsonRpcNotification,
+    JsonRpcRequest,
+    JsonRpcResponse,
+    LabelsRequest,
+    LabelsResponse,
+    RetrieveRequest,
+    RetrieveResponse,
+)
+from upp.rpc.methods import (
+    ALL_METHODS,
+    UPP_CONTEXTUALIZE,
+    UPP_DELETE,
+    UPP_EVENTS,
+    UPP_EXPORT,
+    UPP_GET_TASKS,
+    UPP_IMPORT,
+    UPP_INFO,
+    UPP_INGEST,
+    UPP_LABELS,
+    UPP_RETRIEVE,
+)
+
+__all__ = [
+    # Message 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",
+    "IngestRequest",
+    "IngestResponse",
+    "RetrieveRequest",
+    "RetrieveResponse",
+    # Codec
+    "decode_request",
+    "decode_response",
+    "encode_request",
+    "encode_response",
+    # 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",
+    # 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",
+]