cortexdbai 0.10.4__tar.gz → 0.11.0__tar.gz

{cortexdbai-0.10.4 → cortexdbai-0.11.0}/.gitignore

@@ -88,7 +88,14 @@ benchmarks/data_*/
 benchmarks/**/fast_results/
 data_*/
 *_data/
+*_data_20*/
 cortexdb_data*/
 server_results/
 *.log
 docker_build.log
+
+# local gate/bench data stores
+gate*_data_*/
+
+# Code-plane benchmark local run outputs (official results are committed deliberately)
+benchmarks/codeplane/runs/

{cortexdbai-0.10.4 → cortexdbai-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: cortexdbai
-Version: 0.10.4
+Version: 0.11.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.10.4 → cortexdbai-0.11.0}/cortexdb/__init__.py

@@ -36,6 +36,7 @@ from cortexdb.v1 import V1Client, AsyncV1Client
 from cortexdb.v1.exceptions import (
     V1APIError,
     V1AuthError,
+    V1InvalidRequestError,
     V1ConnectionError,
     V1Error,
     V1NotConfiguredError,
@@ -49,7 +50,7 @@ from cortexdb import v1  # the explicit submodule namespace
 Cortex = V1Client
 AsyncCortex = AsyncV1Client
 
-__version__ = "0.10.4"
+__version__ = "0.11.0"
 __all__ = [
     # Clients (preferred top-level names)
     "Cortex",
@@ -63,6 +64,7 @@ __all__ = [
     "V1Error",
     "V1APIError",
     "V1AuthError",
+    "V1InvalidRequestError",
     "V1ConnectionError",
     "V1TimeoutError",
     "V1RateLimitError",

{cortexdbai-0.10.4 → cortexdbai-0.11.0}/cortexdb/v1/__init__.py

@@ -38,6 +38,7 @@ from cortexdb.v1.client import AsyncV1Client, V1Client
 from cortexdb.v1.exceptions import (
     V1APIError,
     V1AuthError,
+    V1InvalidRequestError,
     V1ConnectionError,
     V1Error,
     V1NotConfiguredError,
@@ -52,6 +53,7 @@ __all__ = [
     "V1Error",
     "V1APIError",
     "V1AuthError",
+    "V1InvalidRequestError",
     "V1ConnectionError",
     "V1TimeoutError",
     "V1RateLimitError",

{cortexdbai-0.10.4 → cortexdbai-0.11.0}/cortexdb/v1/client.py

@@ -28,6 +28,7 @@ except ImportError:
 from cortexdb.v1.exceptions import (
     V1APIError,
     V1ConnectionError,
+    V1InvalidRequestError,
     V1TimeoutError,
 )
 
@@ -237,6 +238,21 @@ def _forget_body(
     if memory_ids:
         selector["memory_ids"] = list(memory_ids)
     if selector:
+        # KAN-146: `confirm_all` authorizes a SCOPE-WIDE operation; combined
+        # with a selector it is ambiguous ("delete these ids" vs "delete
+        # everything") and the server refuses it with
+        # AMBIGUOUS_SELECTOR_CONFIRM_ALL. Refuse it here instead, so a
+        # caller that wires both up never reaches a destructive endpoint and
+        # gets a message that names the two supported modes.
+        if confirm_all:
+            raise V1InvalidRequestError(
+                "AMBIGUOUS_SELECTOR_CONFIRM_ALL",
+                "selector + confirm_all is ambiguous: confirm_all authorizes "
+                "a scope-wide operation and would ignore the selector. Send "
+                "confirm_all=False (or omit it) to delete exactly the "
+                "selected memories, or pass no selector with "
+                "confirm_all=True for a scope-wide forget",
+            )
         body["selector"] = selector
     if reason:
         body["reason"] = reason
@@ -256,6 +272,17 @@ def _erasure_body(
     and the server refuses them here."""
     body: dict = {"scope": scope, "confirm_all": confirm_all}
     if memory_ids:
+        # KAN-146: same rule as /v1/forget — confirm_all authorizes a
+        # WHOLE-SCOPE erasure and is only valid with an empty selector. The
+        # server refuses the combination (AMBIGUOUS_SELECTOR); refuse it
+        # before the irreversible call is made.
+        if confirm_all:
+            raise V1InvalidRequestError(
+                "AMBIGUOUS_SELECTOR",
+                "confirm_all=True is only valid with an EMPTY selector "
+                "(whole-scope erasure); to erase specific records pass "
+                "memory_ids WITHOUT confirm_all",
+            )
         body["selector"] = {"memory_ids": list(memory_ids)}
     if audit_note:
         body["audit_note"] = audit_note
@@ -418,6 +445,8 @@ class V1Client:
         self.timeout = timeout
         self._session = requests.Session()
         self._session.headers.update(_build_headers(actor, bearer))
+        #: ``client.code.*`` — the Code Intelligence Plane (T-906).
+        self.code = CodeNamespace(self)
 
     # ── auth ──────────────────────────────────────────────────────────
 
@@ -1917,3 +1946,212 @@ class AsyncV1Client:
 
     async def __aexit__(self, *_) -> None:
         await self.aclose()
+
+
+class CodeNamespace:
+    """``client.code.*`` — the Code Intelligence Plane (T-906).
+
+    Thin typed wrappers over ``/v1/code/*``. Requires the "Code memory"
+    feature bundle on the server; with it off every call raises the
+    server's 503. Envelopes and certificates pass through verbatim —
+    coverage, uncertainty and warnings reach your code unedited.
+
+    Example::
+
+        client = V1Client("http://localhost:3141", bearer=token)
+        client.code.register_repo("shop", "/path/to/checkout")
+        ctx = client.code.context("shop", "how does settlement work?")
+        for item in ctx["envelope"]["items"]:
+            print(item["citation"])
+    """
+
+    def __init__(self, client: "V1Client") -> None:
+        self._client = client
+
+    def register_repo(self, name: str, path: str) -> dict:
+        """``POST /v1/code/repos`` — register + index a local checkout."""
+        return self._client._post("/v1/code/repos", {"name": name, "path": path})
+
+    def repos(self) -> dict:
+        """``GET /v1/code/repos`` — every repo this tenant registered."""
+        return self._client._get("/v1/code/repos")
+
+    def repo_status(self, name: str) -> dict:
+        """``GET /v1/code/repos/{name}`` — snapshot, stats, scope."""
+        return self._client._get(f"/v1/code/repos/{name}")
+
+    def remove_repo(self, name: str) -> dict:
+        """``DELETE /v1/code/repos/{name}``."""
+        client = self._client
+        try:
+            r = client._session.delete(
+                f"{client.api_url}/v1/code/repos/{name}", timeout=client.timeout
+            )
+        except requests.Timeout as e:
+            raise V1TimeoutError(str(e)) from e
+        except requests.ConnectionError as e:
+            raise V1ConnectionError(str(e)) from e
+        _raise_for_response(r.status_code, r.text)
+        return r.json() if r.text else {}
+
+    def resolve_symbol(self, repo: str, name: str, *, limit: int = 50) -> dict:
+        """``GET /v1/code/symbol/resolve`` — every in-scope match; an
+        ambiguous name returns ALL candidates, never a guess."""
+        return self._client._get(
+            "/v1/code/symbol/resolve",
+            params={"repo": repo, "name": name, "limit": limit},
+        )
+
+    def calls(
+        self,
+        repo: str,
+        symbol: str,
+        *,
+        direction: str = "out",
+        depth: int = 1,
+        include_dynamic: bool = False,
+    ) -> dict:
+        """``GET /v1/code/calls`` — call edges, tier-labeled; dynamic
+        dispatch fan-out only with ``include_dynamic=True``."""
+        return self._client._get(
+            "/v1/code/calls",
+            params={
+                "repo": repo,
+                "symbol": symbol,
+                "direction": direction,
+                "depth": depth,
+                "include_dynamic": str(include_dynamic).lower(),
+            },
+        )
+
+    def impact(self, repo: str, symbol: str, *, depth: int = 3) -> dict:
+        """``GET /v1/code/impact`` — reverse closure; each reached symbol
+        reports hops and the WEAKEST precision tier on its path."""
+        return self._client._get(
+            "/v1/code/impact", params={"repo": repo, "symbol": symbol, "depth": depth}
+        )
+
+    def graph_query(
+        self,
+        repo: str,
+        roots: list[str],
+        *,
+        predicates: Optional[list[str]] = None,
+        direction: str = "outgoing",
+        depth: int = 1,
+        max_nodes: int = 250,
+        max_edges: int = 500,
+        include_dynamic: bool = False,
+    ) -> dict:
+        """``POST /v1/code/graph/query`` — a bounded multi-predicate
+        traversal with tier and status retained on every edge."""
+        return self._client._post(
+            "/v1/code/graph/query",
+            {
+                "repo": repo,
+                "roots": roots,
+                "predicates": predicates or ["calls"],
+                "direction": direction,
+                "depth": depth,
+                "max_nodes": max_nodes,
+                "max_edges": max_edges,
+                "include_dynamic": include_dynamic,
+            },
+        )
+
+    def inventory(
+        self,
+        repo: str,
+        kind: str,
+        *,
+        limit: int = 200,
+        cursor: Optional[int] = None,
+    ) -> dict:
+        """``POST /v1/code/inventory`` — bounded definitions, routes,
+        architecture, or unreferenced-definition candidates without a full
+        database scan."""
+        body = {"repo": repo, "kind": kind, "limit": limit}
+        if cursor is not None:
+            body["cursor"] = cursor
+        return self._client._post("/v1/code/inventory", body)
+
+    def context(
+        self,
+        repo: str,
+        task: str,
+        *,
+        changed_paths: Optional[list] = None,
+        token_budget: int = 2000,
+    ) -> dict:
+        """``POST /v1/code/context`` — the task/diff evidence envelope:
+        verbatim snippets with citations, coverage, uncertainty notes and
+        pre-action warnings, under a hard token budget."""
+        return self._client._post(
+            "/v1/code/context",
+            {
+                "repo": repo,
+                "task": task,
+                "changed_paths": changed_paths or [],
+                "token_budget": token_budget,
+            },
+        )
+
+    def workspace_context(
+        self,
+        task: str,
+        *,
+        repos: Optional[list[str]] = None,
+        changed_paths: Optional[dict[str, list[str]]] = None,
+        token_budget: int = 2000,
+    ) -> dict:
+        """``POST /v1/code/workspace/context`` — one tenant-scoped,
+        token-budgeted context query across selected repositories. Empty
+        ``repos`` searches every repository visible to the caller."""
+        return self._client._post(
+            "/v1/code/workspace/context",
+            {
+                "repos": repos or [],
+                "task": task,
+                "changed_paths": changed_paths or {},
+                "token_budget": token_budget,
+            },
+        )
+
+    def coverage_status(self, repo: str) -> dict:
+        """``GET /v1/code/coverage/status``."""
+        return self._client._get("/v1/code/coverage/status", params={"repo": repo})
+
+    def history_for_symbol(
+        self, repo: str, name: str, *, cursor: Optional[int] = None, limit: int = 50
+    ) -> dict:
+        """``GET /v1/code/history/for-symbol`` — lineage-merged events,
+        newest first, cursor-paginated."""
+        params: dict = {"repo": repo, "name": name, "limit": limit}
+        if cursor is not None:
+            params["cursor"] = cursor
+        return self._client._get("/v1/code/history/for-symbol", params=params)
+
+    def tests_for_change(self, repo: str, name: str) -> dict:
+        """``GET /v1/code/tests/for-change`` — rows labeled static
+        (reachability) vs observed (recorded coverage); absent coverage
+        is disclosed, never upgraded."""
+        return self._client._get(
+            "/v1/code/tests/for-change", params={"repo": repo, "name": name}
+        )
+
+    def certify(self, repo: str, question: str, symbol: str) -> dict:
+        """``POST /v1/code/certify`` — ``list-implementations`` or
+        ``count-call-sites``; returns a hash-verified certificate or
+        ``incomplete`` with reasons."""
+        return self._client._post(
+            "/v1/code/certify", {"repo": repo, "question": question, "symbol": symbol}
+        )
+
+    def gc(self, repo: str) -> dict:
+        """``POST /v1/code/gc`` — one two-phase GC cycle; the report
+        enumerates every destructive step."""
+        return self._client._post("/v1/code/gc", {"repo": repo})
+
+    def matrix(self) -> dict:
+        """``GET /v1/code/matrix`` — the earned capability matrix."""
+        return self._client._get("/v1/code/matrix")

{cortexdbai-0.10.4 → cortexdbai-0.11.0}/cortexdb/v1/exceptions.py

@@ -63,6 +63,27 @@ class V1APIError(V1Error):
         )
 
 
+class V1InvalidRequestError(V1APIError):
+    """Client-side refusal, raised BEFORE any network call.
+
+    The request is self-contradictory in a way the server also refuses, so
+    the SDK stops it locally rather than sending it — nothing is mutated and
+    the caller gets the same ``error_code`` the server would return.
+    Subclasses :class:`V1APIError` (with ``status=400``) so existing
+    ``except V1APIError`` handlers keep working.
+    """
+
+    def __init__(self, error_code: str, message: str):
+        super().__init__(
+            status=400,
+            error_code=error_code,
+            message=message,
+            request_id=None,
+            details=None,
+            retriable=False,
+        )
+
+
 class V1AuthError(V1APIError):
     """401 — missing/invalid token, actor mismatch, revoked token, wrong tenant."""
 

{cortexdbai-0.10.4 → cortexdbai-0.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cortexdbai"
-version = "0.10.4"
+version = "0.11.0"
 description = "The Long-Term Memory Layer for AI Systems"
 readme = "README.md"
 license = "Apache-2.0"

cortexdbai-0.11.0/tests/test_code_namespace.py

@@ -0,0 +1,104 @@
+"""T-906: ``client.code.*`` mirrors the /v1/code surface."""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+from cortexdb.v1.client import V1Client
+
+
+def _client() -> V1Client:
+    return V1Client("http://localhost:3141", actor="user:test")
+
+
+class TestCodeNamespace:
+    def test_namespace_is_attached(self) -> None:
+        client = _client()
+        assert hasattr(client, "code")
+
+    def test_reads_route_to_the_right_paths(self) -> None:
+        client = _client()
+        calls: list[tuple] = []
+
+        def fake_get(path, *, params=None):
+            calls.append(("GET", path, dict(params or {})))
+            return {"ok": True}
+
+        with patch.object(client, "_get", side_effect=fake_get):
+            client.code.repos()
+            client.code.repo_status("shop")
+            client.code.resolve_symbol("shop", "settle")
+            client.code.calls("shop", "settle", direction="in", depth=2)
+            client.code.impact("shop", "settle", depth=4)
+            client.code.coverage_status("shop")
+            client.code.history_for_symbol("shop", "settle", cursor=3)
+            client.code.tests_for_change("shop", "settle")
+            client.code.matrix()
+        paths = [c[1] for c in calls]
+        assert paths == [
+            "/v1/code/repos",
+            "/v1/code/repos/shop",
+            "/v1/code/symbol/resolve",
+            "/v1/code/calls",
+            "/v1/code/impact",
+            "/v1/code/coverage/status",
+            "/v1/code/history/for-symbol",
+            "/v1/code/tests/for-change",
+            "/v1/code/matrix",
+        ]
+        calls_params = calls[3][2]
+        assert calls_params["direction"] == "in"
+        assert calls_params["depth"] == 2
+        assert calls[6][2]["cursor"] == 3
+
+    def test_writes_route_with_bodies(self) -> None:
+        client = _client()
+        posts: list[tuple] = []
+
+        def fake_post(path, body):
+            posts.append((path, body))
+            return {"ok": True}
+
+        with patch.object(client, "_post", side_effect=fake_post):
+            client.code.register_repo("shop", "/src/shop")
+            client.code.context(
+                "shop", "how does settle work?", changed_paths=["a.ts"], token_budget=500
+            )
+            client.code.workspace_context(
+                "trace the request",
+                repos=["api", "worker"],
+                changed_paths={"api": ["src/client.ts"]},
+                token_budget=900,
+            )
+            client.code.graph_query(
+                "shop",
+                ["invoice.created"],
+                predicates=["handles_event", "emits_event"],
+                direction="incoming",
+                include_dynamic=True,
+            )
+            client.code.inventory("shop", "architecture", limit=50, cursor=7)
+            client.code.certify("shop", "count-call-sites", "sym")
+            client.code.gc("shop")
+        assert [p[0] for p in posts] == [
+            "/v1/code/repos",
+            "/v1/code/context",
+            "/v1/code/workspace/context",
+            "/v1/code/graph/query",
+            "/v1/code/inventory",
+            "/v1/code/certify",
+            "/v1/code/gc",
+        ]
+        assert posts[1][1]["token_budget"] == 500
+        assert posts[1][1]["changed_paths"] == ["a.ts"]
+        assert posts[2][1]["repos"] == ["api", "worker"]
+        assert posts[2][1]["changed_paths"] == {"api": ["src/client.ts"]}
+        assert posts[2][1]["token_budget"] == 900
+        assert posts[3][1]["predicates"] == ["handles_event", "emits_event"]
+        assert posts[3][1]["include_dynamic"] is True
+        assert posts[4][1] == {
+            "repo": "shop",
+            "kind": "architecture",
+            "limit": 50,
+            "cursor": 7,
+        }