upp-python 0.1.0__tar.gz

upp_python-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+*.egg
+.coverage
+.coverage.*
+coverage/
+htmlcov/
+
+# Environment
+.env
+.env.local
+.env.*
+
+# Native extensions
+*.so
+*.pyd
+
+# TypeScript / Node
+node_modules/
+*.js
+*.d.ts
+*.js.map
+!jest.config.js
+!vitest.config.ts
+!eslint.config.js
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

upp_python-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: upp-python
+Version: 0.1.0
+Summary: Python reference implementation of the Universal Personalization Protocol (UPP) data models
+Project-URL: Homepage, https://github.com/Contextually-AI/upp
+Project-URL: Documentation, https://github.com/Contextually-AI/upp/tree/main/spec
+Project-URL: Repository, https://github.com/Contextually-AI/upp
+Project-URL: Issues, https://github.com/Contextually-AI/upp/issues
+Project-URL: Changelog, https://github.com/Contextually-AI/upp/blob/main/CHANGELOG.md
+Author: UPP Protocol Authors
+License-Expression: MIT
+Keywords: json-rpc,personalization,protocol,pydantic,user-profile
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# UPP Python — Reference Implementation
+
+Python reference implementation of the [Universal Personalization Protocol (UPP)](../../spec/01-overview.md) data models, backends, and client.
+
+## Installation
+
+```bash
+pip install upp-python
+```
+
+### Development
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from upp import Event, StoredEvent, SourceType, EventStatus
+from upp import LabelDefinition, OntologyUserV1, UPPClient
+
+# Create an event (pre-storage)
+event = Event(
+    value="I work as a senior software engineer at Anthropic",
+    labels=["what_occupation"],
+    confidence=0.95,
+    source_type=SourceType.USER_STATED,
+)
+
+# Use with a client (requires backend implementations)
+import asyncio
+
+async def demo():
+    client = UPPClient(
+        ingest=my_ingest_backend,
+        retriever=my_retriever_backend,
+        ontology=OntologyUserV1(),
+    )
+    stored = await client.ingest("user-123", [event])
+    print(f"Stored: {stored[0].value} (id={stored[0].id})")
+
+    # Retrieve events
+    events = await client.get_events("user-123")
+    print(f"Total events: {len(events)}")
+
+asyncio.run(demo())
+```
+
+## Package Structure
+
+```
+src/upp/
+├── __init__.py              # Top-level exports
+├── client.py                # UPPClient — high-level protocol client
+├── models/
+│   ├── __init__.py           # Model re-exports
+│   ├── client.py             # UPPClientProtocol
+│   ├── enums.py              # EventStatus, SourceType, SensitivityTier, Cardinality, Durability
+│   ├── events.py             # Event, StoredEvent
+│   └── labels.py             # LabelDefinition
+├── backends/
+│   ├── __init__.py           # Backend re-exports
+│   ├── ingest.py             # IngestBackend protocol
+│   ├── retriever.py          # RetrieverBackend protocol
+│   └── ontology.py           # OntologyBackend protocol
+├── ontologies/
+│   ├── __init__.py
+│   └── user_v1.py            # OntologyUserV1 — loads ontologies/user/v1.json
+└── rpc/
+    ├── __init__.py           # RPC re-exports
+    ├── methods.py            # UPP_INGEST, UPP_RETRIEVE, etc.
+    ├── errors.py             # Error codes and UppError
+    ├── messages.py           # JSON-RPC types + operation request/response models
+    └── codec.py              # JSON-RPC encode/decode
+```
+
+## Protocol Operations
+
+The UPP protocol defines 8 operations:
+
+| Operation | Type | Description |
+|---|---|---|
+| `upp/ingest` | Core (write) | Extract and ingest events from text |
+| `upp/retrieve` | Core (read) | Intelligent retrieval of relevant events |
+| `upp/events` | Core (read) | List all stored events |
+| `upp/delete` | Core (write) | Delete events (GDPR compliance) |
+| `upp/info` | Discovery | Server metadata |
+| `upp/labels` | Discovery | Label definitions from an ontology |
+| `upp/export` | Portability | Export events for migration |
+| `upp/import` | Portability | Import events from another server |
+
+## Requirements
+
+- Python >= 3.11
+- Pydantic >= 2.0.0
+
+## Testing
+
+```bash
+pytest tests/ -v
+```
+
+## License
+
+MIT — See [LICENSE](../../LICENSE) for details.

upp_python-0.1.0/README.md

@@ -0,0 +1,106 @@
+# UPP Python — Reference Implementation
+
+Python reference implementation of the [Universal Personalization Protocol (UPP)](../../spec/01-overview.md) data models, backends, and client.
+
+## Installation
+
+```bash
+pip install upp-python
+```
+
+### Development
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from upp import Event, StoredEvent, SourceType, EventStatus
+from upp import LabelDefinition, OntologyUserV1, UPPClient
+
+# Create an event (pre-storage)
+event = Event(
+    value="I work as a senior software engineer at Anthropic",
+    labels=["what_occupation"],
+    confidence=0.95,
+    source_type=SourceType.USER_STATED,
+)
+
+# Use with a client (requires backend implementations)
+import asyncio
+
+async def demo():
+    client = UPPClient(
+        ingest=my_ingest_backend,
+        retriever=my_retriever_backend,
+        ontology=OntologyUserV1(),
+    )
+    stored = await client.ingest("user-123", [event])
+    print(f"Stored: {stored[0].value} (id={stored[0].id})")
+
+    # Retrieve events
+    events = await client.get_events("user-123")
+    print(f"Total events: {len(events)}")
+
+asyncio.run(demo())
+```
+
+## Package Structure
+
+```
+src/upp/
+├── __init__.py              # Top-level exports
+├── client.py                # UPPClient — high-level protocol client
+├── models/
+│   ├── __init__.py           # Model re-exports
+│   ├── client.py             # UPPClientProtocol
+│   ├── enums.py              # EventStatus, SourceType, SensitivityTier, Cardinality, Durability
+│   ├── events.py             # Event, StoredEvent
+│   └── labels.py             # LabelDefinition
+├── backends/
+│   ├── __init__.py           # Backend re-exports
+│   ├── ingest.py             # IngestBackend protocol
+│   ├── retriever.py          # RetrieverBackend protocol
+│   └── ontology.py           # OntologyBackend protocol
+├── ontologies/
+│   ├── __init__.py
+│   └── user_v1.py            # OntologyUserV1 — loads ontologies/user/v1.json
+└── rpc/
+    ├── __init__.py           # RPC re-exports
+    ├── methods.py            # UPP_INGEST, UPP_RETRIEVE, etc.
+    ├── errors.py             # Error codes and UppError
+    ├── messages.py           # JSON-RPC types + operation request/response models
+    └── codec.py              # JSON-RPC encode/decode
+```
+
+## Protocol Operations
+
+The UPP protocol defines 8 operations:
+
+| Operation | Type | Description |
+|---|---|---|
+| `upp/ingest` | Core (write) | Extract and ingest events from text |
+| `upp/retrieve` | Core (read) | Intelligent retrieval of relevant events |
+| `upp/events` | Core (read) | List all stored events |
+| `upp/delete` | Core (write) | Delete events (GDPR compliance) |
+| `upp/info` | Discovery | Server metadata |
+| `upp/labels` | Discovery | Label definitions from an ontology |
+| `upp/export` | Portability | Export events for migration |
+| `upp/import` | Portability | Import events from another server |
+
+## Requirements
+
+- Python >= 3.11
+- Pydantic >= 2.0.0
+
+## Testing
+
+```bash
+pytest tests/ -v
+```
+
+## License
+
+MIT — See [LICENSE](../../LICENSE) for details.

upp_python-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "upp-python"
+version = "0.1.0"
+description = "Python reference implementation of the Universal Personalization Protocol (UPP) data models"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "UPP Protocol Authors" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+keywords = ["personalization", "protocol", "user-profile", "pydantic", "json-rpc"]
+dependencies = [
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov",
+    "ruff",
+    "mypy",
+]
+
+[project.urls]
+Homepage = "https://github.com/Contextually-AI/upp"
+Documentation = "https://github.com/Contextually-AI/upp/tree/main/spec"
+Repository = "https://github.com/Contextually-AI/upp"
+Issues = "https://github.com/Contextually-AI/upp/issues"
+Changelog = "https://github.com/Contextually-AI/upp/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/upp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 160
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+plugins = ["pydantic.mypy"]

upp_python-0.1.0/src/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_python-0.1.0/src/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_python-0.1.0/src/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.
+        """
+        ...