mirrors-sdk 0.1.0__py3-none-any.whl

mirrors_sdk/__init__.py

@@ -0,0 +1,33 @@
+"""Mirrors: optional context and best-effort original trace capture."""
+
+from .client import Mirrors
+from .models import (
+    ContextFreshness,
+    ContextResult,
+    DeliveryReceipt,
+    DeliveryTicket,
+    FlushResult,
+    TurnTimer,
+)
+from .types import (
+    CanonicalMessage,
+    CanonicalTrace,
+    EndUser,
+    MessageBlock,
+    SourceCompleteness,
+)
+
+__all__ = [
+    "Mirrors",
+    "ContextFreshness",
+    "ContextResult",
+    "DeliveryReceipt",
+    "DeliveryTicket",
+    "FlushResult",
+    "TurnTimer",
+    "CanonicalMessage",
+    "CanonicalTrace",
+    "EndUser",
+    "MessageBlock",
+    "SourceCompleteness",
+]

mirrors_sdk/capture.py

@@ -0,0 +1,254 @@
+"""Ordered capture delivery with immutable reconciliation of uncertain writes."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import time
+import uuid
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from typing import Any
+
+from .models import DeliveryReceipt
+from .transport import TransportError
+from .wire import Wire
+
+
+@dataclass(frozen=True)
+class _Pending:
+    digest: bytes
+    body: bytes
+    request: dict[str, Any]
+
+
+@dataclass
+class _Trace:
+    metadata: bytes
+    ordinal: int = 0
+    pending: _Pending | None = None
+    sealed: bool = False
+    retired: bool = False
+    lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+    running: asyncio.Task[Any] | None = None
+    final_digest: bytes | None = None
+    final_owner: asyncio.Task[Any] | None = None
+
+
+class CaptureRuntime:
+    """Loop-owned state; application threads communicate through the SDK worker."""
+
+    def __init__(self, transport: Any, config: Any) -> None:
+        self._transport = transport
+        self._config = config
+        self._active: dict[str, _Trace] = {}
+        self._terminal: dict[str, _Trace] = {}
+        self._recent: OrderedDict[str, tuple[bytes, DeliveryReceipt]] = OrderedDict()
+        self._closed = False
+
+    async def send(self, input: dict[str, Any], deadline: float) -> DeliveryReceipt:
+        """Send once; finals may retry once within the same absolute deadline."""
+        receipt = await self._send(input, deadline)
+        if input.get("final") is True:
+            trace_id = input.get("trace", {}).get("id")
+            # A rejected final still ends the host execution. Release any prefix state
+            # left behind by validation/capacity rejection, preserving admitted finals.
+            self.release(trace_id)
+            state = self._terminal.get(trace_id)
+            if state is not None and state.final_owner is asyncio.current_task():
+                # Settled uncertain finals do not consume scarce terminal capacity forever.
+                # Their immutable outcome is retained in the same bounded receipt cache.
+                self._terminal.pop(trace_id, None)
+                if state.final_digest is not None:
+                    self._remember(trace_id, state.final_digest, receipt)
+                self._retire(state)
+        return receipt
+
+    async def _send(self, input: dict[str, Any], deadline: float) -> DeliveryReceipt:
+        if self._closed:
+            return DeliveryReceipt("dropped", "closed")
+        final = input.get("final") is True
+        timeout_ms = self._config.timeout_ms
+        deadline = min(
+            deadline,
+            time.monotonic() + (timeout_ms or (6000 if final else 1000)) / 1000,
+        )
+        try:
+            encoded = Wire.encode(input)
+            snapshot = json.loads(encoded)
+            trace_id = snapshot["trace"]["id"]
+            digest = hashlib.sha256(encoded).digest()
+            metadata = self._metadata(snapshot["trace"])
+        except (TypeError, ValueError, KeyError, RecursionError):
+            return DeliveryReceipt("dropped", "invalid_evidence")
+        previous = self._recent.get(trace_id)
+        if previous is not None:
+            return (
+                previous[1]
+                if previous[0] == digest
+                else DeliveryReceipt("dropped", "terminal_conflict")
+            )
+        state = self._terminal.get(trace_id) or self._active.get(trace_id)
+        if state is not None and state.metadata != metadata:
+            return DeliveryReceipt("dropped", "invalid_evidence")
+        if state is not None and state.sealed and not final:
+            return DeliveryReceipt("dropped", "terminal_conflict")
+        if state is not None and state.sealed and state.final_digest != digest:
+            return DeliveryReceipt("dropped", "terminal_conflict")
+        if state is None:
+            pool = self._terminal if final else self._active
+            if len(pool) >= (16 if final else 64):
+                return DeliveryReceipt("dropped", "capacity")
+            state = _Trace(metadata, sealed=final)
+            pool[trace_id] = state
+            if final:
+                state.final_digest = digest
+                state.final_owner = asyncio.current_task()
+        elif final and not state.sealed:
+            if len(self._terminal) >= 16:
+                return DeliveryReceipt("dropped", "capacity")
+            state.sealed = True
+            state.final_digest = digest
+            state.final_owner = asyncio.current_task()
+            self._active.pop(trace_id, None)
+            self._terminal[trace_id] = state
+        acquired = False
+        try:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return DeliveryReceipt("unconfirmed", "timeout")
+            await asyncio.wait_for(state.lock.acquire(), remaining)
+            acquired = True
+            state.running = asyncio.current_task()
+            if state.retired or self._closed:
+                return DeliveryReceipt("dropped", "closed")
+            if state.sealed and not final:
+                return DeliveryReceipt("dropped", "superseded")
+            # Another queued final may have completed while this call waited.
+            previous = self._recent.get(trace_id)
+            if previous is not None:
+                return (
+                    previous[1]
+                    if previous[0] == digest
+                    else DeliveryReceipt("dropped", "terminal_conflict")
+                )
+            if state.pending is not None and state.pending.digest != digest:
+                # An uncertain terminal is immutable. A different final cannot replace it.
+                if state.pending.request["final"]:
+                    return DeliveryReceipt("dropped", "terminal_conflict")
+                await self._deliver(state, trace_id, deadline, retry=final)
+            if state.pending is None:
+                if state.ordinal >= 10_000:
+                    return DeliveryReceipt("dropped", "capacity")
+                request = {
+                    **snapshot,
+                    "protocol": 3,
+                    "agentId": self._config.agent_id,
+                    "requestId": str(uuid.uuid4()),
+                    "ordinal": state.ordinal + 1,
+                }
+                state.pending = _Pending(
+                    digest, Wire.encode(request, 1_048_576), request
+                )
+            return await self._deliver(state, trace_id, deadline, retry=final)
+        except asyncio.TimeoutError:
+            return DeliveryReceipt("unconfirmed", "timeout")
+        except asyncio.CancelledError:
+            return DeliveryReceipt("unconfirmed", "transport")
+        except TransportError as error:
+            return DeliveryReceipt(
+                "unconfirmed", "timeout" if error.reason == "timeout" else "transport"
+            )
+        except Exception:
+            # Optional capture must not leak protocol or transport failures into the host.
+            return DeliveryReceipt("unconfirmed", "transport")
+        finally:
+            if acquired:
+                state.running = None
+                state.lock.release()
+
+    async def _deliver(
+        self, state: _Trace, trace_id: str, deadline: float, *, retry: bool
+    ) -> DeliveryReceipt:
+        pending = state.pending
+        assert pending is not None
+        for attempt in range(2 if retry else 1):
+            if time.monotonic() >= deadline:
+                raise asyncio.TimeoutError
+            if state.retired or self._closed:
+                raise asyncio.CancelledError
+            try:
+                response = await self._transport.request(
+                    "trace",
+                    pending.body,
+                    deadline,
+                    lambda value: Wire.trace_response(value, pending.request),
+                    final_recovery=retry,
+                )
+                break
+            except TransportError as error:
+                if (
+                    error.permanent
+                    or not retry
+                    or attempt == 1
+                    or time.monotonic() >= deadline
+                ):
+                    raise
+        if state.retired or self._closed:
+            raise asyncio.CancelledError
+        if time.monotonic() >= deadline:
+            raise asyncio.TimeoutError
+        if not Wire.trace_response(response, pending.request):
+            raise ValueError("Invalid capture response")
+        state.ordinal = pending.request["ordinal"]
+        state.pending = None
+        receipt = DeliveryReceipt("accepted", ingestion=response["ingestion"])
+        if pending.request["final"]:
+            self._active.pop(trace_id, None)
+            self._terminal.pop(trace_id, None)
+            self._remember(trace_id, pending.digest, receipt)
+        return receipt
+
+    def _remember(self, trace_id: str, digest: bytes, receipt: DeliveryReceipt) -> None:
+        self._recent[trace_id] = (digest, receipt)
+        if len(self._recent) > 128:
+            self._recent.popitem(last=False)
+
+    def release(self, trace_id: str) -> None:
+        """Retire prefixes locally; an admitted final retains its delivery opportunity."""
+        state = self._active.pop(trace_id, None)
+        if state is not None:
+            self._retire(state)
+
+    def clear(self) -> None:
+        """Permanently stop capture and abandon all outstanding work."""
+        self._closed = True
+        for state in (*self._active.values(), *self._terminal.values()):
+            self._retire(state)
+        self._active.clear()
+        self._terminal.clear()
+        self._recent.clear()
+
+    @staticmethod
+    def _retire(state: _Trace) -> None:
+        state.retired = True
+        if state.running is not None:
+            state.running.cancel()
+
+    @staticmethod
+    def _metadata(trace: dict[str, Any]) -> bytes:
+        # End-user and measured duration intentionally belong to the final snapshot.
+        fields = (
+            "model",
+            "entryPoint",
+            "completeness",
+            "conversationId",
+            "conversationRevision",
+        )
+        return json.dumps(
+            {key: trace[key] for key in fields if key in trace},
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=False,
+        ).encode("utf-8")

mirrors_sdk/circuit.py

@@ -0,0 +1,47 @@
+"""An endpoint-local circuit, owned exclusively by the background event loop."""
+
+from collections.abc import Callable
+import time
+
+
+class Circuit:
+    def __init__(self, threshold: int = 3, cooldown_ms: int = 30_000) -> None:
+        if type(threshold) is not int or not 1 <= threshold <= 100:
+            raise ValueError("Invalid circuit threshold")
+        if type(cooldown_ms) is not int or not 1 <= cooldown_ms <= 300_000:
+            raise ValueError("Invalid circuit cooldown")
+        self._threshold = threshold
+        self._cooldown = cooldown_ms / 1000
+        self._failures = 0
+        self._until = 0.0
+        self._probing = False
+        self._generation = 0
+
+    def acquire(self) -> Callable[[bool | None], None] | None:
+        if self._until and (time.monotonic() < self._until or self._probing):
+            return None
+        probe = self._until > 0
+        if probe:
+            self._probing = True
+        generation = self._generation
+        finished = False
+
+        def finish(success: bool | None) -> None:
+            nonlocal finished
+            if finished or generation != self._generation:
+                return
+            finished = True
+            if probe:
+                self._probing = False
+            if success is None:
+                return
+            if success:
+                self._failures = 0
+                self._until = 0
+            else:
+                self._failures += 1
+                if probe or self._failures >= self._threshold:
+                    self._until = time.monotonic() + self._cooldown
+                    self._generation += 1
+
+        return finish

mirrors_sdk/client.py

@@ -0,0 +1,339 @@
+"""Synchronous integration surface with optional async waits for async applications."""
+
+from __future__ import annotations
+
+import asyncio
+from collections import OrderedDict
+from concurrent.futures import TimeoutError
+import hashlib
+import os
+import threading
+import time
+
+from .configuration import Config
+from .context import ContextHost
+from .delivery import Deliveries
+from .models import DeliveryReceipt, FlushResult, TurnTimer
+from .wire import Wire
+from .worker import Worker
+
+
+class Mirrors:
+    def __init__(
+        self,
+        *,
+        api_url: str,
+        api_key: str,
+        agent_id: str,
+        timeout_ms: int | None = None,
+        enabled: bool = True,
+        failure_threshold: int = 3,
+        cooldown_ms: int = 30_000,
+        heartbeat_interval_ms: int = 1000,
+        mode_lease_ms: int = 3000,
+    ):
+        self._lock = threading.RLock()
+        self._pid = os.getpid()
+        self._closed = False
+        self._failed = False
+        self._worker = None
+        self._deliveries = Deliveries()
+        self._traces = {}
+        self._recent = OrderedDict()
+        try:
+            self._config = Config(
+                api_url=api_url,
+                api_key=api_key,
+                agent_id=agent_id,
+                timeout_ms=timeout_ms,
+                enabled=enabled,
+                failure_threshold=failure_threshold,
+                cooldown_ms=cooldown_ms,
+                heartbeat_interval_ms=heartbeat_interval_ms,
+                mode_lease_ms=mode_lease_ms,
+            )
+        except Exception:
+            self._config = None
+        self._enabled = self._config is not None and self._config.enabled
+        self._context = ContextHost(self._config)
+        if self._config:
+            try:
+                self._worker = Worker(
+                    self._config, self._context.observe_mode, self._worker_failed
+                )
+                self._context.worker = self._worker
+            except Exception:
+                self._worker_failed()
+
+    def _unavailable(self):
+        if os.getpid() != self._pid:
+            return "forked_process"
+        if self._config is None:
+            return "invalid_options"
+        if self._failed:
+            return "worker_failed"
+        if self._closed:
+            return "closed"
+        if not self._enabled:
+            return "disabled"
+        if self._worker is None:
+            return "worker_failed"
+        return None
+
+    def _remember(self, trace_id, value):
+        self._recent[trace_id] = value
+        self._recent.move_to_end(trace_id)
+        if len(self._recent) > 128:
+            self._recent.popitem(last=False)
+
+    def capture_trace(
+        self, trace: dict, *, final: bool = False, terminal: str | None = None
+    ):
+        """Copy and queue original evidence. Never wait for transport or a provider."""
+        started = time.monotonic()
+        if os.getpid() != self._pid:
+            # Never touch a lock inherited from another thread across fork.
+            from .models import DeliveryTicket
+
+            ticket = DeliveryTicket("forked")
+            ticket._future.set_result(DeliveryReceipt("dropped", "forked_process"))
+            return ticket
+        with self._lock:
+            reason = self._unavailable()
+            if reason:
+                return self._deliveries.drop(reason)
+        try:
+            snapshot = Wire.snapshot(trace, final=final, terminal=terminal)
+            encoded_trace = Wire.encode(snapshot)
+            value = {"trace": snapshot, "final": final, "captureOnly": True}
+            if terminal is not None:
+                value["terminal"] = terminal
+            digest = hashlib.sha256(Wire.encode(value)).digest()
+        except Exception:
+            if type(trace) is dict and type(trace.get("id")) is str:
+                self.release_trace(trace["id"])
+            return self._deliveries.drop("invalid_evidence")
+        trace_id = snapshot["id"]
+        with self._lock:
+            reason = self._unavailable()
+            if reason:
+                return self._deliveries.drop(reason)
+            if trace_id in self._recent:
+                recent = self._recent[trace_id]
+                return (
+                    recent[1]
+                    if recent and recent[0] == digest
+                    else self._deliveries.drop("terminal_conflict")
+                )
+            if final:
+                self._context.release(trace_id)
+            else:
+                self._context.observe(trace_id, encoded_trace)
+            previous = self._traces.get(trace_id)
+            if (
+                previous
+                and previous[0] == digest
+                and previous[1].receipt.status == "pending"
+            ):
+                return previous[1]
+            if self._deliveries.full(final) or (
+                not final and not previous and len(self._traces) >= 64
+            ):
+                if final:
+                    self.release_trace(trace_id)
+                return self._deliveries.drop("capacity")
+            ticket = self._deliveries.create(final, trace_id)
+            if final:
+                self._traces.pop(trace_id, None)
+                self._remember(trace_id, (digest, ticket))
+            else:
+                self._traces[trace_id] = (digest, ticket)
+            budget = self._config.timeout_ms or (6000 if final else 1000)
+            try:
+                job = self._worker.submit(
+                    lambda worker: worker.capture.send(value, started + budget / 1000)
+                )
+                self._deliveries.attach(ticket, job)
+                job.add_done_callback(lambda done: self._capture_done(ticket, done))
+            except Exception:
+                self._deliveries.settle(
+                    ticket, DeliveryReceipt("unconfirmed", "worker_failed")
+                )
+            return ticket
+
+    def _capture_done(self, ticket, job):
+        try:
+            receipt = job.result()
+        except Exception:
+            receipt = DeliveryReceipt("unconfirmed", "transport")
+        self._deliveries.settle(ticket, receipt)
+
+    def _begin_context(self, trace, timeout_ms, started, cancel):
+        with self._lock:
+            reason = self._unavailable()
+            if not reason and cancel is not None and cancel.is_set():
+                reason = "canceled"
+            if (
+                not reason
+                and type(trace) is dict
+                and type(trace.get("id")) is str
+                and trace["id"] in self._recent
+            ):
+                reason = "execution_closed"
+            if reason:
+                return self._context.empty(reason, started), None, started
+        future, deadline = self._context.start(trace, timeout_ms, started)
+        # Finalization/release may race with bounded preparation outside this lock.
+        with self._lock:
+            if (
+                type(trace) is dict
+                and type(trace.get("id")) is str
+                and trace["id"] in self._recent
+            ):
+                self._context.release(trace["id"])
+        return None, future, deadline
+
+    def get_context(
+        self,
+        trace: dict,
+        *,
+        timeout_ms: int = 1000,
+        cancel: threading.Event | None = None,
+    ):
+        """Return optional text within one total second; failures leave context empty."""
+        started = time.monotonic()
+        if os.getpid() != self._pid:
+            from .models import ContextResult
+
+            return ContextResult(reason="forked_process")
+        result, future, deadline = self._begin_context(
+            trace, timeout_ms, started, cancel
+        )
+        if result:
+            return result
+        while True:
+            if future.done():
+                return future.result()
+            self._context.tick(future, cancel is not None and cancel.is_set())
+            try:
+                return future.result(
+                    timeout=max(0, min(0.005, deadline - time.monotonic()))
+                )
+            except TimeoutError:
+                if time.monotonic() >= deadline:
+                    self._context.tick(future)
+                    return (
+                        future.result()
+                        if future.done()
+                        else self._context.empty("timeout", started)
+                    )
+
+    async def aget_context(
+        self,
+        trace: dict,
+        *,
+        timeout_ms: int = 1000,
+        cancel: threading.Event | None = None,
+    ):
+        started = time.monotonic()
+        if os.getpid() != self._pid:
+            from .models import ContextResult
+
+            return ContextResult(reason="forked_process")
+        result, future, deadline = self._begin_context(
+            trace, timeout_ms, started, cancel
+        )
+        if result:
+            return result
+        try:
+            while not future.done():
+                self._context.tick(future, cancel is not None and cancel.is_set())
+                if future.done():
+                    break
+                await asyncio.sleep(max(0, min(0.005, deadline - time.monotonic())))
+            return future.result()
+        except asyncio.CancelledError:
+            self._context.tick(future, True)
+            raise  # Preserve application cancellation, never turn it into a model call.
+
+    def release_trace(self, trace_id: str):
+        if os.getpid() != self._pid or type(trace_id) is not str:
+            return
+        try:
+            Wire.id(trace_id)
+        except ValueError:
+            return
+        with self._lock:
+            self._context.release(trace_id)
+            self._traces.pop(trace_id, None)
+            if trace_id not in self._recent:
+                self._remember(trace_id, None)
+            self._deliveries.cancel("canceled", trace_id)
+            if self._worker:
+                self._worker.release(trace_id)
+
+    def set_enabled(self, enabled: bool):
+        if os.getpid() != self._pid or type(enabled) is not bool:
+            return
+        with self._lock:
+            if self._closed or self._enabled == enabled:
+                return
+            self._enabled = enabled
+            self._context.set_enabled(enabled)
+            if not enabled:
+                for trace_id in list(self._traces):
+                    self.release_trace(trace_id)
+                self._deliveries.cancel("disabled")
+            if self._worker:
+                self._worker.set_enabled(enabled)
+
+    def flush(self, *, timeout_ms: int = 2000):
+        if os.getpid() != self._pid:
+            return FlushResult(unconfirmed=1)
+        return self._deliveries.flush(timeout_ms)
+
+    async def aflush(self, *, timeout_ms: int = 2000):
+        if os.getpid() != self._pid:
+            return FlushResult(unconfirmed=1)
+        return await self._deliveries.flush_async(timeout_ms)
+
+    def close(self, *, timeout_ms: int = 2000):
+        if os.getpid() != self._pid:
+            return FlushResult(unconfirmed=1)
+        with self._lock:
+            self._closed = True
+            self._context.stop()
+        result = self.flush(timeout_ms=timeout_ms)
+        self.dispose()
+        return result
+
+    def dispose(self):
+        if os.getpid() != self._pid:
+            return
+        with self._lock:
+            self._closed = True
+            self._context.stop()
+            self._traces.clear()
+            self._recent.clear()
+            self._deliveries.cancel("closed")
+            if self._worker:
+                self._worker.dispose()
+
+    def _worker_failed(self):
+        self._failed = True
+        self._context.stop("worker_failed")
+        self._deliveries.cancel("worker_failed")
+
+    def diagnostics(self):
+        if os.getpid() != self._pid:
+            return {"reason": "forked_process"}
+        with self._lock:
+            return {
+                **self._deliveries.diagnostics(),
+                "active_executions": len(self._traces),
+                "recent_executions": len(self._recent),
+            }
+
+    @staticmethod
+    def start_turn() -> TurnTimer:
+        return TurnTimer()