contexara 0.1.0__py3-none-any.whl

contexara/__init__.py

@@ -0,0 +1,46 @@
+from .async_client import AsyncContexara
+from .client import Contexara, MemoryAPI
+from .context import format_context_block
+from .errors import (
+    AuthenticationError,
+    ConflictError,
+    ConnectionError_,
+    ContexaraAPIError,
+    ContexaraError,
+    ContexaraTimeoutError,
+    PermissionDeniedError,
+    QuotaExceededError,
+    RateLimitError,
+    ResponseValidationError,
+    StreamError,
+    ValidationError,
+)
+from .models import AddResult, Entity, Memory, RetrieveResult, UploadEvent
+from .resilience import ResiliencePolicy
+from .testing import MockContexaraClient
+
+__all__ = [
+    "Contexara",
+    "AsyncContexara",
+    "MemoryAPI",
+    "Memory",
+    "Entity",
+    "RetrieveResult",
+    "AddResult",
+    "UploadEvent",
+    "ResiliencePolicy",
+    "MockContexaraClient",
+    "format_context_block",
+    "ContexaraError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "ValidationError",
+    "ConflictError",
+    "ConnectionError_",
+    "ContexaraTimeoutError",
+    "ResponseValidationError",
+    "StreamError",
+    "ContexaraAPIError",
+]

contexara/_capture.py

@@ -0,0 +1,370 @@
+"""_capture.py — builds the real CaptureEvent envelope /ingest expects,
+and tracks session_id/turn_number the same way a real hook does (see
+clients/installer/hook/platforms/cursor/hook.mjs's nextTurnNumber() and
+resolveSessionId() — session_id is the caller's own stable conversation
+identity, turn_number is a local, incrementing-per-session counter, not
+server-assigned).
+
+Two usage levels, per the build plan's section 7:
+  - Simple: memory.add(text) — the client auto-generates one default
+    session_id (constant for the life of the Contexara instance,
+    mirroring Cursor's "cursor-default" fallback) and allocates turn
+    numbers atomically from a local counter.
+  - Prepared/durable: memory.prepare_add(...) returns a fully-built,
+    serializable PreparedCaptureEvent an application can persist BEFORE
+    sending, and replay unchanged after a restart via memory.send(event)
+    — event_id/created_at/turn identity are frozen at prepare-time and
+    MUST NOT be regenerated on replay (see the contract's replay rule).
+
+REAL, CONFIRMED GAP (contract review, 2026-09-28): reusing an event_id
+with genuinely different content is NOT reliably caught server-side —
+platform/api/app/worker.py's is_event_already_ingested() dedup check
+returns before any content comparison ever runs. This module enforces
+the replay rule by construction (a PreparedCaptureEvent's fields are
+immutable once built; send() never mutates them) rather than relying on
+the server to catch a violation.
+"""
+from __future__ import annotations
+
+import threading
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+# Bounds the session registry for the life of one Contexara instance.
+# Every distinct session_id ever allocated (automatic or explicit)
+# counts against this once, permanently — see SessionTracker's own
+# docstring for why entries are never evicted to make room. Sized
+# generously (each entry is a small string key + a 2-tuple) so a real
+# long-lived process handling far more than 100,000 distinct sessions
+# over its lifetime is the only case that hits this limit.
+MAX_BOOKKEEPING_SESSIONS = 100_000
+
+
+def _iso_now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def derive_turn_id(turn_number: int) -> str:
+    """MUST match platform/api/app/schemas.py:CaptureEvent.derive_turn_id
+    exactly — the server independently re-derives this and rejects a
+    mismatch (409/worker failure)."""
+    return f"turn_{turn_number:06d}"
+
+
+@dataclass(frozen=True)
+class PreparedCaptureEvent:
+    """A fully-built, serializable CaptureEvent, ready to send or persist.
+    Every field is frozen at construction time — send() must never
+    mutate any of these before transmitting, since a retry after an
+    uncertain outcome must resend the exact original payload unchanged
+    (the contract's replay rule)."""
+
+    event_id: str
+    turn_id: str
+    session_id: str
+    turn_number: int
+    provider: str
+    capture_version: str
+    created_at: str
+    user_content: str | None
+    assistant_content: str | None
+    project_id: str | None = None
+    workspace_id: str | None = None
+
+    def to_wire(self) -> dict:
+        """The real CaptureEvent JSON body /ingest expects."""
+        return {
+            "event_id": self.event_id,
+            "event_type": "conversation_turn",
+            "event_version": "1.0",
+            "capture_version": self.capture_version,
+            "schema_version": "1.0",
+            "turn_id": self.turn_id,
+            "tenant_id": "unset",
+            "user_id": "unset",
+            "session_id": self.session_id,
+            "turn_number": self.turn_number,
+            "project_id": self.project_id,
+            "workspace_id": self.workspace_id,
+            "provider": self.provider,
+            "created_at": self.created_at,
+            "status": "complete",
+            "incomplete_reason": None,
+            "conversation": {
+                "user": {"timestamp": None, "content": self.user_content},
+                "assistant": {"timestamp": None, "content": self.assistant_content},
+            },
+            "metadata": {
+                "capture_client_version": self.capture_version,
+                "os": None,
+                "hook_event_names": [],
+            },
+        }
+
+    def to_dict(self) -> dict:
+        """Serializable representation for an application to persist
+        BEFORE sending, so it can replay this exact event after a
+        restart — a plain dict of this dataclass's own fields, not the
+        wire shape (to_wire() derives the wire shape from this, not the
+        other way around, so persisting to_dict()'s output and later
+        reconstructing via from_dict() round-trips exactly)."""
+        return {
+            "event_id": self.event_id,
+            "turn_id": self.turn_id,
+            "session_id": self.session_id,
+            "turn_number": self.turn_number,
+            "provider": self.provider,
+            "capture_version": self.capture_version,
+            "created_at": self.created_at,
+            "user_content": self.user_content,
+            "assistant_content": self.assistant_content,
+            "project_id": self.project_id,
+            "workspace_id": self.workspace_id,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "PreparedCaptureEvent":
+        return cls(**data)
+
+
+class SessionTracker:
+    """Owns default-session generation and per-session turn-number
+    allocation for ONE Contexara client instance. Not process-global —
+    two separate Contexara() instances get independent default sessions,
+    matching "one client instance = roughly one logical conversation
+    unless told otherwise", not "one process".
+
+    Thread-safe: allocate_turn() is the one method under concurrent-call
+    risk (two threads calling memory.add() on the same client at once),
+    guarded by a lock so two calls never observe/reuse the same
+    turn_number for the same session_id.
+
+    REAL BUG FIXED 2026-09-28 (Codex review, round 3, THIRD pass): the
+    previous two fixes both tried to patch the eviction/forgetting
+    design instead of replacing it, and both were reproduced broken by
+    Codex before this rewrite:
+
+    - Pass 1 (TTL + idle eviction): a bounded "recently evicted" set
+      rolled its oldest entry off under sustained churn, letting an
+      evicted session_id look brand-new again once enough OTHER
+      sessions had also been evicted.
+    - Pass 2 (unbounded evicted/explicit sets): fixed that, but (a)
+      broke explicit → explicit continuation (the check treated ANY
+      prior explicit allocation as a mode conflict, not just a prior
+      AUTOMATIC one — a session doing turn 1, 2, 3 all via
+      explicit_turn_number was incorrectly rejected on turn 2), and
+      (b) two separate unbounded sets meant total bookkeeping grew
+      without limit for the tracker's lifetime — not a configured
+      bound, regardless of how "non-adversarial" normal traffic is.
+      Reproduced directly by Codex: max_sessions=2, 100 distinct
+      explicitly-allocated session_ids → 100 retained forever.
+
+    This pass replaces BOTH bounded-forgetting and unbounded-growth
+    with the single design Codex specified: one bounded registry,
+    keyed by session_id, storing (mode, turn_number | None). Entries
+    are NEVER evicted for the life of this tracker instance — there is
+    no TTL, no idle sweep, no eviction of any kind. The only thing
+    max_sessions governs is whether *registering a brand-new*
+    session_id is allowed; every session_id already in the registry,
+    of either mode, continues working for as long as the process runs.
+    This is a real, fixed, configured bound (not "bounded in practice
+    by non-adversarial traffic" — an argument Codex correctly rejected,
+    since session_ids are caller-supplied and ordinary traffic alone
+    can exhaust an unbounded set). A caller who legitimately needs more
+    than max_sessions distinct sessions across one client's lifetime is
+    the resuming-in-another-process case this class's own
+    explicit_turn_number parameter already exists for — that path is
+    unaffected by capacity, since resuming callers manage their own
+    state and never need a REGISTRY entry to keep working correctly
+    (see allocate_turn's own docstring)."""
+
+    def __init__(self, *, max_sessions: int | None = None) -> None:
+        self._lock = threading.Lock()
+        self._default_session_id: str | None = None
+        # session_id -> (mode, turn_number). mode is "automatic" or
+        # "explicit". For "explicit" entries, turn_number is None — an
+        # explicit caller manages their own numbers, this registry only
+        # needs to remember WHICH mode the session is locked to, not
+        # any particular number. Never evicted, never shrinks, for the
+        # life of this tracker instance — see this class's own
+        # docstring for why that is the actual fix, not a regression.
+        self._sessions: dict[str, tuple[str, int | None]] = {}
+        self._max_sessions = max_sessions if max_sessions is not None else MAX_BOOKKEEPING_SESSIONS
+
+    def default_session_id(self) -> str:
+        """Lazily generates one default session_id, stable for the life
+        of this tracker instance — mirrors Cursor's own
+        resolveSessionId() fallback ("cursor-default"): a single,
+        consistent conversation identity used when the caller has no
+        more specific one to offer, not a fresh id manufactured per
+        call (which would make every add() its own isolated one-turn
+        session, defeating the point of a session concept at all)."""
+        with self._lock:
+            if self._default_session_id is None:
+                self._default_session_id = f"sdk-{uuid.uuid4().hex[:12]}"
+            return self._default_session_id
+
+    def allocate_turn(self, session_id: str, *, explicit_turn_number: int | None = None) -> int:
+        """Returns the next turn_number for session_id, starting at 1,
+        incrementing per call — the same real allocation rule
+        nextTurnNumber() implements for hook clients. Atomic under
+        concurrent calls via the instance lock.
+
+        explicit_turn_number: caller-managed allocation, for a
+        distributed application that tracks its own durable
+        session/turn state externally (e.g. after a process restart,
+        or across multiple worker processes sharing one logical
+        session) — bypasses this tracker's local counter entirely.
+        A session_id is permanently locked to whichever mode
+        (automatic or explicit) its FIRST allocate_turn() call used,
+        for the life of this tracker instance:
+
+        - automatic → automatic: increments and returns the local
+          counter, as always.
+        - explicit → explicit: REAL BUG FIXED 2026-09-28 (Codex review,
+          round 3, third pass, reproduced directly): an earlier version
+          of this check rejected ANY session_id that had ever seen an
+          explicit call, including a second, third, etc. explicit call
+          for the SAME session_id — "explicit turn 1" then "explicit
+          turn 2" for one conversation incorrectly raised. Explicit
+          mode does not update this registry's own counter (the caller
+          owns their own numbers), so repeated explicit calls for an
+          explicit-mode session are always allowed; only a MODE SWITCH
+          (automatic session receiving an explicit call, or vice versa)
+          is rejected.
+        - either mode switching to the other: raises ValidationError —
+          silently mixing the two would desynchronize this tracker's
+          local counter from whatever the caller (or the server) is
+          separately tracking.
+
+        Raises ValidationError if registering session_id would exceed
+        max_sessions. This registry never evicts an entry once
+        created — see this class's own docstring for why "bounded, but
+        forgets old entries" was the actual defect being fixed across
+        the last two rounds, not a feature. A caller who legitimately
+        needs more than max_sessions distinct session_ids across one
+        client instance's lifetime should pass explicit_turn_number
+        (which never touches the registry once a session_id is already
+        registered in explicit mode) or construct a new client
+        instance."""
+        from .errors import ValidationError
+
+        with self._lock:
+            existing = self._sessions.get(session_id)
+
+            if explicit_turn_number is not None:
+                if existing is not None and existing[0] != "explicit":
+                    raise ValidationError(
+                        f"session_id {session_id!r} already has an active local turn counter "
+                        f"from automatic allocation — passing an explicit_turn_number for it now "
+                        f"would desynchronize the two. Use one allocation strategy per session "
+                        f"consistently, not both."
+                    )
+                if existing is None:
+                    self._reserve_capacity(session_id)
+                    self._sessions[session_id] = ("explicit", None)
+                return explicit_turn_number
+
+            if existing is not None and existing[0] == "explicit":
+                raise ValidationError(
+                    f"session_id {session_id!r} was previously allocated an explicit_turn_number "
+                    f"— switching to automatic allocation for it now would desynchronize the two. "
+                    f"Use one allocation strategy per session consistently, not both."
+                )
+
+            if existing is not None:
+                next_turn = (existing[1] or 0) + 1
+                self._sessions[session_id] = ("automatic", next_turn)
+                return next_turn
+
+            self._reserve_capacity(session_id)
+            self._sessions[session_id] = ("automatic", 1)
+            return 1
+
+    def _reserve_capacity(self, session_id: str) -> None:
+        """Raises if registering a brand-new session_id would exceed
+        max_sessions. Only called when session_id is NOT already in
+        the registry — an already-registered session_id (either mode)
+        never needs capacity, since it does not grow the registry."""
+        from .errors import ValidationError
+
+        if len(self._sessions) >= self._max_sessions:
+            raise ValidationError(
+                f"session_id {session_id!r} cannot be registered: this client is already "
+                f"tracking {self._max_sessions} other session_ids for its lifetime, and this "
+                f"registry never forgets a session_id once created (see SessionTracker's own "
+                f"docstring for why unbounded-with-forgetting was rejected as unsafe). Either "
+                f"reuse an already-registered session_id, pass an explicit_turn_number for a "
+                f"session_id whose turns you track yourself, or construct a new client instance."
+            )
+
+
+# Real, documented limits — platform/api/app/schemas.py:18,22
+# (MAX_MESSAGE_CONTENT_CHARS, MAX_IDENTIFIER_CHARS). REAL GAP CLOSED
+# 2026-09-28 (Codex review): prepare_add() previously sent blank
+# content and over-limit content straight to the network, where the
+# server would reject it with a 422 — a real, avoidable round trip for
+# an error the SDK can and should catch immediately.
+MAX_MESSAGE_CONTENT_CHARS = 100_000
+MAX_IDENTIFIER_CHARS = 512
+
+
+def build_prepared_event(
+    tracker: SessionTracker,
+    *,
+    text: str,
+    assistant_message: str | None,
+    session_id: str | None,
+    project_id: str | None,
+    workspace_id: str | None,
+    provider: str,
+    capture_version: str,
+    turn_number: int | None = None,
+) -> PreparedCaptureEvent:
+    from .errors import ValidationError
+
+    if not text or not text.strip():
+        raise ValidationError("text must not be blank")
+    if len(text) > MAX_MESSAGE_CONTENT_CHARS:
+        raise ValidationError(
+            f"text is {len(text)} chars, over the real {MAX_MESSAGE_CONTENT_CHARS}-char limit "
+            f"the server enforces per message."
+        )
+    if assistant_message is not None and len(assistant_message) > MAX_MESSAGE_CONTENT_CHARS:
+        raise ValidationError(
+            f"assistant_message is {len(assistant_message)} chars, over the real "
+            f"{MAX_MESSAGE_CONTENT_CHARS}-char limit the server enforces per message."
+        )
+    if session_id is not None and len(session_id) > MAX_IDENTIFIER_CHARS:
+        raise ValidationError(f"session_id is over the real {MAX_IDENTIFIER_CHARS}-char identifier limit.")
+    # REAL GAP CLOSED (schema reconciliation, release plan step 2):
+    # shared/schemas/capture_event.schema.json declares turn_number's
+    # real minimum as 1, and derive_turn_id's "turn_%06d" format
+    # produces a malformed turn_id (fails the schema's own
+    # ^turn_[0-9]{6}$ regex) for turn_number <= 0 — e.g. turn_number=-1
+    # formats as "turn_-00001", not six digits. Neither the backend
+    # Pydantic model NOR this SDK enforced turn_number >= 1 before this
+    # fix, making it reachable via this exact explicit_turn_number
+    # parameter with no server-side backstop. The Node SDK already
+    # enforced this (capture.ts's fromPersistable); this brings the
+    # Python SDK to parity and catches the error at prepare_add()/add()
+    # time instead of only via a confusing later ID-format failure.
+    if turn_number is not None and turn_number < 1:
+        raise ValidationError(f"turn_number must be >= 1, got {turn_number}.")
+
+    resolved_session_id = session_id or tracker.default_session_id()
+    turn_number = tracker.allocate_turn(resolved_session_id, explicit_turn_number=turn_number)
+    return PreparedCaptureEvent(
+        event_id=f"evt_{uuid.uuid4()}",
+        turn_id=derive_turn_id(turn_number),
+        session_id=resolved_session_id,
+        turn_number=turn_number,
+        provider=provider,
+        capture_version=capture_version,
+        created_at=_iso_now(),
+        user_content=text,
+        assistant_content=assistant_message,
+        project_id=project_id,
+        workspace_id=workspace_id,
+    )

contexara/_sse.py

@@ -0,0 +1,110 @@
+"""_sse.py — parses the real /upload SSE protocol described in
+platform/sdk/contracts/PUBLIC_API_CONTRACT.md's upload section and
+exercised by fixtures/upload_sse_stream.json.
+
+Real frame shape: `data: {json}\n\n` (or `\r\n\r\n`), terminated by a
+literal `data: [DONE]\n\n` frame. An `{"error": ...}` frame may appear
+before [DONE] — [DONE] following an error frame does NOT mean success;
+callers must check for an error frame having been seen, not just for
+stream completion.
+
+This is a pure, transport-agnostic byte-accumulator: feed it raw bytes
+in whatever chunks arrive from the network (which may split a frame
+anywhere, including mid-multibyte-UTF-8-character), and it yields
+complete, parsed UploadEvent-shaped dicts as they become available.
+Kept separate from client.py so the same parser backs both the sync and
+async upload() implementations without duplicating this logic.
+"""
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+
+from .errors import StreamError
+
+
+class SSEFrameParser:
+    """Stateful, incremental parser. Call feed(chunk) with each raw byte
+    chunk as it arrives; each call yields zero or more fully-parsed
+    frame dicts. Call finish() once the stream ends to detect a
+    connection drop with no [DONE] (a real protocol violation, distinct
+    from a clean error-then-done sequence)."""
+
+    def __init__(self) -> None:
+        self._buffer = b""
+        self._decoder_leftover = b""
+        self._saw_done = False
+        self._error_frame: str | None = None
+        self._last_metadata: dict | None = None
+
+    def feed(self, chunk: bytes) -> Iterator[dict]:
+        self._buffer += chunk
+        # Normalize CRLF to LF once, on the accumulated buffer, so the
+        # frame-splitting logic below only needs to handle one line
+        # ending — real servers may use either per the contract.
+        normalized = self._buffer.replace(b"\r\n", b"\n")
+        # A complete frame is terminated by a blank line (\n\n). Split
+        # on that, keep the last (possibly incomplete) piece buffered
+        # for the next feed() call — this is what makes a frame split
+        # across two network reads reassemble correctly.
+        parts = normalized.split(b"\n\n")
+        self._buffer = parts[-1]
+        for raw_frame in parts[:-1]:
+            event = self._parse_frame(raw_frame)
+            if event is not None:
+                yield event
+
+    def _parse_frame(self, raw_frame: bytes) -> dict | None:
+        # A real frame is one or more `data: ...` lines. REAL BUG FIXED
+        # 2026-09-28 (Codex review): multiple data: lines were joined
+        # with NO separator (b"".join), which is not what the SSE spec
+        # requires — per the WHATWG spec, each data: line's value gets
+        # a "\n" appended before the next line's value, not
+        # concatenated directly. This protocol's real frames today are
+        # always single-line, so this had no observed practical effect
+        # yet, but a multiline frame would have silently corrupted the
+        # decoded JSON (e.g. two numbers on adjacent lines merging into
+        # one digit string with no separator).
+        lines = raw_frame.split(b"\n")
+        data_parts = [ln[len(b"data:"):].lstrip() for ln in lines if ln.startswith(b"data:")]
+        if not data_parts:
+            return None  # a comment/keepalive line with no data: prefix
+        payload = b"\n".join(data_parts)
+        text = payload.decode("utf-8")
+        if text == "[DONE]":
+            self._saw_done = True
+            return {"done": True}
+        try:
+            obj = json.loads(text)
+        except json.JSONDecodeError as exc:
+            raise StreamError(f"malformed SSE data frame: {text!r}: {exc}") from None
+        if "error" in obj:
+            self._error_frame = obj["error"]
+        if "content_hash" in obj or "attachment_id" in obj:
+            self._last_metadata = obj
+        return obj
+
+    def finish(self) -> None:
+        """Call once the underlying stream has ended (EOF). Raises
+        StreamError if the stream ended without a [DONE] frame (a
+        protocol violation — connection drop or server crash mid-
+        stream) or if an error frame was seen at any point (regardless
+        of whether [DONE] followed it — DONE's presence alone never
+        means success)."""
+        if self._error_frame is not None:
+            meta = self._last_metadata or {}
+            raise StreamError(
+                self._error_frame,
+                content_hash=meta.get("content_hash"),
+                duplicate=meta.get("duplicate"),
+                attachment_id=meta.get("attachment_id"),
+            )
+        if not self._saw_done:
+            meta = self._last_metadata or {}
+            raise StreamError(
+                "upload stream ended without a [DONE] frame (connection drop or "
+                "server error mid-stream)",
+                content_hash=meta.get("content_hash"),
+                duplicate=meta.get("duplicate"),
+                attachment_id=meta.get("attachment_id"),
+            )