cortexdbai 0.6.0__tar.gz → 0.8.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexdbai
-Version: 0.6.0
+Version: 0.8.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.6.0 → cortexdbai-0.8.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.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",
-]
+"""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",
+]

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

@@ -500,6 +500,8 @@ class V1Client:
         question_date: Optional[str] = None,
         answer_model: Optional[str] = None,
         answer_max_tokens: Optional[int] = None,
+        answer_instructions: Optional[str] = None,
+        cite_sources: bool = False,
         use_pack_id: Optional[str] = None,
         temporal: Optional[Mapping[str, Any]] = None,
         diagnostics: str = "none",
@@ -510,6 +512,12 @@ class V1Client:
         defaults to ``"none"`` so free-tier tokens don't hit the
         ``diagnostics.read`` gate. Pass ``"summary"`` or ``"full"`` when
         you hold the elevated capability.
+
+        ``answer_instructions`` is a prompt addendum appended to the server's
+        system prompt — control style, verbosity, and output format ("be
+        terse", "answer as markdown with curl examples", "respond in JSON").
+        It never affects retrieval. Max 4000 chars. Pair with
+        ``question_type="docs-assistant"`` for documentation-support answers.
         """
         body: dict = {
             "scope": scope,
@@ -525,12 +533,75 @@ class V1Client:
             body["answer_model"] = answer_model
         if answer_max_tokens is not None:
             body["answer_max_tokens"] = answer_max_tokens
+        if answer_instructions:
+            body["answer_instructions"] = answer_instructions
+        if cite_sources:
+            body["cite_sources"] = True
         if use_pack_id:
             body["use_pack_id"] = use_pack_id
         if temporal:
             body["temporal"] = dict(temporal)
         return self._post("/v1/answer", body)
 
+    def compose(
+        self,
+        scope: str,
+        brief: str,
+        *,
+        view: str = "holistic",
+        time: Optional[str] = None,
+        depth: Optional[str] = None,
+        length: Optional[str] = None,
+        max_tokens: Optional[int] = None,
+        structure: Optional[Sequence[str]] = None,
+        citations: bool = True,
+        instructions: Optional[str] = None,
+        model: Optional[str] = None,
+        use_pack_id: Optional[str] = None,
+        include_context: bool = False,
+    ) -> dict:
+        """``POST /v1/compose`` — produce a structured markdown DOCUMENT
+        from memory (digests, reports, overviews).
+
+        The synthesis-permitted counterpart to :meth:`answer`: answer is
+        "what is true in my memory?" (terse, cite-or-abstain); compose is
+        "write me something from my memory" (markdown with headings,
+        tables, mermaid diagrams; per-section "insufficient evidence"
+        notes instead of a global abstention). Returns ``document``
+        instead of ``answer``.
+
+        - ``view``: ``holistic`` (default), ``lineage`` (include ancestor
+          synthesis your subtree contributed to), or ``descend``.
+        - ``time``: natural-language window, e.g. ``"last 7 days"``.
+        - ``depth``: ``standard`` (default) or ``exhaustive`` (whole-scope
+          context instead of ranked top-K — right for digests).
+        - ``length``: ``brief`` | ``standard`` | ``deep``
+          (~600/1500/4000 output tokens); ``max_tokens`` overrides.
+        - ``structure``: section outline the document follows exactly.
+        - ``citations``: grounded ``[S#]`` markers, default ON.
+        - ``instructions``: free-text style escape hatch (max 4000 chars).
+        """
+        body: dict = {"scope": scope, "brief": brief, "view": view, "citations": citations}
+        if time:
+            body["time"] = time
+        if depth:
+            body["depth"] = depth
+        if length:
+            body["length"] = length
+        if max_tokens is not None:
+            body["max_tokens"] = max_tokens
+        if structure:
+            body["structure"] = list(structure)
+        if instructions:
+            body["instructions"] = instructions
+        if model:
+            body["model"] = model
+        if use_pack_id:
+            body["use_pack_id"] = use_pack_id
+        if include_context:
+            body["include_context"] = True
+        return self._post("/v1/compose", body)
+
     # ── layer reads ───────────────────────────────────────────────────
 
     def events(
@@ -1020,11 +1091,14 @@ class AsyncV1Client:
         *,
         question_type: Optional[str] = None,
         question_date: Optional[str] = None,
+        answer_instructions: Optional[str] = None,
+        cite_sources: bool = False,
         view: str = "holistic",
         diagnostics: str = "none",
     ) -> dict:
         """``POST /v1/answer``. ``diagnostics`` defaults to ``"none"`` so
-        free-tier tokens succeed (audit FRI-1)."""
+        free-tier tokens succeed (audit FRI-1). ``answer_instructions``:
+        see :meth:`V1Client.answer`."""
         body: dict = {
             "scope": scope,
             "view": view,
@@ -1035,8 +1109,39 @@ class AsyncV1Client:
             body["question_type"] = question_type
         if question_date:
             body["question_date"] = question_date
+        if answer_instructions:
+            body["answer_instructions"] = answer_instructions
+        if cite_sources:
+            body["cite_sources"] = True
         return await self._post("/v1/answer", body)
 
+    async def compose(
+        self,
+        scope: str,
+        brief: str,
+        *,
+        view: str = "holistic",
+        time: Optional[str] = None,
+        depth: Optional[str] = None,
+        length: Optional[str] = None,
+        structure: Optional[Sequence[str]] = None,
+        citations: bool = True,
+        instructions: Optional[str] = None,
+    ) -> dict:
+        """``POST /v1/compose``. See :meth:`V1Client.compose`."""
+        body: dict = {"scope": scope, "brief": brief, "view": view, "citations": citations}
+        if time:
+            body["time"] = time
+        if depth:
+            body["depth"] = depth
+        if length:
+            body["length"] = length
+        if structure:
+            body["structure"] = list(structure)
+        if instructions:
+            body["instructions"] = instructions
+        return await self._post("/v1/compose", 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).

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

@@ -1,186 +1,186 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "cortexdbai"
-version = "0.6.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.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"]