cortexdbai 0.4.3__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexdbai
-Version: 0.4.3
+Version: 0.5.0
 Summary: The Long-Term Memory Layer for AI Systems
 Project-URL: Homepage, https://cortexdb.ai
 Project-URL: Documentation, https://docs.cortexdb.ai

{cortexdbai-0.4.3 → cortexdbai-0.5.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 ──────────────────────────────────────────────────────
 
 
@@ -492,6 +585,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 +1015,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,