cortexdb-client 0.3.0__tar.gz → 0.4.0__tar.gz

cortexdb_client-0.4.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.5
+Name: cortexdb-client
+Version: 0.4.0
+Summary: Typed gRPC client for CortexDB (AI memory + knowledge graph sidecar)
+Project-URL: Homepage, https://github.com/liliang-cn/cortexdb
+Project-URL: Repository, https://github.com/liliang-cn/cortexdb
+Author: Liang Li
+License: MIT
+Keywords: agent-memory,ai,cortexdb,grpc,knowledge-graph,rag
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: grpcio>=1.60
+Requires-Dist: protobuf>=4.25
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: grpcio-tools>=1.60; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# cortexdb-client (Python)
+
+Typed gRPC client for [CortexDB](https://github.com/liliang-cn/cortexdb) — a
+pure-Go, single-file AI memory and knowledge graph database, served as a
+sidecar (`cortexdb-grpc`). Give your Python agent (e.g. **Hermes**) durable
+memory **and** a queryable knowledge graph.
+
+## Install
+
+```bash
+pip install cortexdb-client          # or: uv add cortexdb-client
+```
+
+Start the sidecar (one binary, one SQLite file):
+
+```bash
+go install github.com/liliang-cn/cortexdb/v2/cmd/cortexdb-grpc@latest
+CORTEXDB_PATH=agent.db CORTEXDB_GRPC_TOKEN=s3cret cortexdb-grpc
+# listening on 127.0.0.1:47821
+```
+
+## Quick start
+
+```python
+from cortexdb_client import CortexClient, proto
+
+with CortexClient.connect("127.0.0.1:47821", token="s3cret") as client:
+    client.knowledge.SaveKnowledge(proto.SaveKnowledgeRequest(
+        knowledge_id="note-1",
+        content="The user is building an autonomous research agent in Python.",
+    ))
+    hits = client.knowledge.SearchKnowledge(proto.SearchKnowledgeRequest(
+        query="what is the user building?", top_k=3,
+    ))
+    for h in hits.results:
+        print(h.knowledge_id, h.score, h.snippet)
+```
+
+Sub-clients mirror the Rust crate: `client.knowledge`, `client.memory`,
+`client.graph` (SPARQL/RDF/SHACL/inference/ontology), `client.graphrag`,
+`client.tools` (generic tool dispatch, same surface as MCP), `client.admin`.
+
+## Results as DataFrames or CSV
+
+`client.tools.CallTool` answers with JSON. `cortexdb_client.tabular` turns the
+row-shaped part of it into flat records, a pandas DataFrame or a CSV file:
+
+```python
+import json
+from cortexdb_client import CortexClient, proto, tabular
+
+with CortexClient.connect("127.0.0.1:47821", token="s3cret") as client:
+    res = client.tools.CallTool(proto.CallToolRequest(
+        name="graph_cypher_query",
+        args_json=json.dumps({"query": "MATCH (a)-[r]->(b) RETURN a, r, b LIMIT 100"}),
+    ))
+
+rows = tabular.records(res)       # list of flat dicts: {"a.id": ..., "r.type": ..., "b.id": ...}
+df = tabular.to_pandas(res)       # needs the extra: pip install "cortexdb-client[pandas]"
+tabular.to_csv(res, "edges.csv")  # standard library only; to_csv(res) returns the text
+```
+
+pandas is optional and imported only inside `to_pandas()`; the base install
+stays `grpcio` + `protobuf`.
+
+| Tool | Table(s) |
+| --- | --- |
+| `graph_cypher_query` | `rows` (default) — `columns` zipped with each row |
+| `aggregate_metadata` | `results` (default) — one row per group |
+| `memory_search`, `knowledge_search` | `results` (default); `knowledge_search` may also carry `chunks` |
+| `knowledge_memory_recall` | `memories`, `knowledge`, `chunks`, `graph_facts` — pass `table=` |
+| `memory_list_all` | `memories` (default) |
+| `graph_list_all` | `nodes`, `edges` — pass `table=` |
+| `search_text`, `recall_log_list`, `graph_property_values`, … | the one top-level list of objects (`chunks`, `recalls`, `values`) |
+
+`tabular.tables(res)` names the tables a result has. A result with more than one
+and no `rows` / `results` raises `ValueError` until you pick:
+`tabular.records(res, "edges")`.
+
+How a row becomes columns:
+
+- a scalar is a column under its key;
+- a nested object becomes one column per leaf, keys joined with `.`
+  (`metadata.project`, `n.properties.city`); `sep="__"` changes the separator;
+- a list becomes its JSON text, or stays a list with `lists="keep"`
+  (for `DataFrame.explode`);
+- the `keys` of an aggregate group and the `memory` of a memory hit are lifted,
+  so their fields lead the row unprefixed (`team`, `year`, `value`, `count`;
+  `id`, `content`, …, `score`). A lifted name that collides keeps its prefix
+  (`keys.count`). Every other key of a group is a column whatever it is called,
+  so new measures need no client change;
+- rows need not share columns: CSV leaves the cell empty, pandas gives `NaN`.
+
+Listings page with a cursor; collect the pages, then tabulate:
+
+```python
+memories, cursor = [], ""
+while True:
+    page = json.loads(client.tools.CallTool(proto.CallToolRequest(
+        name="memory_list_all", args_json=json.dumps({"cursor": cursor}))).result_json)
+    memories += tabular.records(page)
+    cursor = page.get("next_cursor", "")
+    if not cursor:
+        break
+```
+
+To analyse the SQLite file itself with DuckDB, pandas or `sqlite3`, see
+"Data analysis" in the [guide](https://github.com/liliang-cn/cortexdb/blob/main/docs/GUIDE.md).
+
+## Why a knowledge graph, not just vectors
+
+Beyond semantic recall, the `graph` service lets an agent store and traverse
+**entities and relations** — multi-hop questions like "who, among the people
+Alice knows, works on X" — with SPARQL, RDFS-lite inference, and SHACL-lite
+validation. That is the capability most agent-memory layers lack.
+
+## Embeddings
+
+Lexical mode needs no keys. Point the sidecar at any OpenAI-compatible
+embeddings endpoint (e.g. Ollama) to enable vector retrieval:
+
+```bash
+OPENAI_BASE_URL=http://localhost:11434/v1 \
+CORTEXDB_EMBED_MODEL=embeddinggemma CORTEXDB_EMBED_DIM=768 \
+cortexdb-grpc
+```
+
+## Regenerating the protobuf code
+
+Generated code is committed under `cortexdb_client/_pb`. To regenerate after a
+proto change: `uv run --extra dev ./gen.sh`.

cortexdb_client-0.4.0/README.md

@@ -0,0 +1,131 @@
+# cortexdb-client (Python)
+
+Typed gRPC client for [CortexDB](https://github.com/liliang-cn/cortexdb) — a
+pure-Go, single-file AI memory and knowledge graph database, served as a
+sidecar (`cortexdb-grpc`). Give your Python agent (e.g. **Hermes**) durable
+memory **and** a queryable knowledge graph.
+
+## Install
+
+```bash
+pip install cortexdb-client          # or: uv add cortexdb-client
+```
+
+Start the sidecar (one binary, one SQLite file):
+
+```bash
+go install github.com/liliang-cn/cortexdb/v2/cmd/cortexdb-grpc@latest
+CORTEXDB_PATH=agent.db CORTEXDB_GRPC_TOKEN=s3cret cortexdb-grpc
+# listening on 127.0.0.1:47821
+```
+
+## Quick start
+
+```python
+from cortexdb_client import CortexClient, proto
+
+with CortexClient.connect("127.0.0.1:47821", token="s3cret") as client:
+    client.knowledge.SaveKnowledge(proto.SaveKnowledgeRequest(
+        knowledge_id="note-1",
+        content="The user is building an autonomous research agent in Python.",
+    ))
+    hits = client.knowledge.SearchKnowledge(proto.SearchKnowledgeRequest(
+        query="what is the user building?", top_k=3,
+    ))
+    for h in hits.results:
+        print(h.knowledge_id, h.score, h.snippet)
+```
+
+Sub-clients mirror the Rust crate: `client.knowledge`, `client.memory`,
+`client.graph` (SPARQL/RDF/SHACL/inference/ontology), `client.graphrag`,
+`client.tools` (generic tool dispatch, same surface as MCP), `client.admin`.
+
+## Results as DataFrames or CSV
+
+`client.tools.CallTool` answers with JSON. `cortexdb_client.tabular` turns the
+row-shaped part of it into flat records, a pandas DataFrame or a CSV file:
+
+```python
+import json
+from cortexdb_client import CortexClient, proto, tabular
+
+with CortexClient.connect("127.0.0.1:47821", token="s3cret") as client:
+    res = client.tools.CallTool(proto.CallToolRequest(
+        name="graph_cypher_query",
+        args_json=json.dumps({"query": "MATCH (a)-[r]->(b) RETURN a, r, b LIMIT 100"}),
+    ))
+
+rows = tabular.records(res)       # list of flat dicts: {"a.id": ..., "r.type": ..., "b.id": ...}
+df = tabular.to_pandas(res)       # needs the extra: pip install "cortexdb-client[pandas]"
+tabular.to_csv(res, "edges.csv")  # standard library only; to_csv(res) returns the text
+```
+
+pandas is optional and imported only inside `to_pandas()`; the base install
+stays `grpcio` + `protobuf`.
+
+| Tool | Table(s) |
+| --- | --- |
+| `graph_cypher_query` | `rows` (default) — `columns` zipped with each row |
+| `aggregate_metadata` | `results` (default) — one row per group |
+| `memory_search`, `knowledge_search` | `results` (default); `knowledge_search` may also carry `chunks` |
+| `knowledge_memory_recall` | `memories`, `knowledge`, `chunks`, `graph_facts` — pass `table=` |
+| `memory_list_all` | `memories` (default) |
+| `graph_list_all` | `nodes`, `edges` — pass `table=` |
+| `search_text`, `recall_log_list`, `graph_property_values`, … | the one top-level list of objects (`chunks`, `recalls`, `values`) |
+
+`tabular.tables(res)` names the tables a result has. A result with more than one
+and no `rows` / `results` raises `ValueError` until you pick:
+`tabular.records(res, "edges")`.
+
+How a row becomes columns:
+
+- a scalar is a column under its key;
+- a nested object becomes one column per leaf, keys joined with `.`
+  (`metadata.project`, `n.properties.city`); `sep="__"` changes the separator;
+- a list becomes its JSON text, or stays a list with `lists="keep"`
+  (for `DataFrame.explode`);
+- the `keys` of an aggregate group and the `memory` of a memory hit are lifted,
+  so their fields lead the row unprefixed (`team`, `year`, `value`, `count`;
+  `id`, `content`, …, `score`). A lifted name that collides keeps its prefix
+  (`keys.count`). Every other key of a group is a column whatever it is called,
+  so new measures need no client change;
+- rows need not share columns: CSV leaves the cell empty, pandas gives `NaN`.
+
+Listings page with a cursor; collect the pages, then tabulate:
+
+```python
+memories, cursor = [], ""
+while True:
+    page = json.loads(client.tools.CallTool(proto.CallToolRequest(
+        name="memory_list_all", args_json=json.dumps({"cursor": cursor}))).result_json)
+    memories += tabular.records(page)
+    cursor = page.get("next_cursor", "")
+    if not cursor:
+        break
+```
+
+To analyse the SQLite file itself with DuckDB, pandas or `sqlite3`, see
+"Data analysis" in the [guide](https://github.com/liliang-cn/cortexdb/blob/main/docs/GUIDE.md).
+
+## Why a knowledge graph, not just vectors
+
+Beyond semantic recall, the `graph` service lets an agent store and traverse
+**entities and relations** — multi-hop questions like "who, among the people
+Alice knows, works on X" — with SPARQL, RDFS-lite inference, and SHACL-lite
+validation. That is the capability most agent-memory layers lack.
+
+## Embeddings
+
+Lexical mode needs no keys. Point the sidecar at any OpenAI-compatible
+embeddings endpoint (e.g. Ollama) to enable vector retrieval:
+
+```bash
+OPENAI_BASE_URL=http://localhost:11434/v1 \
+CORTEXDB_EMBED_MODEL=embeddinggemma CORTEXDB_EMBED_DIM=768 \
+cortexdb-grpc
+```
+
+## Regenerating the protobuf code
+
+Generated code is committed under `cortexdb_client/_pb`. To regenerate after a
+proto change: `uv run --extra dev ./gen.sh`.

{cortexdb_client-0.3.0 → cortexdb_client-0.4.0}/cortexdb_client/__init__.py

@@ -16,10 +16,14 @@ Example::
 The sub-client accessors mirror the Rust crate: ``client.knowledge``,
 ``client.memory``, ``client.graph``, ``client.graphrag``, ``client.tools``,
 ``client.admin``.
+
+``cortexdb_client.tabular`` turns a tool result into flat records, a pandas
+DataFrame or CSV.
 """
 
 from .client import CortexClient
 from . import proto
+from . import tabular
 
-__all__ = ["CortexClient", "proto"]
+__all__ = ["CortexClient", "proto", "tabular"]
 __version__ = "0.1.0"

cortexdb_client-0.4.0/cortexdb_client/tabular.py

@@ -0,0 +1,284 @@
+"""Tool results as tables: flat records, a pandas DataFrame, or CSV.
+
+A tool called through ``client.tools.CallTool`` answers with one JSON object.
+The row-shaped part of it — a Cypher query's rows, the groups of
+``aggregate_metadata``, the hits of a search or a recall, a listing — is a
+list under some key. :func:`records` picks that list and returns it as flat
+``dict`` records, one per row, ready for ``csv``, pandas, polars or DuckDB::
+
+    import json
+    from cortexdb_client import CortexClient, proto, tabular
+
+    with CortexClient.connect("127.0.0.1:47821") as client:
+        res = client.tools.CallTool(proto.CallToolRequest(
+            name="graph_cypher_query",
+            args_json=json.dumps({"query": "MATCH (n) RETURN n LIMIT 100"}),
+        ))
+    rows = tabular.records(res)       # [{"n.id": "...", "n.labels": "[...]", ...}, ...]
+    df = tabular.to_pandas(res)       # needs: pip install "cortexdb-client[pandas]"
+    tabular.to_csv(res, "nodes.csv")
+
+Which list is the table
+-----------------------
+
+``records(result, table=None)`` chooses, in this order:
+
+1. ``table``, when given — the name of a top-level key (``"memories"``,
+   ``"knowledge"``, ``"chunks"``, ``"graph_facts"``, ``"nodes"``, ``"edges"``,
+   ``"recalls"`` …). :func:`tables` lists the names a result has.
+2. ``rows``, when the result also has ``columns`` (``graph_cypher_query``).
+3. ``results``, when present (``aggregate_metadata``, ``memory_search``,
+   ``knowledge_search``).
+4. The only top-level list of objects, when there is exactly one
+   (``memory_list_all`` → ``memories``, ``search_text`` → ``chunks``).
+
+Anything else raises ``ValueError`` naming the tables to choose from —
+``graph_list_all`` has ``nodes`` and ``edges``, ``knowledge_memory_recall`` has
+``memories``, ``knowledge``, ``chunks`` and ``graph_facts``.
+
+How a row is flattened
+----------------------
+
+* A scalar (string, number, bool, ``None``) is a column under its key.
+* A nested object becomes one column per leaf, the keys joined with ``.``:
+  ``{"metadata": {"project": "x"}}`` → ``metadata.project``. An empty object
+  adds no column.
+* A list becomes one column holding its compact JSON text (``lists="json"``,
+  the default — safe for CSV), or is kept as a Python list (``lists="keep"``,
+  for ``DataFrame.explode``).
+* Two wrappers are lifted so their fields are columns in their own right:
+  the ``keys`` of an ``aggregate_metadata`` group (``{"keys": {"project":
+  "x"}, "count": 3}`` → ``project``, ``count``) and the ``memory`` of a memory
+  hit (``{"memory": {"id": "m1"}, "score": 0.4}`` → ``id``, ``score``).
+  Lifted columns come first. One that would collide with another column
+  keeps its prefix (``keys.count``). Every other key of a group — today
+  ``value`` and ``count`` — is a column whatever it is called.
+* A Cypher row is its ``columns`` zipped with its values; a node or
+  relationship value is flattened under the column name (``n.id``,
+  ``n.properties.city``).
+
+Rows need not share columns: a key absent from a row is absent from its
+record. :func:`to_csv` and pandas fill the gap (empty cell, ``NaN``).
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+import os
+from typing import IO, TYPE_CHECKING, Any, Dict, Iterable, List, Mapping, Optional, Union
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    import pandas
+
+__all__ = ["Record", "flatten", "records", "tables", "columns", "to_pandas", "to_csv"]
+
+#: One flat row: column name → scalar (or list, with ``lists="keep"``).
+Record = Dict[str, Any]
+
+# Wrappers whose fields are lifted to top-level columns (see module docstring).
+_LIFTED = ("keys", "memory")
+
+_LIST_MODES = ("json", "keep")
+
+
+def _dumps(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"), sort_keys=True, default=str)
+
+
+def flatten(obj: Mapping[str, Any], *, sep: str = ".", lists: str = "json", prefix: str = "") -> Record:
+    """Flatten one nested object into a single-level record.
+
+    Nested objects become ``parent<sep>child`` columns, lists become compact
+    JSON text (``lists="json"``) or stay lists (``lists="keep"``), scalars are
+    copied. No wrapper is lifted here; see :func:`records` for that.
+    """
+    if lists not in _LIST_MODES:
+        raise ValueError(f"lists must be one of {_LIST_MODES}, got {lists!r}")
+    out: Record = {}
+    _flatten_into(out, obj, prefix, sep, lists)
+    return out
+
+
+def _flatten_into(out: Record, obj: Mapping[str, Any], prefix: str, sep: str, lists: str) -> None:
+    for key, value in obj.items():
+        name = f"{prefix}{sep}{key}" if prefix else str(key)
+        _put(out, name, value, sep, lists)
+
+
+def _put(out: Record, name: str, value: Any, sep: str, lists: str) -> None:
+    if isinstance(value, Mapping):
+        _flatten_into(out, value, name, sep, lists)
+    elif isinstance(value, (list, tuple)):
+        out[name] = _dumps(value) if lists == "json" else list(value)
+    else:
+        out[name] = value
+
+
+def _load(result: Any) -> Any:
+    """Decode what a tool call returned into plain Python data."""
+    payload = getattr(result, "result_json", None)  # proto.CallToolResponse
+    if payload is not None:
+        result = payload
+    if isinstance(result, (bytes, bytearray)):
+        result = bytes(result).decode("utf-8")
+    if isinstance(result, str):
+        if not result.strip():
+            return {}
+        return json.loads(result)
+    return result
+
+
+def _is_table(value: Any) -> bool:
+    return isinstance(value, list) and all(isinstance(item, Mapping) for item in value)
+
+
+def _table_names(data: Mapping[str, Any]) -> List[str]:
+    names = [key for key, value in data.items() if key != "rows" and _is_table(value)]
+    if "columns" in data and "rows" in data:
+        names.insert(0, "rows")
+    return names
+
+
+def tables(result: Any) -> List[str]:
+    """Names of the tables in a tool result, in the order the result has them.
+
+    A table is a top-level list of objects, or the ``rows`` of a Cypher
+    answer. A list the server left out because it was empty is not named.
+    """
+    data = _load(result)
+    if isinstance(data, list):
+        return []
+    if not isinstance(data, Mapping):
+        raise TypeError(f"expected a tool result object, got {type(data).__name__}")
+    return _table_names(data)
+
+
+def _pick(data: Mapping[str, Any], table: Optional[str]) -> str:
+    if table is not None:
+        if table not in data:
+            raise ValueError(f"no table {table!r} in this result; it has {_table_names(data) or 'none'}")
+        return table
+    if "columns" in data and "rows" in data:
+        return "rows"
+    if "results" in data:
+        return "results"
+    names = _table_names(data)
+    if len(names) == 1:
+        return names[0]
+    if not names:
+        raise ValueError("this result has no list of rows to tabulate")
+    raise ValueError(f"this result has several tables, pass table=: {names}")
+
+
+def _lifted_row(row: Mapping[str, Any], sep: str, lists: str) -> Record:
+    rest = {k: v for k, v in row.items() if not (k in _LIFTED and isinstance(v, Mapping))}
+    own = flatten(rest, sep=sep, lists=lists)
+    out: Record = {}
+    for wrapper in _LIFTED:  # lifted fields lead: group keys, then measures
+        inner = row.get(wrapper)
+        if not isinstance(inner, Mapping):
+            continue
+        for name, value in flatten(inner, sep=sep, lists=lists).items():
+            out[f"{wrapper}{sep}{name}" if name in own or name in out else name] = value
+    out.update(own)
+    return out
+
+
+def records(result: Any, table: Optional[str] = None, *, sep: str = ".", lists: str = "json") -> List[Record]:
+    """The rows of a tool result as flat records.
+
+    ``result`` is what ``client.tools.CallTool`` returned (a
+    ``CallToolResponse``), its ``result_json`` text, or the decoded object.
+    A bare list of objects is taken as the table itself. See the module
+    docstring for how the table is chosen and how a row is flattened.
+    """
+    if lists not in _LIST_MODES:
+        raise ValueError(f"lists must be one of {_LIST_MODES}, got {lists!r}")
+    data = _load(result)
+    if isinstance(data, list):
+        rows: Any = data
+    elif isinstance(data, Mapping):
+        name = _pick(data, table)
+        rows = data.get(name)
+        if name == "rows" and "columns" in data:
+            return _cypher_records(data.get("columns") or [], rows or [], sep, lists)
+    else:
+        raise TypeError(f"expected a tool result object, got {type(data).__name__}")
+    if rows is None:  # a Go nil slice arrives as null
+        return []
+    if not _is_table(rows):
+        raise ValueError(f"table {table!r} is not a list of objects")
+    return [_lifted_row(row, sep, lists) for row in rows]
+
+
+def _cypher_records(cols: Iterable[Any], rows: Iterable[Any], sep: str, lists: str) -> List[Record]:
+    names = [str(c) for c in cols]
+    out: List[Record] = []
+    for row in rows:
+        record: Record = {}
+        for name, value in zip(names, row):
+            _put(record, name, value, sep, lists)
+        out.append(record)
+    return out
+
+
+def columns(rows: Iterable[Mapping[str, Any]]) -> List[str]:
+    """Every column of ``rows``, in the order each first appears."""
+    seen: Dict[str, None] = {}
+    for row in rows:
+        for name in row:
+            seen.setdefault(name, None)
+    return list(seen)
+
+
+def to_pandas(result: Any, table: Optional[str] = None, *, sep: str = ".", lists: str = "json") -> "pandas.DataFrame":
+    """The rows of a tool result as a ``pandas.DataFrame``.
+
+    pandas is optional: ``pip install "cortexdb-client[pandas]"``. Columns
+    come in first-seen order; a key a row lacks is ``NaN`` there.
+    """
+    try:
+        import pandas as pd
+    except ImportError as exc:
+        raise ImportError(
+            "to_pandas() needs pandas, which cortexdb-client does not install by default. "
+            'Install it with: pip install "cortexdb-client[pandas]"  (or: uv add "cortexdb-client[pandas]"). '
+            "records() returns the same rows as plain dicts without it."
+        ) from exc
+    rows = records(result, table, sep=sep, lists=lists)
+    return pd.DataFrame.from_records(rows, columns=columns(rows))
+
+
+def to_csv(
+    result: Any,
+    dest: Union[str, "os.PathLike[str]", IO[str], None] = None,
+    table: Optional[str] = None,
+    *,
+    sep: str = ".",
+) -> Optional[str]:
+    """Write the rows of a tool result as CSV, header first.
+
+    ``dest`` is a path, an open text file, or ``None`` to get the CSV back as
+    a string. Lists are written as JSON text and a missing value as an empty
+    cell. Uses only the standard library. A path is written as UTF-8.
+    """
+    rows = records(result, table, sep=sep, lists="json")
+    header = columns(rows)
+
+    def write(handle: IO[str]) -> None:
+        writer = csv.DictWriter(handle, fieldnames=header, restval="", lineterminator="\n")
+        writer.writeheader()
+        writer.writerows(rows)
+
+    if dest is None:
+        buffer = io.StringIO()
+        write(buffer)
+        return buffer.getvalue()
+    if isinstance(dest, (str, os.PathLike)):
+        with open(dest, "w", encoding="utf-8", newline="") as handle:
+            write(handle)
+        return None
+    write(dest)
+    return None

{cortexdb_client-0.3.0 → cortexdb_client-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cortexdb-client"
-version = "0.3.0"
+version = "0.4.0"
 description = "Typed gRPC client for CortexDB (AI memory + knowledge graph sidecar)"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -24,6 +24,8 @@ Repository = "https://github.com/liliang-cn/cortexdb"
 
 [project.optional-dependencies]
 dev = ["grpcio-tools>=1.60", "build", "twine"]
+# tabular.to_pandas(); the rest of cortexdb_client.tabular needs nothing extra.
+pandas = ["pandas>=1.5"]
 
 [build-system]
 requires = ["hatchling"]