pi-python-core 0.8.1__py3-none-any.whl

pi_python/errors.py

@@ -0,0 +1,49 @@
+"""Stable exception classes; exceptions never imply that side effects were rolled back."""
+
+
+class PiError(Exception):
+    pass
+
+
+class ConfigurationError(PiError):
+    pass
+
+
+class MessageValidationError(PiError):
+    pass
+
+
+class UnsupportedCapabilityError(MessageValidationError):
+    pass
+
+
+class ProviderProtocolError(PiError):
+    pass
+
+
+class AgentBusyError(PiError):
+    pass
+
+
+class AgentClosedError(PiError):
+    pass
+
+
+class InvalidContinuationError(PiError):
+    pass
+
+
+class ToolOutcomeUnknownError(PiError):
+    pass
+
+
+class CleanupTimeoutError(PiError):
+    pass
+
+
+class SubscriptionError(PiError):
+    pass
+
+
+class CandidateValidationError(PiError):
+    pass

pi_python/estimate.py

@@ -0,0 +1,144 @@
+"""Context-size estimate ported from Pi a13d35a utils/estimate.ts (MIT); see NOTICE.
+
+A character heuristic, not a tokenizer: four UTF-16 code units per token and a fixed
+charge per image. It sizes output limits and compaction decisions; the service still
+enforces the real context limit.
+"""
+
+from __future__ import annotations
+from typing import Any
+import json
+import math
+from .messages import (
+    AssistantMessage,
+    ImageContent,
+    Message,
+    SystemMessage,
+    TextContent,
+    ThinkingContent,
+    ToolResultMessage,
+    UserMessage,
+)
+from .transcript import system_message_text
+
+_CHARS_PER_TOKEN = 4
+_IMAGE_CHARS = 4800
+_SAFETY_TOKENS = 4096
+
+
+def _length(text: str) -> int:
+    """JavaScript string length: UTF-16 code units."""
+    return len(text.encode("utf-16-le", "surrogatepass")) // 2
+
+
+def _json(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+
+
+def _tokens(chars: int) -> int:
+    return math.ceil(chars / _CHARS_PER_TOKEN)
+
+
+def _content_tokens(content: str | list[TextContent | ImageContent]) -> int:
+    if isinstance(content, str):
+        return _tokens(_length(content))
+    return _tokens(
+        sum(_length(b.text) if isinstance(b, TextContent) else _IMAGE_CHARS for b in content)
+    )
+
+
+def estimate_message_tokens(message: Message) -> int:
+    if isinstance(message, SystemMessage):
+        tokens = _tokens(_length(system_message_text(message)))
+        if message.tools_added:
+            tools = [
+                {"name": t.name, "description": t.description, "parameters": t.input_schema}
+                for t in message.tools_added
+            ]
+            tokens += _tokens(_length(_json(tools)))
+        if message.tools_removed:
+            tokens += _tokens(_length(_json([{"name": n} for n in message.tools_removed])))
+        return tokens
+    if isinstance(message, (UserMessage, ToolResultMessage)):
+        return _content_tokens(message.content)
+    if isinstance(message, AssistantMessage):
+        chars = 0
+        for block in message.content:
+            if isinstance(block, TextContent):
+                chars += _length(block.text)
+            elif isinstance(block, ThinkingContent):
+                chars += _length(block.thinking)
+            elif not isinstance(block, ImageContent):
+                chars += _length(block.name) + _length(_json(block.arguments))
+        return _tokens(chars)
+    return 0
+
+
+def _usage_tokens(usage: dict) -> int:
+    total = usage.get("total_tokens") or 0
+    return total or sum(
+        usage.get(k, 0) or 0 for k in ("input", "output", "cache_read", "cache_write")
+    )
+
+
+def estimate_context_tokens(messages: list[Message]) -> int:
+    """Last valid reported usage plus an estimate of everything after it."""
+    latest = -math.inf
+    anchor = None
+    for index, message in enumerate(messages):
+        if isinstance(message, AssistantMessage):
+            # A newer prefix message inserted after this response invalidates its usage.
+            if (
+                message.timestamp >= latest
+                and message.stop_reason not in {"aborted", "error"}
+                and _usage_tokens(message.usage) > 0
+            ):
+                anchor = index
+        latest = max(latest, message.timestamp)
+    if anchor is None:
+        return sum(estimate_message_tokens(m) for m in messages)
+    message = messages[anchor]
+    assert isinstance(message, AssistantMessage)
+    return _usage_tokens(message.usage) + sum(
+        estimate_message_tokens(m) for m in messages[anchor + 1 :]
+    )
+
+
+def clamp_max_tokens_to_context(
+    context_window: int, messages: list[Message], max_tokens: int
+) -> int:
+    """Pi clampMaxTokensToContext: leave room for the estimated prompt and a margin."""
+    if context_window <= 0:
+        return max(1, max_tokens)
+    available = context_window - estimate_context_tokens(messages) - _SAFETY_TOKENS
+    return min(max_tokens, max(1, available))
+
+
+def short_hash(text: str) -> str:
+    """Pi utils/hash.ts shortHash, bit for bit (32-bit Math.imul over UTF-16 units)."""
+
+    def imul(a: int, b: int) -> int:
+        result = (a * b) & 0xFFFFFFFF
+        return result - 0x100000000 if result & 0x80000000 else result
+
+    def u32(value: int) -> int:
+        return value & 0xFFFFFFFF
+
+    def base36(value: int) -> str:
+        digits = "0123456789abcdefghijklmnopqrstuvwxyz"
+        out = ""
+        while True:
+            value, rest = divmod(value, 36)
+            out = digits[rest] + out
+            if not value:
+                return out
+
+    h1, h2 = 0xDEADBEEF, 0x41C6CE57
+    units = text.encode("utf-16-le", "surrogatepass")
+    for i in range(0, len(units), 2):
+        ch = units[i] | units[i + 1] << 8
+        h1 = imul(u32(h1) ^ ch, 2654435761)
+        h2 = imul(u32(h2) ^ ch, 1597334677)
+    h1 = imul(u32(h1) ^ (u32(h1) >> 16), 2246822507) ^ imul(u32(h2) ^ (u32(h2) >> 13), 3266489909)
+    h2 = imul(u32(h2) ^ (u32(h2) >> 16), 2246822507) ^ imul(u32(h1) ^ (u32(h1) >> 13), 3266489909)
+    return base36(u32(h2)) + base36(u32(h1))

pi_python/events.py

@@ -0,0 +1,138 @@
+"""Sequential critical delivery, detached payloads and independent failure diagnostics."""
+
+from __future__ import annotations
+import asyncio
+import inspect
+import json
+from collections.abc import Awaitable, Callable
+from copy import deepcopy
+from dataclasses import asdict, dataclass, field
+from typing import Any
+from .errors import MessageValidationError, SubscriptionError
+from .messages import validate_json
+
+
+@dataclass
+class Event:
+    type: str
+    run_id: str
+    turn_id: int
+    sequence: int
+    call_id: str | None = None
+    data: dict[str, Any] = field(default_factory=dict)
+    schema_version: int = 1
+
+
+EventListener = Callable[[Event], Awaitable[None] | None]
+Unsubscribe = Callable[[], None]
+
+
+def encode_event(event: Event) -> str:
+    data = asdict(event)
+    validate_json(data)
+    decode_event(json.dumps(data))
+    return json.dumps(data, ensure_ascii=False, allow_nan=False)
+
+
+def decode_event(value: str) -> Event:
+    try:
+        d = json.loads(value)
+        validate_json(d)
+        if type(d.get("schema_version")) is not int or d["schema_version"] != 1:
+            raise MessageValidationError("Unsupported event schema version")
+        e = Event(**d)
+        if (
+            not isinstance(e.type, str)
+            or not isinstance(e.run_id, str)
+            or not isinstance(e.data, dict)
+        ):
+            raise MessageValidationError("Invalid event")
+        if (
+            type(e.sequence) is not int
+            or e.sequence < 1
+            or type(e.turn_id) is not int
+            or e.turn_id < 0
+        ):
+            raise MessageValidationError("Invalid event sequence or turn")
+        if e.call_id is not None and not isinstance(e.call_id, str):
+            raise MessageValidationError("Invalid event call ID")
+        return e
+    except (ValueError, TypeError, AttributeError) as exc:
+        raise MessageValidationError(str(exc)) from exc
+
+
+class EventDispatcher:
+    def __init__(self) -> None:
+        self.listeners: list[EventListener] = []
+        self.diagnostics: list[dict[str, Any]] = []
+        self.failed = False
+        self.sequence = 0
+        self.lock = asyncio.Lock()
+
+    def subscribe(self, listener: EventListener) -> Unsubscribe:
+        self.listeners.append(listener)
+        active = True
+
+        def unsubscribe() -> None:
+            nonlocal active
+            if active:
+                active = False
+                self.listeners.remove(listener)
+
+        return unsubscribe
+
+    async def emit(
+        self,
+        kind: str,
+        run_id: str,
+        turn_id: int,
+        data: dict[str, Any],
+        call_id: str | None,
+        await_owned: Callable,
+    ) -> None:
+        if self.failed:
+            return
+        async with self.lock:
+            if self.failed:
+                return
+            self.sequence += 1
+            event = Event(kind, run_id, turn_id, self.sequence, call_id, deepcopy(data))
+            encode_event(event)
+            listeners = list(self.listeners)
+            for index, listener in enumerate(listeners):
+                try:
+                    result = listener(deepcopy(event))
+                    if inspect.isawaitable(result):
+                        await await_owned(result)
+                except Exception as exc:
+                    self.failed = True
+                    self.diagnostics.append(
+                        {
+                            "event": kind,
+                            "sequence": event.sequence,
+                            "listener_index": index,
+                            "unhandled_listener_indices": list(range(index + 1, len(listeners))),
+                            "error": f"{type(exc).__name__}: {exc}",
+                        }
+                    )
+                    raise SubscriptionError(f"{kind} subscriber {index} failed: {exc}") from exc
+
+
+class EventQueue:
+    """A bounded display adapter. Only message deltas may be dropped, explicitly counted."""
+
+    def __init__(self, maxsize: int = 128, *, drop_text_updates: bool = False):
+        if maxsize <= 0:
+            raise ValueError("maxsize must be positive")
+        self.queue: asyncio.Queue[Event] = asyncio.Queue(maxsize)
+        self.drop_text_updates = drop_text_updates
+        self.dropped_updates = 0
+
+    async def __call__(self, event: Event) -> None:
+        if self.drop_text_updates and event.type == "message_update" and self.queue.full():
+            self.dropped_updates += 1
+            return
+        await self.queue.put(deepcopy(event))
+
+    async def get(self) -> Event:
+        return await self.queue.get()