cortexdbai 0.4.3__tar.gz → 0.6.0__tar.gz

{cortexdbai-0.4.3 → cortexdbai-0.6.0}/.gitignore

@@ -77,6 +77,6 @@ blog/
 sales/
 videos/
 local-instance/
-
-# doc-claims verifier scratch output
-tools/verifier_out*/
+
+# doc-claims verifier scratch output
+tools/verifier_out*/

{cortexdbai-0.4.3 → cortexdbai-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexdbai
-Version: 0.4.3
+Version: 0.6.0
 Summary: The Long-Term Memory Layer for AI Systems
 Project-URL: Homepage, https://cortexdb.ai
 Project-URL: Documentation, https://docs.cortexdb.ai
@@ -173,6 +173,12 @@ print(c.recall(c.actor, query="what did I say?")["context_block"])
 c.experience("ws:demo", text="Deployed payments-service v3.1 to prod.")
 c.experience("ws:demo", text="Rolled back auth-gateway.", wait="indexed")
 
+# Large content: wait="captured" returns at the durable accept point (~10ms);
+# poll write_status to see indexing progress. After a client timeout,
+# found=False or status="failed" both mean re-sending is safe (re-processes).
+c.experience("ws:demo", text=big_transcript, idempotency_key="k1", wait="captured")
+c.write_status(idempotency_key="k1")  # {found, status, stages_completed, ...}
+
 # Recall — returns a StratifiedPack { context_block, layers, provenance }.
 pack = c.recall("ws:demo", query="recent deploys", view="holistic")
 

{cortexdbai-0.4.3 → cortexdbai-0.6.0}/README.md

@@ -60,6 +60,12 @@ print(c.recall(c.actor, query="what did I say?")["context_block"])
 c.experience("ws:demo", text="Deployed payments-service v3.1 to prod.")
 c.experience("ws:demo", text="Rolled back auth-gateway.", wait="indexed")
 
+# Large content: wait="captured" returns at the durable accept point (~10ms);
+# poll write_status to see indexing progress. After a client timeout,
+# found=False or status="failed" both mean re-sending is safe (re-processes).
+c.experience("ws:demo", text=big_transcript, idempotency_key="k1", wait="captured")
+c.write_status(idempotency_key="k1")  # {found, status, stages_completed, ...}
+
 # Recall — returns a StratifiedPack { context_block, layers, provenance }.
 pack = c.recall("ws:demo", query="recent deploys", view="holistic")
 

{cortexdbai-0.4.3 → cortexdbai-0.6.0}/cortexdb/__init__.py

@@ -1,71 +1,71 @@
-"""CortexDB Python SDK — the long-term memory layer for AI systems.
-
-The SDK is a thin HTTP client over the v1 API surface that cortexdb
-exposes by default on port 3141. The top-level :class:`Cortex` class
-(alias :class:`V1Client`) is what you should reach for.
-
-Quick start::
-
-    from cortexdb import Cortex
-
-    # Local docker run with no auth (CORTEX_API_KEY unset on the server):
-    with Cortex("http://localhost:3141") as c:
-        c.experience("ws:demo", text="Priya at Acme signed for 200 seats.")
-        pack = c.recall("ws:demo", query="How many seats did Acme sign for?")
-        print(pack)
-
-    # Hosted / multi-tenant deployment with PASETO bearer + actor header:
-    with Cortex(
-        "https://api-v1.cortexdb.ai",
-        actor="user:alice",
-        bearer="eyJ...",
-    ) as c:
-        out = c.answer(
-            "org:initech/user:alice",
-            question="What did Alice say about coffee?",
-        )
-
-Versions ≤ 0.2.x exposed a separate ``cortexdb.Cortex`` class targeting
-the legacy ``/v1/remember`` endpoints. That surface was retired in 0.3.0
-because the cortexdb binary's public port now only serves the v1 API;
-the legacy endpoints survive only as an internal bench-compat helper.
-If you need them, pin ``cortexdbai<0.3``.
-"""
-
-from cortexdb.v1 import V1Client, AsyncV1Client
-from cortexdb.v1.exceptions import (
-    V1APIError,
-    V1AuthError,
-    V1ConnectionError,
-    V1Error,
-    V1NotConfiguredError,
-    V1PolicyDeniedError,
-    V1RateLimitError,
-    V1TimeoutError,
-)
-from cortexdb import v1  # the explicit submodule namespace
-
-# Ergonomic top-level aliases. New code can write either form.
-Cortex = V1Client
-AsyncCortex = AsyncV1Client
-
-__version__ = "0.4.3"
-__all__ = [
-    # Clients (preferred top-level names)
-    "Cortex",
-    "AsyncCortex",
-    # Explicit v1 names (identical classes, kept for code that pinned them)
-    "V1Client",
-    "AsyncV1Client",
-    # Submodule
-    "v1",
-    # Exceptions
-    "V1Error",
-    "V1APIError",
-    "V1AuthError",
-    "V1ConnectionError",
-    "V1TimeoutError",
-    "V1RateLimitError",
-    "V1NotConfiguredError",
-    "V1PolicyDeniedError",
-]
+"""CortexDB Python SDK — the long-term memory layer for AI systems.
+
+The SDK is a thin HTTP client over the v1 API surface that cortexdb
+exposes by default on port 3141. The top-level :class:`Cortex` class
+(alias :class:`V1Client`) is what you should reach for.
+
+Quick start::
+
+    from cortexdb import Cortex
+
+    # Local docker run with no auth (CORTEX_API_KEY unset on the server):
+    with Cortex("http://localhost:3141") as c:
+        c.experience("ws:demo", text="Priya at Acme signed for 200 seats.")
+        pack = c.recall("ws:demo", query="How many seats did Acme sign for?")
+        print(pack)
+
+    # Hosted / multi-tenant deployment with PASETO bearer + actor header:
+    with Cortex(
+        "https://api-v1.cortexdb.ai",
+        actor="user:alice",
+        bearer="eyJ...",
+    ) as c:
+        out = c.answer(
+            "org:initech/user:alice",
+            question="What did Alice say about coffee?",
+        )
+
+Versions ≤ 0.2.x exposed a separate ``cortexdb.Cortex`` class targeting
+the legacy ``/v1/remember`` endpoints. That surface was retired in 0.3.0
+because the cortexdb binary's public port now only serves the v1 API;
+the legacy endpoints survive only as an internal bench-compat helper.
+If you need them, pin ``cortexdbai<0.3``.
+"""
+
+from cortexdb.v1 import V1Client, AsyncV1Client
+from cortexdb.v1.exceptions import (
+    V1APIError,
+    V1AuthError,
+    V1ConnectionError,
+    V1Error,
+    V1NotConfiguredError,
+    V1PolicyDeniedError,
+    V1RateLimitError,
+    V1TimeoutError,
+)
+from cortexdb import v1  # the explicit submodule namespace
+
+# Ergonomic top-level aliases. New code can write either form.
+Cortex = V1Client
+AsyncCortex = AsyncV1Client
+
+__version__ = "0.6.0"
+__all__ = [
+    # Clients (preferred top-level names)
+    "Cortex",
+    "AsyncCortex",
+    # Explicit v1 names (identical classes, kept for code that pinned them)
+    "V1Client",
+    "AsyncV1Client",
+    # Submodule
+    "v1",
+    # Exceptions
+    "V1Error",
+    "V1APIError",
+    "V1AuthError",
+    "V1ConnectionError",
+    "V1TimeoutError",
+    "V1RateLimitError",
+    "V1NotConfiguredError",
+    "V1PolicyDeniedError",
+]

{cortexdbai-0.4.3 → cortexdbai-0.6.0}/cortexdb/v1/client.py

@@ -148,6 +148,99 @@ def _envelope(
     return env
 
 
+# Per-action argument contract for POST /v1/conflicts/{id}/resolve. The
+# server rejects unknown shapes with a 422; validating client-side gives the
+# caller a `ValueError` naming the exact problem before any bytes move.
+_RESOLVE_ACTIONS: dict = {
+    "pick": {"required": ("winner",), "optional": ("reason",)},
+    "split": {"required": ("boundary", "earlier", "later"), "optional": ()},
+    "new_information": {"required": ("record",), "optional": ()},
+    "dismiss": {"required": (), "optional": ("reason",)},
+}
+
+
+def _resolve_conflict_body(action: str, kwargs: Mapping[str, Any]) -> dict:
+    """Validate + build the resolve-conflict request body.
+
+    ``kwargs`` maps every action-specific parameter name to its value (or
+    ``None`` when the caller didn't pass it). Raises :class:`ValueError` on
+    an unknown action, a missing required parameter, or a parameter that
+    doesn't belong to the chosen action.
+    """
+    spec = _RESOLVE_ACTIONS.get(action)
+    if spec is None:
+        raise ValueError(
+            f"unknown resolve action {action!r}; expected one of "
+            f"{sorted(_RESOLVE_ACTIONS)}"
+        )
+    allowed = set(spec["required"]) | set(spec["optional"])
+    provided = {k for k, v in kwargs.items() if v is not None}
+    missing = [k for k in spec["required"] if k not in provided]
+    if missing:
+        raise ValueError(f"action {action!r} requires {missing}")
+    extraneous = sorted(provided - allowed)
+    if extraneous:
+        raise ValueError(
+            f"action {action!r} does not accept {extraneous} "
+            f"(allowed: {sorted(allowed)})"
+        )
+    body: dict = {"action": action}
+    for k in allowed:
+        v = kwargs.get(k)
+        if v is not None:
+            body[k] = v
+    if action in ("pick", "dismiss") and "reason" not in body:
+        body["reason"] = ""
+    return body
+
+
+def _range_expr(value: Any) -> str:
+    """Normalize a bi-temporal range to the server's ``start..end`` string.
+
+    Accepts a preformatted ``"start..end"`` string or a 2-item
+    ``(start, end)`` sequence of date expressions.
+    """
+    if isinstance(value, str):
+        return value
+    try:
+        start, end = value
+    except (TypeError, ValueError) as e:
+        raise ValueError(
+            "range must be a 'start..end' string or a (start, end) pair"
+        ) from e
+    return f"{start}..{end}"
+
+
+def _claims_params(
+    scope: str,
+    *,
+    subject: Optional[str],
+    predicate: Optional[str],
+    valid_as_of: Optional[str],
+    known_as_of: Optional[str],
+    valid_during: Optional[Any],
+    recorded_during: Optional[Any],
+    limit: Optional[int],
+) -> dict:
+    """Build the query params for ``GET /v1/claims``."""
+    params: dict = {"scope": scope}
+    if subject:
+        params["subject"] = subject
+    if predicate:
+        params["predicate"] = predicate
+    if valid_as_of:
+        params["valid_as_of"] = valid_as_of
+    if known_as_of:
+        params["known_as_of"] = known_as_of
+    if valid_during is not None:
+        params["valid_during"] = _range_expr(valid_during)
+    if recorded_during is not None:
+        params["recorded_during"] = _range_expr(recorded_during)
+    if limit is not None:
+        params["limit"] = limit
+    return params
+
+
 # ── Synchronous client ──────────────────────────────────────────────────────
 
 
@@ -291,6 +384,28 @@ class V1Client:
         path = "/v1/experience" + (f"?wait={wait}" if wait else "")
         return self._post(path, env)
 
+    def write_status(
+        self,
+        *,
+        idempotency_key: Optional[str] = None,
+        event_id: Optional[str] = None,
+    ) -> dict:
+        """``GET /v1/experience/status`` — did a write land, and how far has
+        it progressed? The safe resume path after a client-side timeout, and
+        the poll target after ``experience(..., wait="captured")``.
+
+        Returns ``{found, event_id, status, stages_completed, note}`` where
+        ``status`` is ``"captured"`` / ``"indexed"`` / ``"failed"``.
+        ``found: False`` (or ``status: "failed"``) means re-sending the same
+        write with the same ``idempotency_key`` is safe — it re-processes
+        rather than replaying."""
+        params: dict = {}
+        if idempotency_key is not None:
+            params["idempotency_key"] = idempotency_key
+        if event_id is not None:
+            params["event_id"] = event_id
+        return self._get("/v1/experience/status", params=params)
+
     def upload_blob(
         self, data: bytes, content_type: str = "application/octet-stream"
     ) -> dict:
@@ -492,6 +607,130 @@ class V1Client:
         body: dict = {"scope": scope, "topics": list(topics) if topics else []}
         return self._post("/v1/understanding/synthesize", body)
 
+    # ── conflicts + bi-temporal claims ────────────────────────────────
+    #
+    # Rendering note: RecordView boundaries carry `valid_from_basis` /
+    # `valid_to_basis` ("stated" | "observed"). An "observed" boundary is
+    # only a knowledge bound — present it as "by <date>", never
+    # "on/since <date>".
+
+    def list_conflicts(
+        self,
+        scope: str,
+        *,
+        status: str = "open",
+        limit: int = 50,
+        cursor: Optional[int] = None,
+    ) -> dict:
+        """``GET /v1/conflicts`` — the conflict queue for a scope.
+
+        ``status`` is ``"open"`` (default) or ``"all"``. Returns
+        ``{conflicts: [ConflictView], total, next_cursor}``; pass
+        ``next_cursor`` back as ``cursor`` to page.
+        """
+        params: dict = {"scope": scope, "status": status, "limit": limit}
+        if cursor is not None:
+            params["cursor"] = cursor
+        return self._get("/v1/conflicts", params=params)
+
+    def get_conflict(self, conflict_id: str) -> dict:
+        """``GET /v1/conflicts/{id}`` — one conflict with full member
+        records."""
+        return self._get(f"/v1/conflicts/{conflict_id}")
+
+    def resolve_conflict(
+        self,
+        conflict_id: str,
+        action: str,
+        *,
+        winner: Optional[str] = None,
+        reason: Optional[str] = None,
+        boundary: Optional[str] = None,
+        earlier: Optional[str] = None,
+        later: Optional[str] = None,
+        record: Optional[str] = None,
+    ) -> dict:
+        """``POST /v1/conflicts/{id}/resolve`` — manually resolve a conflict.
+
+        Actions and their arguments:
+
+        * ``"pick"`` — ``winner`` (record UUID) required, ``reason`` optional.
+        * ``"split"`` — ``boundary`` (absolute date expression, e.g.
+          ``"2024-03"``), ``earlier`` and ``later`` (record UUIDs) required.
+        * ``"new_information"`` — ``record`` (record UUID) required.
+        * ``"dismiss"`` — ``reason`` optional.
+
+        Raises :class:`ValueError` on a bad action/argument combination.
+        Returns the post-resolution ``ConflictView``.
+        """
+        body = _resolve_conflict_body(
+            action,
+            {
+                "winner": winner,
+                "reason": reason,
+                "boundary": boundary,
+                "earlier": earlier,
+                "later": later,
+                "record": record,
+            },
+        )
+        return self._post(f"/v1/conflicts/{conflict_id}/resolve", body)
+
+    def query_claims(
+        self,
+        scope: str,
+        *,
+        subject: Optional[str] = None,
+        predicate: Optional[str] = None,
+        valid_as_of: Optional[str] = None,
+        known_as_of: Optional[str] = None,
+        valid_during: Optional[Any] = None,
+        recorded_during: Optional[Any] = None,
+        limit: Optional[int] = None,
+    ) -> dict:
+        """``GET /v1/claims`` — the two-axis bi-temporal record query
+        ("what was true at X, as known at Y").
+
+        * ``valid_as_of`` — world-time point (``"2023"``, ``"2023-06-01"``).
+          Defaults server-side to now.
+        * ``known_as_of`` — record-time point. Defaults server-side to now.
+        * ``valid_during`` / ``recorded_during`` — ranges; either a
+          ``"start..end"`` string or a ``(start, end)`` pair.
+
+        Returns ``{records: [RecordView]}``.
+        """
+        params = _claims_params(
+            scope,
+            subject=subject,
+            predicate=predicate,
+            valid_as_of=valid_as_of,
+            known_as_of=known_as_of,
+            valid_during=valid_during,
+            recorded_during=recorded_during,
+            limit=limit,
+        )
+        return self._get("/v1/claims", params=params)
+
+    def claim_history(self, scope: str, *, subject: str, predicate: str) -> dict:
+        """``GET /v1/claims/history`` — the full change-log of one claim:
+        every valid interval and record-time correction, plus any conflicts
+        involving the claim. Returns ``{claim, history, conflicts}``."""
+        return self._get(
+            "/v1/claims/history",
+            params={"scope": scope, "subject": subject, "predicate": predicate},
+        )
+
+    def belief_history(self, belief_id: str) -> dict:
+        """``GET /v1/beliefs/history`` — current belief + every superseded
+        semantic version, oldest first. Returns
+        ``{current, versions, revision_count}``."""
+        return self._get("/v1/beliefs/history", params={"belief_id": belief_id})
+
+    def concept_history(self, concept_id: str) -> dict:
+        """``GET /v1/concepts/{id}/history`` — current concept + superseded
+        semantic versions. Returns ``{current, versions}``."""
+        return self._get(f"/v1/concepts/{concept_id}/history")
+
     # ── forget + erasures ─────────────────────────────────────────────
 
     def forget(
@@ -798,6 +1037,100 @@ class AsyncV1Client:
             body["question_date"] = question_date
         return await self._post("/v1/answer", body)
 
+    # ── conflicts + bi-temporal claims ────────────────────────────────
+    # Same surface + semantics as the sync client; see V1Client for the
+    # full docstrings (including the "observed → by <date>" rendering rule).
+
+    async def list_conflicts(
+        self,
+        scope: str,
+        *,
+        status: str = "open",
+        limit: int = 50,
+        cursor: Optional[int] = None,
+    ) -> dict:
+        """``GET /v1/conflicts``. See :meth:`V1Client.list_conflicts`."""
+        params: dict = {"scope": scope, "status": status, "limit": limit}
+        if cursor is not None:
+            params["cursor"] = cursor
+        return await self._get("/v1/conflicts", params=params)
+
+    async def get_conflict(self, conflict_id: str) -> dict:
+        """``GET /v1/conflicts/{id}``. See :meth:`V1Client.get_conflict`."""
+        return await self._get(f"/v1/conflicts/{conflict_id}")
+
+    async def resolve_conflict(
+        self,
+        conflict_id: str,
+        action: str,
+        *,
+        winner: Optional[str] = None,
+        reason: Optional[str] = None,
+        boundary: Optional[str] = None,
+        earlier: Optional[str] = None,
+        later: Optional[str] = None,
+        record: Optional[str] = None,
+    ) -> dict:
+        """``POST /v1/conflicts/{id}/resolve``.
+        See :meth:`V1Client.resolve_conflict` for the per-action contract."""
+        body = _resolve_conflict_body(
+            action,
+            {
+                "winner": winner,
+                "reason": reason,
+                "boundary": boundary,
+                "earlier": earlier,
+                "later": later,
+                "record": record,
+            },
+        )
+        return await self._post(f"/v1/conflicts/{conflict_id}/resolve", body)
+
+    async def query_claims(
+        self,
+        scope: str,
+        *,
+        subject: Optional[str] = None,
+        predicate: Optional[str] = None,
+        valid_as_of: Optional[str] = None,
+        known_as_of: Optional[str] = None,
+        valid_during: Optional[Any] = None,
+        recorded_during: Optional[Any] = None,
+        limit: Optional[int] = None,
+    ) -> dict:
+        """``GET /v1/claims``. See :meth:`V1Client.query_claims`."""
+        params = _claims_params(
+            scope,
+            subject=subject,
+            predicate=predicate,
+            valid_as_of=valid_as_of,
+            known_as_of=known_as_of,
+            valid_during=valid_during,
+            recorded_during=recorded_during,
+            limit=limit,
+        )
+        return await self._get("/v1/claims", params=params)
+
+    async def claim_history(
+        self, scope: str, *, subject: str, predicate: str
+    ) -> dict:
+        """``GET /v1/claims/history``. See :meth:`V1Client.claim_history`."""
+        return await self._get(
+            "/v1/claims/history",
+            params={"scope": scope, "subject": subject, "predicate": predicate},
+        )
+
+    async def belief_history(self, belief_id: str) -> dict:
+        """``GET /v1/beliefs/history``. See :meth:`V1Client.belief_history`."""
+        return await self._get(
+            "/v1/beliefs/history", params={"belief_id": belief_id}
+        )
+
+    async def concept_history(self, concept_id: str) -> dict:
+        """``GET /v1/concepts/{id}/history``.
+        See :meth:`V1Client.concept_history`."""
+        return await self._get(f"/v1/concepts/{concept_id}/history")
+
     async def _get(
         self,
         path: str,