pi-durable-python 1.3.0__py3-none-any.whl

pi_durable/delta.py

@@ -0,0 +1,269 @@
+"""Chord-compatible JSON operation batches.
+
+Durable documents are materialized by replaying ordered operation batches. The tuple vocabulary
+is the one Chord Delta publishes:
+
+``["r", value]``
+    Replace the complete value.
+``["s", path, value]``
+    Set an object property or array element.
+``["d", path]``
+    Delete an object property or remove an array element.
+``["a", path, text]``
+    Append to a string.
+``["t", path, count]``
+    Remove ``count`` UTF-16 code units from a string's front.
+``["p", path, index, remove, items]``
+    Splice an array.
+``["m", path, permutation]``
+    Reorder an array in place: ``new[i] = old[permutation[i]]``.
+
+The applier is intentionally independent of the document tracker. Memory storage uses it to
+materialize persisted deltas; Session drafts emit the same tuples from their own overlay.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from typing import Any, TypeAlias, cast
+
+from .json import JsonValue, copy_json
+
+Op: TypeAlias = list[Any]
+"""One decoded operation tuple, represented as its JSON array."""
+
+RESERVED_SEGMENTS = frozenset({"__proto__", "constructor", "prototype"})
+
+MAX_DELTA_OPERATIONS = 4_096
+"""Beyond this many operations a batch folds into one root replacement, as Chord does."""
+
+OVERLAP_SCAN_LIMIT = 65_536
+"""Characters Chord's bounded overlap search examines; beyond it a string is written whole."""
+
+
+class UnsafePathError(Exception):
+    """An operation addresses an unsafe or malformed path segment."""
+
+    def __init__(self, segment: object) -> None:
+        super().__init__(f"unsafe path segment: {segment}")
+        self.segment = segment
+        self.name = "UnsafePathError"
+
+
+class PathError(Exception):
+    """An operation cannot resolve to a value of the shape it expects."""
+
+    def __init__(self, path: object) -> None:
+        super().__init__(f"unresolvable path: {path}")
+        self.path = path
+        self.name = "PathError"
+
+
+def _is_int(value: object) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def overlap_strings(before: str, after: str, limit: int = OVERLAP_SCAN_LIMIT) -> int:
+    """Longest suffix of ``before`` that is a prefix of ``after``, within ``limit`` characters.
+
+    Knuth–Morris–Pratt, so a large tail window costs one pass; Chord's delta writer uses the same
+    bounded search and falls back to writing the whole string when it finds no shared part.
+    """
+
+    if not before or not after or limit <= 0:
+        return 0
+    prefix = after[:limit]
+    combined = prefix + "\x00" + before
+    table = [0] * len(combined)
+    length = 0
+    for index in range(1, len(combined)):
+        while length > 0 and combined[index] != combined[length]:
+            length = table[length - 1]
+        if combined[index] == combined[length]:
+            length += 1
+        table[index] = length
+    return min(table[-1], len(prefix), len(before))
+
+
+def assert_safe_path(path: object) -> None:
+    """Reject segments that could reach the prototype chain or are not JSON path segments."""
+
+    if not isinstance(path, list):
+        raise TypeError("path is not an array")
+    for segment in path:
+        if isinstance(segment, str):
+            if segment in RESERVED_SEGMENTS:
+                raise UnsafePathError(segment)
+        elif not _is_int(segment) or segment < 0:
+            raise UnsafePathError(segment)
+
+
+def _assert_path_arg(value: object, *, non_empty: bool = False) -> None:
+    if not isinstance(value, list):
+        raise TypeError("path is not an array")
+    if non_empty and not value:
+        raise TypeError("path is empty")
+    assert_safe_path(value)
+
+
+def _assert_permutation(value: object) -> None:
+    if not isinstance(value, list):
+        raise TypeError("m permutation is not an array")
+    seen = [False] * len(value)
+    for index in value:
+        if not _is_int(index) or index < 0 or index >= len(value) or seen[index]:
+            raise TypeError("m permutation is not a bijection")
+        seen[index] = True
+
+
+def assert_valid_op(op: object) -> None:
+    """Validate one decoded operation tuple."""
+
+    if not isinstance(op, list) or not op:
+        raise TypeError("op is not a tuple")
+    verb = op[0]
+    if verb == "r":
+        if len(op) != 2:
+            raise TypeError("r arity")
+    elif verb == "s":
+        if len(op) != 3:
+            raise TypeError("s arity")
+        _assert_path_arg(op[1], non_empty=True)
+    elif verb == "d":
+        if len(op) != 2:
+            raise TypeError("d arity")
+        _assert_path_arg(op[1], non_empty=True)
+    elif verb == "a":
+        if len(op) != 3 or not isinstance(op[2], str):
+            raise TypeError("a shape")
+        _assert_path_arg(op[1], non_empty=True)
+    elif verb == "t":
+        if len(op) != 3 or not _is_int(op[2]) or op[2] < 0:
+            raise TypeError("t shape")
+        _assert_path_arg(op[1], non_empty=True)
+    elif verb == "p":
+        if len(op) != 5:
+            raise TypeError("p arity")
+        _assert_path_arg(op[1])
+        if not _is_int(op[2]) or op[2] < 0:
+            raise TypeError("p index")
+        if not _is_int(op[3]) or op[3] < 0:
+            raise TypeError("p remove")
+        if not isinstance(op[4], list):
+            raise TypeError("p items")
+    elif verb == "m":
+        if len(op) != 3:
+            raise TypeError("m arity")
+        _assert_path_arg(op[1])
+        _assert_permutation(op[2])
+    else:
+        raise TypeError(f"unknown op verb: {verb}")
+
+
+def _resolve(root: JsonValue, path: Sequence[Any]) -> Any:
+    value: Any = root
+    for segment in path:
+        if isinstance(segment, str):
+            if not isinstance(value, dict):
+                raise PathError(list(path))
+            value = value[segment]
+        else:
+            if not isinstance(value, list) or segment >= len(value):
+                raise PathError(list(path))
+            value = value[segment]
+    return value
+
+
+def _assert_index_in_range(parent: list[Any], index: int) -> None:
+    if index > len(parent):
+        raise UnsafePathError(index)
+
+
+def apply(target: JsonValue, ops: Iterable[Op]) -> JsonValue:
+    """Apply decoded operations to a mutable value and return the possibly replaced root.
+
+    Payloads carried by an operation are copied into the result, so the result never aliases the
+    caller's operations and later operations can safely address what an earlier one inserted.
+    """
+
+    root: Any = target
+    for op in ops:
+        assert_valid_op(op)
+        if op[0] == "r":
+            root = copy_json(op[1])
+            continue
+        path = op[1]
+        assert_safe_path(path)
+        if op[0] == "p":
+            parent = root if not path else _resolve(root, path)
+            if not isinstance(parent, list):
+                raise PathError(path)
+            index, remove, items = op[2], op[3], op[4]
+            parent[index:index + remove] = cast(list[Any], copy_json(items))
+            continue
+        if op[0] == "m":
+            parent = root if not path else _resolve(root, path)
+            if not isinstance(parent, list) or len(parent) != len(op[2]):
+                raise PathError(path)
+            previous = parent[:]
+            for index, source in enumerate(op[2]):
+                parent[index] = previous[source]
+            continue
+
+        parent = _resolve(root, path[:-1])
+        key = path[-1]
+        if isinstance(parent, list):
+            if not _is_int(key):
+                raise UnsafePathError(key)
+            _assert_index_in_range(parent, key)
+        if not isinstance(parent, (dict, list)):
+            raise PathError(path)
+        if op[0] == "s":
+            parent[key] = copy_json(op[2])
+        elif op[0] == "d":
+            if isinstance(parent, list):
+                if key >= len(parent):
+                    raise PathError(path)
+                del parent[key]
+            else:
+                parent.pop(key, None)
+        elif op[0] == "a":
+            current = parent[key] if isinstance(parent, list) or key in parent else None
+            if not isinstance(current, str):
+                raise PathError(path)
+            parent[key] = current + op[2]
+        elif op[0] == "t":
+            current = parent[key] if isinstance(parent, list) or key in parent else None
+            if not isinstance(current, str):
+                raise PathError(path)
+            parent[key] = current[op[2]:]
+    return root
+
+
+def apply_immutable(target: JsonValue, ops: Sequence[Op]) -> JsonValue:
+    """Apply one batch without mutating ``target`` or its containers."""
+
+    return apply(copy_json(target), ops)
+
+
+def apply_immutable_batches(target: JsonValue, batches: Iterable[Sequence[Op]]) -> JsonValue:
+    """Apply ordered batches without exposing or mutating an intermediate revision."""
+
+    root = copy_json(target)
+    for ops in batches:
+        root = apply(root, ops)
+    return root
+
+
+__all__ = [
+    "MAX_DELTA_OPERATIONS",
+    "Op",
+    "PathError",
+    "RESERVED_SEGMENTS",
+    "UnsafePathError",
+    "apply",
+    "apply_immutable",
+    "apply_immutable_batches",
+    "assert_safe_path",
+    "assert_valid_op",
+]

pi_durable/documents.py

@@ -0,0 +1,366 @@
+"""Document definitions, typed tokens, and materialization.
+
+A document definition is a token-safe value object. Persisted records keep the v1.3.0 camelCase
+shape; Python callers configure definitions with snake_case names and may also pass a mapping.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import json
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any, Literal, TypeAlias, cast
+
+from .delta import Op
+from .ids import (
+    ConversationId,
+    DocumentId,
+    TaskId,
+)
+from .json import JsonObject, copy_json
+from .types import CheckpointInfo, DocumentAddress, DocumentCreate, DocumentRecord, StoredDocument
+
+DocScope: TypeAlias = Literal["session", "conversation", "task"]
+
+#: Positional arities of the definition callbacks without the optional receiver.
+_SINGLETON_INITIAL_ARITY = 0
+_FAMILY_INITIAL_ARITY = 1
+_MIGRATE_ARITY = 2
+_CHECKPOINT_ARITY = 3
+
+
+@dataclass(frozen=True, slots=True)
+class DocDefinition:
+    """Erased document definition used by the Session after token resolution."""
+
+    kind: str
+    version: int
+    scope: DocScope
+    initial: Callable[..., JsonObject]
+    family: bool = False
+    history: Literal["latest", "rewindable"] | None = None
+    fork: Literal["asOf", "current", "initial"] | None = None
+    migrate: Callable[[JsonObject, int], JsonObject] | None = None
+    checkpoint_when: Callable[[JsonObject, list[Op], CheckpointInfo], bool] | None = None
+
+    def __getitem__(self, key: str) -> Any:
+        if key == "checkpointWhen":
+            return self.checkpoint_when
+        return getattr(self, key)
+
+
+@dataclass(frozen=True, slots=True)
+class DocToken:
+    """Typed singleton document token passed explicitly to Session access."""
+
+    definition: DocDefinition
+
+
+@dataclass(frozen=True, slots=True)
+class DocFamilyToken:
+    """Typed keyed document-family token passed explicitly to Session access."""
+
+    definition: DocDefinition
+
+
+AnyDocToken: TypeAlias = DocToken | DocFamilyToken
+
+# Scope-specific token names from the v1.3.0 public surface. Python resolves the scope at runtime
+# from the definition, so these are the same erased token classes.
+SessionDocToken: TypeAlias = DocToken
+ConversationDocToken: TypeAlias = DocToken
+RewindableConversationDocToken: TypeAlias = DocToken
+TaskDocToken: TypeAlias = DocToken
+SessionDocFamilyToken: TypeAlias = DocFamilyToken
+ConversationDocFamilyToken: TypeAlias = DocFamilyToken
+RewindableConversationDocFamilyToken: TypeAlias = DocFamilyToken
+TaskDocFamilyToken: TypeAlias = DocFamilyToken
+
+#: Erased definition shapes used by callers that do not care about family/singleton tokens.
+CommonDocDefinition: TypeAlias = DocDefinition
+DocFamilyDefinition: TypeAlias = DocDefinition
+
+
+def _definition_values(definition: Mapping[str, Any] | None, kwargs: Mapping[str, Any]) -> dict[str, Any]:
+    values = dict(definition or {})
+    values.update(kwargs)
+    aliases = {
+        "checkpointWhen": "checkpoint_when",
+        "initial": "initial",
+    }
+    for source, target in aliases.items():
+        if source in values and target not in values:
+            values[target] = values.pop(source)
+    return values
+
+
+def _bind_receiver(
+    callback: Callable[..., Any] | None,
+    definition: DocDefinition,
+    arity: int,
+) -> Callable[..., Any] | None:
+    """Bind a definition callback that declares the definition as its receiver.
+
+    v1.3.0 invokes `initial`, `migrate`, and `checkpointWhen` as methods, so `this` is the
+    definition. Python callables are plain functions; one whose first parameter is named `self`
+    or `definition` and that declares exactly one extra positional parameter receives the
+    definition bound to it.
+    """
+
+    if callback is None:
+        return None
+    try:
+        parameters = list(inspect.signature(callback).parameters.values())
+    except (TypeError, ValueError):
+        return callback
+    if any(parameter.kind is inspect.Parameter.VAR_POSITIONAL for parameter in parameters):
+        return callback
+    positional = [
+        parameter
+        for parameter in parameters
+        if parameter.kind
+        in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+    ]
+    if len(positional) != arity + 1:
+        return callback
+    if positional[0].name not in ("self", "definition"):
+        return callback
+    return functools.partial(callback, definition)
+
+
+def _build_definition(values: Mapping[str, Any], *, family: bool) -> DocDefinition:
+    kind = values.get("kind")
+    if not isinstance(kind, str):
+        raise TypeError("Document kind must be a string")
+    version = values.get("version")
+    if not isinstance(version, int) or isinstance(version, bool) or version < 1:
+        raise TypeError(f"Document {kind} version must be a positive integer")
+    scope = values.get("scope")
+    if scope not in ("session", "conversation", "task"):
+        raise TypeError(f"Document {kind} scope must be session, conversation, or task")
+    initial = values.get("initial")
+    if not callable(initial):
+        raise TypeError(f"Document {kind} requires an initial() function")
+    history = values.get("history")
+    fork = values.get("fork")
+    if scope == "conversation":
+        if history not in ("latest", "rewindable"):
+            raise TypeError(f"Conversation document {kind} requires history 'latest' or 'rewindable'")
+        if fork not in ("asOf", "current", "initial"):
+            raise TypeError(f"Conversation document {kind} requires a fork policy")
+    elif history is not None or fork is not None:
+        raise TypeError(f"Document {kind} history and fork apply only to conversation scope")
+    migrate = values.get("migrate")
+    if migrate is not None and not callable(migrate):
+        raise TypeError(f"Document {kind} migrate must be callable")
+    checkpoint_when = values.get("checkpoint_when")
+    if checkpoint_when is not None and not callable(checkpoint_when):
+        raise TypeError(f"Document {kind} checkpoint_when must be callable")
+    definition = DocDefinition(
+        kind=kind,
+        version=version,
+        scope=scope,
+        initial=initial,
+        family=family,
+        history=history,
+        fork=fork,
+        migrate=migrate,
+        checkpoint_when=checkpoint_when,
+    )
+    # Bind definition callbacks that declare the definition as their receiver, after constructing
+    # the final value so the receiver is the token's own definition.
+    object.__setattr__(
+        definition,
+        "initial",
+        _bind_receiver(
+            initial, definition, _FAMILY_INITIAL_ARITY if family else _SINGLETON_INITIAL_ARITY
+        ),
+    )
+    object.__setattr__(
+        definition, "migrate", _bind_receiver(migrate, definition, _MIGRATE_ARITY)
+    )
+    object.__setattr__(
+        definition,
+        "checkpoint_when",
+        _bind_receiver(checkpoint_when, definition, _CHECKPOINT_ARITY),
+    )
+    return definition
+
+
+def define_doc(
+    definition: Mapping[str, Any] | None = None,
+    /,
+    **kwargs: Any,
+) -> DocToken:
+    """Define a Session-, conversation-, or task-scoped singleton document."""
+
+    return DocToken(_build_definition(_definition_values(definition, kwargs), family=False))
+
+
+def define_doc_family(
+    definition: Mapping[str, Any] | None = None,
+    /,
+    **kwargs: Any,
+) -> DocFamilyToken:
+    """Define a keyed Session-, conversation-, or task-scoped document family."""
+
+    values = _definition_values(definition, kwargs)
+    values.pop("family", None)
+    return DocFamilyToken(_build_definition(values, family=True))
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedAddress:
+    """Logical address plus its stable cache identity and consumed argument count."""
+
+    address: DocumentAddress
+    id: str
+    next_argument: int
+
+
+def _owner_id(value: object, definition: DocDefinition, scope: str) -> int:
+    if not isinstance(value, int) or isinstance(value, bool) or value < 1:
+        raise TypeError(f"Document {definition.kind} requires a {scope} ID")
+    return value
+
+
+def resolve_address(definition: DocDefinition, args: tuple[Any, ...] | list[Any]) -> ResolvedAddress:
+    """Resolve an overloaded argument list and return the index after owner and family key."""
+
+    index = 0
+    if definition.scope == "session":
+        scope: dict[str, Any] = {"kind": "session"}
+    elif definition.scope == "conversation":
+        scope = {
+            "kind": "conversation",
+            "conversationId": cast(ConversationId, _owner_id(args[index], definition, "conversation")),
+        }
+        index += 1
+    else:
+        scope = {"kind": "task", "taskId": cast(TaskId, _owner_id(args[index], definition, "task"))}
+        index += 1
+    key: str | None = None
+    if definition.family:
+        if index >= len(args) or not isinstance(args[index], str):
+            raise TypeError(f"Document family {definition.kind} requires a string key")
+        key = args[index]
+        index += 1
+    address: DocumentAddress = {"kind": definition.kind, "scope": cast(Any, scope)}
+    if key is not None:
+        address["key"] = key
+    return ResolvedAddress(address=address, id=address_id(address), next_argument=index)
+
+
+def address_id(address: DocumentAddress) -> str:
+    """Return the stable string identity of one logical address."""
+
+    scope = address["scope"]
+    owner = None if scope["kind"] == "session" else scope.get("conversationId", scope.get("taskId"))
+    return json.dumps(
+        [address["kind"], scope["kind"], owner, address.get("key")],
+        separators=(",", ":"),
+    )
+
+
+def document_create(
+    definition: DocDefinition, address: DocumentAddress, document_id: DocumentId
+) -> DocumentCreate:
+    """Build the storage create record for a new incarnation at an address."""
+
+    record: dict[str, Any] = {
+        "id": document_id,
+        "kind": address["kind"],
+        "scope": copy_json(address["scope"]),
+    }
+    if "key" in address:
+        record["key"] = address["key"]
+    if address["scope"]["kind"] == "conversation":
+        record["history"] = definition.history
+        record["fork"] = definition.fork
+    return cast(DocumentCreate, record)
+
+
+def check_record_scope(definition: DocDefinition, record: DocumentCreate | DocumentRecord) -> None:
+    """Reject typed access whose token disagrees with the persisted scope and semantics."""
+
+    scope = record["scope"]
+    if scope["kind"] != definition.scope:
+        raise TypeError(
+            f"Document {record['id']} ({record['kind']}) does not match the supplied definition semantics"
+        )
+    if scope["kind"] == "conversation":
+        if record.get("history") != definition.history or record.get("fork") != definition.fork:
+            raise TypeError(
+                f"Document {record['id']} ({record['kind']}) does not match the supplied definition semantics"
+            )
+
+
+def check_record_version(
+    definition: DocDefinition,
+    record: DocumentCreate | DocumentRecord,
+    version: int,
+) -> None:
+    """Reject typed access to a stored version the supplied definition cannot use."""
+
+    if version > definition.version:
+        raise ValueError(
+            f"Document {record['id']} ({record['kind']}) has newer version {version} "
+            f"than {definition.version}"
+        )
+    if version < definition.version and definition.migrate is None:
+        raise ValueError(
+            f"Document {record['id']} ({record['kind']}) requires migration from version {version}"
+        )
+
+
+def materialize_document_value(
+    definition: DocDefinition,
+    record: DocumentCreate | DocumentRecord,
+    version: int,
+    value: JsonObject,
+) -> JsonObject:
+    """Validate and materialize one detached value for typed access."""
+
+    check_record_scope(definition, record)
+    check_record_version(definition, record, version)
+    if version == definition.version:
+        return value
+    assert definition.migrate is not None
+    return cast(JsonObject, copy_json(definition.migrate(cast(JsonObject, copy_json(value)), version)))
+
+
+def materialize_document(definition: DocDefinition, stored: StoredDocument) -> JsonObject:
+    """Validate and materialize one detached stored document."""
+
+    return materialize_document_value(definition, stored["record"], stored["version"], stored["value"])
+
+
+__all__ = [
+    "AnyDocToken",
+    "CommonDocDefinition",
+    "ConversationDocFamilyToken",
+    "ConversationDocToken",
+    "DocDefinition",
+    "DocFamilyDefinition",
+    "DocFamilyToken",
+    "DocScope",
+    "DocToken",
+    "ResolvedAddress",
+    "RewindableConversationDocFamilyToken",
+    "RewindableConversationDocToken",
+    "SessionDocFamilyToken",
+    "SessionDocToken",
+    "TaskDocFamilyToken",
+    "TaskDocToken",
+    "address_id",
+    "check_record_scope",
+    "check_record_version",
+    "define_doc",
+    "define_doc_family",
+    "document_create",
+    "materialize_document",
+    "materialize_document_value",
+    "resolve_address",
+]

pi_durable/entries.py

@@ -0,0 +1,66 @@
+"""Typed entry kinds.
+
+An ``Entry`` token carries the persisted discriminator and narrows an entry record by ``kind``.
+The built-in tokens name the transcript entries durable itself writes; applications define their
+own with :func:`define_entry`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Generic, Never, TypeGuard, TypeVar, cast
+
+from .json import JsonValue
+from .types import TypedEntry
+
+D = TypeVar("D", bound=JsonValue)
+
+
+@dataclass(frozen=True, slots=True)
+class Entry(Generic[D]):
+    """A typed entry kind with a narrowing guard for its ``data`` payload."""
+
+    kind: str
+
+    def is_(self, entry: Mapping[str, Any] | None) -> TypeGuard[TypedEntry[D]]:
+        """Return whether ``entry`` is present and has this token's kind."""
+
+        return entry is not None and entry.get("kind") == self.kind
+
+
+def define_entry(kind: str) -> Entry[D]:
+    """Define a typed entry kind whose guard narrows by ``EntryRecord.kind``."""
+
+    if not isinstance(kind, str) or not kind:
+        raise TypeError("Entry kind must be a non-empty string")
+    return cast(Entry[D], Entry(kind))
+
+
+#: User input: ``model`` is ``[UserMessage]``. Written by submissions.
+UserEntry: Entry[Never] = define_entry("pi.user")
+#: Provider result with any stop reason: ``model`` is ``[AssistantMessage]``. Written by generation.
+AssistantEntry: Entry[Never] = define_entry("pi.assistant")
+#: Positional prompt and tool change: ``model`` is ``[SystemMessage]`` with empty ``content``.
+SystemEntry: Entry[Never] = define_entry("pi.system")
+#: Tool result: ``model`` is ``[ToolResultMessage]``, whose content ends with the rendered
+#: diagnostics block; ``data`` holds the structured diagnostics, possibly none.
+ToolResultEntry: Entry[dict[str, JsonValue]] = define_entry("pi.tool-result")
+#: Start of a new context: always ``head: "self"``, with ``model`` absent for a plain reset or
+#: ``[UserMessage]`` carrying the handoff text.
+ResetEntry: Entry[Never] = define_entry("pi.reset")
+#: Compaction summary: ``model`` is ``[UserMessage]`` with the wrapped summary, ``head`` the first
+#: kept entry.
+CompactionEntry: Entry[dict[str, JsonValue]] = define_entry("pi.compaction")
+
+
+__all__ = [
+    "AssistantEntry",
+    "CompactionEntry",
+    "Entry",
+    "ResetEntry",
+    "SystemEntry",
+    "ToolResultEntry",
+    "UserEntry",
+    "define_entry",
+]