cortexdb-client 0.1.0__py3-none-any.whl

cortexdb_client/_pb/cortexdb/v1/tools_pb2_grpc.py

@@ -0,0 +1,140 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+import warnings
+
+from cortexdb_client._pb.cortexdb.v1 import tools_pb2 as cortexdb_dot_v1_dot_tools__pb2
+
+GRPC_GENERATED_VERSION = '1.81.0'
+GRPC_VERSION = grpc.__version__
+_version_not_supported = False
+
+try:
+    from grpc._utilities import first_version_is_lower
+    _version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
+except ImportError:
+    _version_not_supported = True
+
+if _version_not_supported:
+    raise RuntimeError(
+        f'The grpc package installed is at version {GRPC_VERSION},'
+        + ' but the generated code in cortexdb/v1/tools_pb2_grpc.py depends on'
+        + f' grpcio>={GRPC_GENERATED_VERSION}.'
+        + f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
+        + f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'
+    )
+
+
+class ToolsServiceStub:
+    """Missing associated documentation comment in .proto file."""
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.ListTools = channel.unary_unary(
+                '/cortexdb.v1.ToolsService/ListTools',
+                request_serializer=cortexdb_dot_v1_dot_tools__pb2.ListToolsRequest.SerializeToString,
+                response_deserializer=cortexdb_dot_v1_dot_tools__pb2.ListToolsResponse.FromString,
+                _registered_method=True)
+        self.CallTool = channel.unary_unary(
+                '/cortexdb.v1.ToolsService/CallTool',
+                request_serializer=cortexdb_dot_v1_dot_tools__pb2.CallToolRequest.SerializeToString,
+                response_deserializer=cortexdb_dot_v1_dot_tools__pb2.CallToolResponse.FromString,
+                _registered_method=True)
+
+
+class ToolsServiceServicer:
+    """Missing associated documentation comment in .proto file."""
+
+    def ListTools(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def CallTool(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_ToolsServiceServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'ListTools': grpc.unary_unary_rpc_method_handler(
+                    servicer.ListTools,
+                    request_deserializer=cortexdb_dot_v1_dot_tools__pb2.ListToolsRequest.FromString,
+                    response_serializer=cortexdb_dot_v1_dot_tools__pb2.ListToolsResponse.SerializeToString,
+            ),
+            'CallTool': grpc.unary_unary_rpc_method_handler(
+                    servicer.CallTool,
+                    request_deserializer=cortexdb_dot_v1_dot_tools__pb2.CallToolRequest.FromString,
+                    response_serializer=cortexdb_dot_v1_dot_tools__pb2.CallToolResponse.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'cortexdb.v1.ToolsService', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers('cortexdb.v1.ToolsService', rpc_method_handlers)
+
+
+ # This class is part of an EXPERIMENTAL API.
+class ToolsService:
+    """Missing associated documentation comment in .proto file."""
+
+    @staticmethod
+    def ListTools(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/cortexdb.v1.ToolsService/ListTools',
+            cortexdb_dot_v1_dot_tools__pb2.ListToolsRequest.SerializeToString,
+            cortexdb_dot_v1_dot_tools__pb2.ListToolsResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def CallTool(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/cortexdb.v1.ToolsService/CallTool',
+            cortexdb_dot_v1_dot_tools__pb2.CallToolRequest.SerializeToString,
+            cortexdb_dot_v1_dot_tools__pb2.CallToolResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)

cortexdb_client/client.py

@@ -0,0 +1,80 @@
+"""The CortexClient facade — mirrors the Rust crate's sub-client layout."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import grpc
+
+from ._pb.cortexdb.v1 import admin_pb2_grpc, graph_pb2_grpc, graphrag_pb2_grpc
+from ._pb.cortexdb.v1 import knowledge_pb2_grpc, memory_pb2_grpc, tools_pb2_grpc
+
+
+def _bearer_interceptor(token: str) -> grpc.UnaryUnaryClientInterceptor:
+    """Attach ``authorization: Bearer <token>`` to every unary call."""
+
+    class _Interceptor(grpc.UnaryUnaryClientInterceptor):
+        def intercept_unary_unary(self, continuation, client_call_details, request):
+            metadata = list(client_call_details.metadata or [])
+            metadata.append(("authorization", f"Bearer {token}"))
+            new_details = client_call_details._replace(metadata=metadata)
+            return continuation(new_details, request)
+
+    return _Interceptor()
+
+
+class CortexClient:
+    """One connection to a CortexDB sidecar, exposing all service clients.
+
+    Construct with :meth:`connect`. Use as a context manager to close the
+    channel automatically, or call :meth:`close` yourself.
+    """
+
+    def __init__(self, channel: grpc.Channel):
+        self._channel = channel
+        self.knowledge = knowledge_pb2_grpc.KnowledgeServiceStub(channel)
+        self.memory = memory_pb2_grpc.MemoryServiceStub(channel)
+        self.graph = graph_pb2_grpc.KnowledgeGraphServiceStub(channel)
+        self.graphrag = graphrag_pb2_grpc.GraphRagServiceStub(channel)
+        self.tools = tools_pb2_grpc.ToolsServiceStub(channel)
+        self.admin = admin_pb2_grpc.AdminServiceStub(channel)
+
+    @classmethod
+    def connect(
+        cls,
+        endpoint: str,
+        token: Optional[str] = None,
+        *,
+        secure: bool = False,
+        credentials: Optional[grpc.ChannelCredentials] = None,
+    ) -> "CortexClient":
+        """Connect to ``endpoint`` (``host:port``, optional ``http(s)://`` prefix).
+
+        Pass ``token`` to authenticate every request with a bearer token. The
+        sidecar listens on plaintext by default; set ``secure=True`` (and
+        optionally ``credentials``) when fronting it with TLS.
+        """
+        target = endpoint
+        for prefix in ("http://", "https://"):
+            if target.startswith(prefix):
+                target = target[len(prefix):]
+                break
+
+        if secure:
+            channel = grpc.secure_channel(target, credentials or grpc.ssl_channel_credentials())
+        else:
+            channel = grpc.insecure_channel(target)
+
+        if token:
+            channel = grpc.intercept_channel(channel, _bearer_interceptor(token))
+
+        return cls(channel)
+
+    def close(self) -> None:
+        self._channel.close()
+
+    def __enter__(self) -> "CortexClient":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()

cortexdb_client/proto.py

@@ -0,0 +1,24 @@
+"""Re-exports of the generated ``cortexdb.v1`` protobuf message types.
+
+Use these as ``proto.SaveKnowledgeRequest(...)`` etc. The grpc service stubs
+live alongside but are wired up by :mod:`cortexdb_client.client`; application
+code should only need the message types from here.
+"""
+
+from ._pb.cortexdb.v1 import common_pb2 as _common
+from ._pb.cortexdb.v1 import knowledge_pb2 as _knowledge
+from ._pb.cortexdb.v1 import memory_pb2 as _memory
+from ._pb.cortexdb.v1 import graph_pb2 as _graph
+from ._pb.cortexdb.v1 import graphrag_pb2 as _graphrag
+from ._pb.cortexdb.v1 import tools_pb2 as _tools
+from ._pb.cortexdb.v1 import admin_pb2 as _admin
+
+_modules = (_common, _knowledge, _memory, _graph, _graphrag, _tools, _admin)
+
+# Flatten every generated message class into this module's namespace so callers
+# can write proto.SaveKnowledgeRequest instead of knowledge_pb2.SaveKnowledgeRequest.
+__all__ = []
+for _m in _modules:
+    for _name in getattr(_m, "DESCRIPTOR").message_types_by_name:
+        globals()[_name] = getattr(_m, _name)
+        __all__.append(_name)

cortexdb_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: cortexdb-client
+Version: 0.1.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'
+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`.
+
+## 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.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+cortexdb_client/__init__.py,sha256=nsOEhmpqzVrrFUJfRb4GQ3S1JPei625oiP4TApzOYxI,784
+cortexdb_client/client.py,sha256=NRRC9CVOnZzbClZRTehjXIPg51vAZ8bAtR6W_GrUK4s,2846
+cortexdb_client/proto.py,sha256=sJMNaSoLgoliJ5I4IRztWC-14f6LfjGnjaxUEN0_4oM,1064
+cortexdb_client/_pb/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cortexdb_client/_pb/cortexdb/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cortexdb_client/_pb/cortexdb/v1/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cortexdb_client/_pb/cortexdb/v1/admin_pb2.py,sha256=gm39Tljd0iEuYElFrjbQBobvqhLUv-fRTm3IE2qucFQ,2275
+cortexdb_client/_pb/cortexdb/v1/admin_pb2_grpc.py,sha256=fhkvXsb13R0PZAlHfVOQic1vGC7kZ_gLCDiaF5S1cCA,5276
+cortexdb_client/_pb/cortexdb/v1/common_pb2.py,sha256=eL8eUb6ukDbqn-mB4Cus33Ic3CMLAOuMh9TIhBgtxJk,4619
+cortexdb_client/_pb/cortexdb/v1/common_pb2_grpc.py,sha256=tZbcHDkTGGGegvbUgSnfUxQtkbSxi2-Vf4dEqPLEPXM,898
+cortexdb_client/_pb/cortexdb/v1/graph_pb2.py,sha256=voKi1pdozp_rdu1_6ztcx8WdJ-ffL4xIStGFZh4yz84,19806
+cortexdb_client/_pb/cortexdb/v1/graph_pb2_grpc.py,sha256=8RQaJfoJZppxcrgR1VfGgQeqBiv1_UHq02pU1C3VLtE,34494
+cortexdb_client/_pb/cortexdb/v1/graphrag_pb2.py,sha256=xj6DWnJwb-pnD5jn_WQg3Ls5SBgjmKDhCWfCMDFZ8SE,8731
+cortexdb_client/_pb/cortexdb/v1/graphrag_pb2_grpc.py,sha256=tvcbJaNZycqL0t-XMMEOX75FoHP8Gn3Oc1tp3p3E-KA,13113
+cortexdb_client/_pb/cortexdb/v1/knowledge_pb2.py,sha256=ayfvcKU4VRQoH9HjQeriTOJHoZ0bfKDngPjnFcqVpbg,9618
+cortexdb_client/_pb/cortexdb/v1/knowledge_pb2_grpc.py,sha256=2ilQ73FbQsoUq1JoobGH-P8RGNEysHAs_i2Piz4FAyQ,11274
+cortexdb_client/_pb/cortexdb/v1/memory_pb2.py,sha256=pzU0tAHQjL6oJ0TYiGCHfSnyAG2Z0_4uDaW6D2UHsEI,6246
+cortexdb_client/_pb/cortexdb/v1/memory_pb2_grpc.py,sha256=dYmm8pqNNqAYBQW9IDuo3XZpd0Y5yKOD_JjAjewdHLE,10932
+cortexdb_client/_pb/cortexdb/v1/tools_pb2.py,sha256=3p0s0bd84LhEb1Z8_lcoFSS0LXuNEW-5D4wi9aR92GI,2623
+cortexdb_client/_pb/cortexdb/v1/tools_pb2_grpc.py,sha256=jOSBnUfigrrcYKaoozkqEB92ARefiVVkT1Fyg5aq3a4,5367
+cortexdb_client-0.1.0.dist-info/METADATA,sha256=PTqrtZPnGxi_L_9UBvaLYCxsq55z1MdiNl-frw2p0gc,2991
+cortexdb_client-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+cortexdb_client-0.1.0.dist-info/RECORD,,

cortexdb_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any