cortexdbai 0.8.0__tar.gz → 0.10.0__tar.gz

{cortexdbai-0.8.0 → cortexdbai-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexdbai
-Version: 0.8.0
+Version: 0.10.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.8.0 → cortexdbai-0.10.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.8.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",
-]
+"""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.10.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.8.0 → cortexdbai-0.10.0}/cortexdb/v1/client.py

@@ -104,19 +104,31 @@ def _envelope(
     observed_actor: Optional[Mapping[str, str]] = None,
     blob_id: Optional[str] = None,
     transcript: Optional[str] = None,
+    triple: Optional[Mapping[str, Any]] = None,
 ) -> dict:
     """Build a v1 ``ExperienceEnvelope`` for the bulk-ingest endpoint.
 
-    Exactly one of ``text`` / ``json_data`` / ``blob_id`` must be provided
-    (Message, Json, or BlobRef content kinds). With ``blob_id`` you may also
-    pass ``transcript`` — the text you already have for that object — and the
-    server will index it and SKIP the content processor (no re-transcription /
-    OCR). Defaults are filled in for ``observed_at`` (current UTC) and
+    Exactly one of ``text`` / ``json_data`` / ``blob_id`` / ``triple`` must be
+    provided (Message, Json, BlobRef, or Triple content kinds). With
+    ``blob_id`` you may also pass ``transcript`` — the text you already have
+    for that object — and the server will index it and SKIP the content
+    processor (no re-transcription / OCR). A ``triple`` writes a fact
+    DETERMINISTICALLY (no LLM extractor in the loop, server >= v0.7.0):
+    ``{"subject": {"type": "literal", "datatype": "string", "value": "Acme"},
+    "predicate": "billing_contact",
+    "object": {"type": "literal", "datatype": "string", "value": "Dana"}}``
+    (subject/object may also be ``{"type": "entity", "id": ...}`` or
+    ``{"type": "concept", "id": ...}``; the server canonicalizes the
+    predicate). Defaults are filled in for ``observed_at`` (current UTC) and
     ``idempotency_key`` (UUID v4).
     """
-    if sum(x is not None for x in (text, json_data, blob_id)) != 1:
-        raise ValueError("provide exactly one of `text`, `json_data`, or `blob_id`")
-    if blob_id is not None:
+    if sum(x is not None for x in (text, json_data, blob_id, triple)) != 1:
+        raise ValueError(
+            "provide exactly one of `text`, `json_data`, `blob_id`, or `triple`"
+        )
+    if triple is not None:
+        content: dict = {"kind": "triple", "triple": dict(triple)}
+    elif blob_id is not None:
         content = {"kind": "blob_ref", "blob_id": blob_id}
         if transcript is not None:
             content["transcript"] = transcript
@@ -363,13 +375,16 @@ class V1Client:
         wait: Optional[str] = None,
         blob_id: Optional[str] = None,
         transcript: Optional[str] = None,
+        triple: Optional[Mapping[str, Any]] = None,
     ) -> dict:
         """``POST /v1/experience`` — single envelope. Provide exactly one of
-        ``text`` / ``json_data`` / ``blob_id``. With ``blob_id`` (from
-        :meth:`upload_blob`) the referenced file is processed into text; pass
-        ``transcript`` to supply your own text instead and skip the processor.
-        ``wait`` selects sync semantics: ``captured``, ``indexed``,
-        ``consolidated``."""
+        ``text`` / ``json_data`` / ``blob_id`` / ``triple``. With ``blob_id``
+        (from :meth:`upload_blob`) the referenced file is processed into text;
+        pass ``transcript`` to supply your own text instead and skip the
+        processor. A ``triple`` (subject/predicate/object dict, see
+        :func:`_envelope`) writes a fact deterministically — no LLM extractor
+        in the loop (server >= v0.7.0). ``wait`` selects sync semantics:
+        ``captured``, ``indexed``, ``consolidated``."""
         env = _envelope(
             scope,
             role=role,
@@ -380,6 +395,7 @@ class V1Client:
             idempotency_key=idempotency_key,
             blob_id=blob_id,
             transcript=transcript,
+            triple=triple,
         )
         path = "/v1/experience" + (f"?wait={wait}" if wait else "")
         return self._post(path, env)
@@ -453,6 +469,7 @@ class V1Client:
                 observed_at=item.get("observed_at"),
                 idempotency_key=item.get("idempotency_key"),
                 observed_actor=item.get("observed_actor"),
+                triple=item.get("triple"),
             )
             for item in items
         ]
@@ -471,9 +488,16 @@ class V1Client:
         diagnostics: str = "none",
         budgets: Optional[Mapping[str, Any]] = None,
         temporal: Optional[Mapping[str, Any]] = None,
+        filters: Optional[Mapping[str, Any]] = None,
     ) -> dict:
         """``POST /v1/recall`` — returns a ``StratifiedPack``.
 
+        ``filters`` — hard eligibility predicates over stored event
+        attributes: ``{"metadata": {"labels": "primary_inbox"}}`` keeps only
+        events whose labels contain the value (lists mean any-of). Valid
+        keys: labels, intent, modality, caller, observed_actor; unknown
+        keys 422. Relevance decides order; filters decide eligibility.
+
         ``diagnostics`` defaults to ``"none"`` so free-tier tokens — which
         do not carry the ``diagnostics.read`` capability — succeed on the
         first call. Pass ``diagnostics="summary"`` (or ``"full"``) when
@@ -486,6 +510,8 @@ class V1Client:
             body["include"] = list(include)
         if budgets:
             body["budgets"] = dict(budgets)
+        if filters:
+            body["filters"] = dict(filters)
         if temporal:
             body["temporal"] = dict(temporal)
         return self._post("/v1/recall", body)
@@ -505,6 +531,7 @@ class V1Client:
         use_pack_id: Optional[str] = None,
         temporal: Optional[Mapping[str, Any]] = None,
         diagnostics: str = "none",
+        filters: Optional[Mapping[str, Any]] = None,
     ) -> dict:
         """``POST /v1/answer`` — runs recall + LLM render.
 
@@ -541,6 +568,8 @@ class V1Client:
             body["use_pack_id"] = use_pack_id
         if temporal:
             body["temporal"] = dict(temporal)
+        if filters:
+            body["filters"] = dict(filters)
         return self._post("/v1/answer", body)
 
     def compose(
@@ -559,6 +588,7 @@ class V1Client:
         model: Optional[str] = None,
         use_pack_id: Optional[str] = None,
         include_context: bool = False,
+        filters: Optional[Mapping[str, Any]] = None,
     ) -> dict:
         """``POST /v1/compose`` — produce a structured markdown DOCUMENT
         from memory (digests, reports, overviews).
@@ -600,6 +630,8 @@ class V1Client:
             body["use_pack_id"] = use_pack_id
         if include_context:
             body["include_context"] = True
+        if filters:
+            body["filters"] = dict(filters)
         return self._post("/v1/compose", body)
 
     # ── layer reads ───────────────────────────────────────────────────
@@ -1013,6 +1045,7 @@ class AsyncV1Client:
                 observed_at=item.get("observed_at"),
                 idempotency_key=item.get("idempotency_key"),
                 observed_actor=item.get("observed_actor"),
+                triple=item.get("triple"),
             )
             for item in items
         ]
@@ -1031,11 +1064,13 @@ class AsyncV1Client:
         wait: Optional[str] = None,
         blob_id: Optional[str] = None,
         transcript: Optional[str] = None,
+        triple: Optional[Mapping[str, Any]] = None,
     ) -> dict:
         """``POST /v1/experience``. Provide exactly one of ``text`` /
-        ``json_data`` / ``blob_id``. With ``blob_id`` (from
+        ``json_data`` / ``blob_id`` / ``triple``. With ``blob_id`` (from
         :meth:`upload_blob`), pass ``transcript`` to index your own text and
-        skip server-side extraction."""
+        skip server-side extraction. A ``triple`` writes a fact
+        deterministically — no LLM extractor in the loop (server >= v0.7.0)."""
         env = _envelope(
             scope,
             role=role,
@@ -1046,6 +1081,7 @@ class AsyncV1Client:
             idempotency_key=idempotency_key,
             blob_id=blob_id,
             transcript=transcript,
+            triple=triple,
         )
         path = "/v1/experience" + (f"?wait={wait}" if wait else "")
         return await self._post(path, env)

{cortexdbai-0.8.0 → cortexdbai-0.10.0}/pyproject.toml

@@ -1,186 +1,186 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "cortexdbai"
-version = "0.8.0"
-description = "The Long-Term Memory Layer for AI Systems"
-readme = "README.md"
-license = "Apache-2.0"
-# 3.10+: the v1 module uses PEP 604 unions (`str | None`) in TypedDict
-# field annotations, which Python 3.9 cannot evaluate at class-definition
-# time even with `from __future__ import annotations`. Python 3.9 hit
-# end-of-life on 2025-10-31. Declaring >=3.10 means `pip install
-# cortexdbai` on 3.9 fails immediately with a clear "requires Python
-# 3.10+" error from pip — not a silent install followed by an obscure
-# `TypeError: Unable to evaluate type annotation 'str | None'` on the
-# first import.
-requires-python = ">=3.10"
-authors = [
-    { name = "Prashant Malik", email = "prashant@cortexdb.ai" },
-]
-keywords = ["ai", "memory", "llm", "knowledge-graph", "event-sourcing", "cortexdb"]
-classifiers = [
-    "Development Status :: 4 - Beta",
-    "Intended Audience :: Developers",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.13",
-    "Topic :: Scientific/Engineering :: Artificial Intelligence",
-    "Topic :: Database",
-    "Typing :: Typed",
-]
-dependencies = [
-    "requests>=2.31",
-    "httpx>=0.24",
-    "pydantic>=2.0",
-    "tenacity>=8.0",
-]
-
-[project.optional-dependencies]
-async = [
-    "httpx[http2]",
-]
-dev = [
-    "pytest>=8.0",
-    "pytest-asyncio>=0.23",
-    "ruff>=0.4",
-]
-
-# --- Framework / provider integrations -------------------------------------
-# Each extra pulls in only the third-party framework needed by the matching
-# submodule under `cortexdb.integrations.<name>`. The CortexDB client itself
-# is always the base package, so it is never listed here. Nothing under
-# `cortexdb.integrations` is imported at `import cortexdb` time — importing a
-# submodule without its extra raises a clean ModuleNotFoundError.
-autogen = [
-    "ag2>=0.4",
-]
-ag2 = [
-    "ag2>=0.4",
-]
-agno = [
-    "agno>=1.0",
-]
-langchain = [
-    "langchain-core>=0.3",
-]
-beeai = [
-    "beeai-framework>=0.1",
-]
-camel = [
-    "camel-ai>=0.2",
-]
-controlflow = [
-    "controlflow>=0.11",
-]
-crewai = [
-    "crewai>=0.80",
-]
-dify = []
-dspy = [
-    "dspy>=2.0",
-]
-flowise = []
-google-adk = [
-    "google-adk>=0.1",
-]
-hermes = []
-instructor = [
-    "instructor>=1.0",
-    "pydantic>=2.0",
-]
-langgraph = [
-    "langchain-core>=0.3",
-    "langgraph-checkpoint>=2.0",
-]
-letta = [
-    "letta>=0.1",
-]
-llamaindex = [
-    "llama-index-core>=0.11",
-]
-nemo-guardrails = [
-    "nemoguardrails>=0.9",
-]
-openai-agents = [
-    "openai-agents>=0.1",
-]
-prefect = [
-    "prefect>=3.0",
-]
-pydanticai = [
-    "pydantic-ai>=0.1",
-]
-smolagents = [
-    "smolagents>=1.0",
-]
-temporal = [
-    "temporalio>=1.7",
-]
-groq = [
-    "httpx>=0.27",
-]
-fireworks = [
-    "httpx>=0.27",
-]
-together = [
-    "httpx>=0.27",
-]
-deepinfra = [
-    "httpx>=0.27",
-]
-ollama = [
-    "httpx>=0.27",
-]
-vllm = [
-    "httpx>=0.27",
-]
-# Convenience: every framework/provider integration at once.
-all-integrations = [
-    "ag2>=0.4",
-    "agno>=1.0",
-    "langchain-core>=0.3",
-    "beeai-framework>=0.1",
-    "camel-ai>=0.2",
-    "controlflow>=0.11",
-    "crewai>=0.80",
-    "dspy>=2.0",
-    "google-adk>=0.1",
-    "instructor>=1.0",
-    "langchain-core>=0.3",
-    "langgraph-checkpoint>=2.0",
-    "letta>=0.1",
-    "llama-index-core>=0.11",
-    "nemoguardrails>=0.9",
-    "openai-agents>=0.1",
-    "prefect>=3.0",
-    "pydantic-ai>=0.1",
-    "smolagents>=1.0",
-    "temporalio>=1.7",
-    "httpx>=0.27",
-]
-
-[project.urls]
-Homepage = "https://cortexdb.ai"
-Documentation = "https://docs.cortexdb.ai"
-Repository = "https://github.com/cortexdb/cortexdb"
-Issues = "https://github.com/cortexdb/cortexdb/issues"
-Changelog = "https://github.com/cortexdb/cortexdb/blob/main/CHANGELOG.md"
-
-[tool.hatch.build.targets.wheel]
-packages = ["cortexdb"]
-
-[tool.ruff]
-target-version = "py310"
-line-length = 100
-
-[tool.ruff.lint]
-select = ["E", "F", "W", "I", "N", "UP", "B", "A", "SIM", "TCH"]
-
-[tool.pytest.ini_options]
-asyncio_mode = "auto"
-testpaths = ["tests"]
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cortexdbai"
+version = "0.10.0"
+description = "The Long-Term Memory Layer for AI Systems"
+readme = "README.md"
+license = "Apache-2.0"
+# 3.10+: the v1 module uses PEP 604 unions (`str | None`) in TypedDict
+# field annotations, which Python 3.9 cannot evaluate at class-definition
+# time even with `from __future__ import annotations`. Python 3.9 hit
+# end-of-life on 2025-10-31. Declaring >=3.10 means `pip install
+# cortexdbai` on 3.9 fails immediately with a clear "requires Python
+# 3.10+" error from pip — not a silent install followed by an obscure
+# `TypeError: Unable to evaluate type annotation 'str | None'` on the
+# first import.
+requires-python = ">=3.10"
+authors = [
+    { name = "Prashant Malik", email = "prashant@cortexdb.ai" },
+]
+keywords = ["ai", "memory", "llm", "knowledge-graph", "event-sourcing", "cortexdb"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Database",
+    "Typing :: Typed",
+]
+dependencies = [
+    "requests>=2.31",
+    "httpx>=0.24",
+    "pydantic>=2.0",
+    "tenacity>=8.0",
+]
+
+[project.optional-dependencies]
+async = [
+    "httpx[http2]",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.4",
+]
+
+# --- Framework / provider integrations -------------------------------------
+# Each extra pulls in only the third-party framework needed by the matching
+# submodule under `cortexdb.integrations.<name>`. The CortexDB client itself
+# is always the base package, so it is never listed here. Nothing under
+# `cortexdb.integrations` is imported at `import cortexdb` time — importing a
+# submodule without its extra raises a clean ModuleNotFoundError.
+autogen = [
+    "ag2>=0.4",
+]
+ag2 = [
+    "ag2>=0.4",
+]
+agno = [
+    "agno>=1.0",
+]
+langchain = [
+    "langchain-core>=0.3",
+]
+beeai = [
+    "beeai-framework>=0.1",
+]
+camel = [
+    "camel-ai>=0.2",
+]
+controlflow = [
+    "controlflow>=0.11",
+]
+crewai = [
+    "crewai>=0.80",
+]
+dify = []
+dspy = [
+    "dspy>=2.0",
+]
+flowise = []
+google-adk = [
+    "google-adk>=0.1",
+]
+hermes = []
+instructor = [
+    "instructor>=1.0",
+    "pydantic>=2.0",
+]
+langgraph = [
+    "langchain-core>=0.3",
+    "langgraph-checkpoint>=2.0",
+]
+letta = [
+    "letta>=0.1",
+]
+llamaindex = [
+    "llama-index-core>=0.11",
+]
+nemo-guardrails = [
+    "nemoguardrails>=0.9",
+]
+openai-agents = [
+    "openai-agents>=0.1",
+]
+prefect = [
+    "prefect>=3.0",
+]
+pydanticai = [
+    "pydantic-ai>=0.1",
+]
+smolagents = [
+    "smolagents>=1.0",
+]
+temporal = [
+    "temporalio>=1.7",
+]
+groq = [
+    "httpx>=0.27",
+]
+fireworks = [
+    "httpx>=0.27",
+]
+together = [
+    "httpx>=0.27",
+]
+deepinfra = [
+    "httpx>=0.27",
+]
+ollama = [
+    "httpx>=0.27",
+]
+vllm = [
+    "httpx>=0.27",
+]
+# Convenience: every framework/provider integration at once.
+all-integrations = [
+    "ag2>=0.4",
+    "agno>=1.0",
+    "langchain-core>=0.3",
+    "beeai-framework>=0.1",
+    "camel-ai>=0.2",
+    "controlflow>=0.11",
+    "crewai>=0.80",
+    "dspy>=2.0",
+    "google-adk>=0.1",
+    "instructor>=1.0",
+    "langchain-core>=0.3",
+    "langgraph-checkpoint>=2.0",
+    "letta>=0.1",
+    "llama-index-core>=0.11",
+    "nemoguardrails>=0.9",
+    "openai-agents>=0.1",
+    "prefect>=3.0",
+    "pydantic-ai>=0.1",
+    "smolagents>=1.0",
+    "temporalio>=1.7",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://cortexdb.ai"
+Documentation = "https://docs.cortexdb.ai"
+Repository = "https://github.com/cortexdb/cortexdb"
+Issues = "https://github.com/cortexdb/cortexdb/issues"
+Changelog = "https://github.com/cortexdb/cortexdb/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["cortexdb"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "A", "SIM", "TCH"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]