superb-memory 0.2.1__tar.gz → 0.2.3__tar.gz

{superb_memory-0.2.1 → superb_memory-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superb-memory
-Version: 0.2.1
+Version: 0.2.3
 Summary: Python client, mdb CLI and MCP server for the MemoryDB Go document and agent memory database
 Author: humaniods
 License-Expression: MIT

{superb_memory-0.2.1 → superb_memory-0.2.3}/cli.py

@@ -11,6 +11,7 @@ import hashlib
 import json
 import os
 import platform
+import re
 import secrets
 import shutil
 import subprocess
@@ -23,7 +24,7 @@ from urllib.parse import urlparse
 sys.path.insert(0, str(os.path.dirname(os.path.abspath(__file__))))
 from memorydb import MemoryDB, MemoryDBError  # noqa: E402
 
-SERVER_VERSION = "0.2.1"          # the release tag mdb serve downloads by default
+SERVER_VERSION = "0.2.3"          # the release tag mdb serve downloads by default
 REPO = "humaniods/MemoryDB"
 
 
@@ -37,10 +38,22 @@ def load_db(args):
     return MemoryDB(url, token=token)
 
 
-def read_json_arg(value, path):
-    if path:
+def read_json_file(path):
+    """Read a JSON input file named on the command line.
+
+    Paths in these commands come from README and docs, so a wrong one has to name the
+    file instead of raising a traceback from wherever argparse happened to call us.
+    """
+    try:
         with open(path) as fh:
             return json.load(fh)
+    except OSError as exc:
+        sys.exit(f"mdb: cannot read {path}: {exc.strerror or exc}")
+
+
+def read_json_arg(value, path):
+    if path:
+        return read_json_file(path)
     if value:
         return json.loads(value)
     sys.exit("provide --json or --file")
@@ -50,6 +63,37 @@ def emit(obj):
     print(json.dumps(obj, indent=2, default=str))
 
 
+def parse_where(value):
+    """Accept the API's JSON for --where, and the field=value shorthand `mdb demo` prints.
+
+    Shell quoting is fiddly enough that a hint has to work exactly as typed, so
+    region="Rajasthan" and region=Rajasthan both mean one equality term.
+    """
+    try:
+        parsed = json.loads(value)
+    except json.JSONDecodeError:
+        parsed = None
+    if isinstance(parsed, dict):
+        return [parsed]
+    if isinstance(parsed, list):
+        return parsed
+    terms = []
+    for chunk in re.split(r",|\s+and\s+", value.strip()):
+        field, sep, raw = chunk.strip().partition("=")
+        if not sep or not field.strip():
+            sys.exit('mdb: --where wants JSON like [{"field":"region","op":"eq","value":"Rajasthan"}] '
+                     "or field=value terms, got: " + value)
+        raw = raw.strip().strip("\"'")
+        for cast in (int, float):
+            try:
+                raw = cast(raw)
+                break
+            except ValueError:
+                continue
+        terms.append({"field": field.strip(), "op": "eq", "value": raw})
+    return terms
+
+
 # -- mdb serve: the database itself, installed over pip, with no Go or git -----------------
 def home():
     path = os.environ.get("MEMORYDB_HOME") or os.path.join(os.path.expanduser("~"), ".memorydb")
@@ -226,7 +270,7 @@ def main(argv=None):
     p.add_argument("--json"); p.add_argument("--file"); p.add_argument("--version", type=int)
 
     p = sub.add_parser("query"); p.add_argument("collection")
-    p.add_argument("--where", default="[]"); p.add_argument("--order"); p.add_argument("--desc", action="store_true")
+    p.add_argument("--where", default="[]", help='[{"field":…,"op":…,"value":…}] or region=Rajasthan shorthand'); p.add_argument("--order"); p.add_argument("--desc", action="store_true")
     p.add_argument("--limit", type=int, default=50); p.add_argument("--fields", help="comma-separated projection")
 
     p = sub.add_parser("memory"); p.add_argument("action", choices=["add", "ls", "history"])
@@ -236,8 +280,19 @@ def main(argv=None):
     p = sub.add_parser("search"); p.add_argument("text")
     p.add_argument("--kind", default=""); p.add_argument("--limit", type=int, default=10)
 
-    p = sub.add_parser("ingest"); p.add_argument("--file", required=True)
-    p = sub.add_parser("tx"); p.add_argument("--file", required=True); p.add_argument("--key")
+    p = sub.add_parser("ingest"); p.add_argument("--file", required=True, help='{"messages":[…],"facts":[…],"source":…}')
+    p = sub.add_parser("tx"); p.add_argument("--file", required=True, help='{"changes":[{"record":…,"expected":N}]}'); p.add_argument("--key")
+
+    p = sub.add_parser("sync", help="mirror an external table; writes only the rows that changed")
+    p.add_argument("source"); p.add_argument("--collection", required=True)
+    p.add_argument("--file", help="JSON array of rows (or objects with data/content)")
+    p.add_argument("--json", help="the same array inline")
+    p.add_argument("--key-field", default="id"); p.add_argument("--delete-missing", action="store_true")
+    p.add_argument("--tag", dest="source_tag", default="", help="value stored as the row's source")
+    p.add_argument("--idempotency-key")
+
+    p = sub.add_parser("sources"); p.add_argument("action", choices=["ls"], nargs="?", default="ls")
+    p = sub.add_parser("demo", help="load the built-in sample workspace into the server")
 
     p = sub.add_parser("serve", help="install (if needed) and run the MemoryDB server")
     p.add_argument("--addr", default="127.0.0.1:8080")
@@ -277,7 +332,7 @@ def main(argv=None):
             else:
                 emit(db.collection(args.collection).objects.delete(pk=args.id, version=args.version))
         elif args.cmd == "query":
-            q = {"where": json.loads(args.where), "limit": args.limit}
+            q = {"where": parse_where(args.where), "limit": args.limit}
             if args.order:
                 q["order_by"] = args.order
                 q["descending"] = args.desc
@@ -290,17 +345,28 @@ def main(argv=None):
             elif args.action == "ls":
                 emit(db.objects.filter(kind=args.kind if args.kind != "fact" else "", source=args.source, q=args.q, limit=args.limit))
             else:
-                emit(db.objects.history(pk=args.id)["results"])
+                emit(db.objects.history(pk=args.id))
         elif args.cmd == "search":
             emit(db.objects.search(args.text, kind=args.kind, limit=args.limit))
         elif args.cmd == "ingest":
-            with open(args.file) as fh:
-                payload = json.load(fh)
-            emit(db.ingest(payload["messages"], facts=payload.get("facts"), source=payload.get("source", "cli")))
+            payload = read_json_file(args.file)
+            emit(db.ingest(payload["messages"], facts=payload.get("facts"),
+                           source=payload.get("source", "cli"),
+                           context=payload.get("context", "")))
         elif args.cmd == "tx":
-            with open(args.file) as fh:
-                payload = json.load(fh)
+            payload = read_json_file(args.file)
             emit(db.transaction(payload["changes"], idempotency_key=args.key))
+        elif args.cmd == "sync":
+            rows = read_json_arg(args.json, args.file)
+            if not isinstance(rows, list):
+                sys.exit("sync input must be a JSON array of rows")
+            emit(db.sources.sync(args.source, collection=args.collection, items=rows,
+                                 key_field=args.key_field, delete_missing=args.delete_missing,
+                                 source=args.source_tag, idempotency_key=args.idempotency_key))
+        elif args.cmd == "sources":
+            emit(db.sources.all())
+        elif args.cmd == "demo":
+            emit(db.demo_seed())
     except MemoryDBError as exc:
         sys.exit(f"mdb error [{exc.status}]: {exc}")
     return 0

{superb_memory-0.2.1 → superb_memory-0.2.3}/memorydb.py

@@ -59,6 +59,28 @@ def parse_connection_string(connection_string):
     return scheme + "://" + host + ":" + str(port), unquote(parts.username)
 
 
+class SourceManager:
+    """Mirror an external table into a collection.
+
+    A sync writes only the rows whose data changed since the last sync, so a cron job
+    that re-pulls a whole CSV or REST list costs one read, not a rewrite of every row.
+    """
+
+    def __init__(self, client):
+        self.client = client
+
+    def sync(self, name, *, collection, items, key_field="id", delete_missing=False, source="", idempotency_key=None):
+        """items is a list of dicts (one row each) or of {"data": {...}, "content": "..."} pairs."""
+        rows = [{"data": i, "content": ""} if isinstance(i, dict) and "data" not in i else i for i in items]
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self.client.request("POST", "sources/" + quote(name, safe="") + "/sync/",
+                                   dict(collection=collection, key_field=key_field, items=rows,
+                                        delete_missing=delete_missing, source=source), headers=headers)
+
+    def all(self):
+        return self.client.request("GET", "sources/")["results"]
+
+
 class MemoryDB:
     def __init__(self, url="http://127.0.0.1:8080", *, token=None, timeout=35):
         if token is None:
@@ -74,6 +96,7 @@ class MemoryDB:
         self.timeout = timeout
         self.objects = MemoryManager(self)
         self.collections = CollectionManager(self)
+        self.sources = SourceManager(self)
 
     @classmethod
     def from_url(cls, connection_string, **fields):
@@ -95,6 +118,13 @@ class MemoryDB:
     def queue_ingest(self, **payload):
         return self.request("POST", "jobs/", payload)
 
+    def demo_seed(self):
+        """Load the built-in sample workspace (four mirrored tables, notes and facts).
+
+        Safe to call twice: a workspace that already has the sample is left alone.
+        """
+        return self.request("POST", "demo/", None)
+
     def request(self, method, path, body=None, headers=None):
         req = Request(self.url + path, data=json.dumps(body).encode() if body is not None else None,
                       headers={"Authorization": "Bearer " + self.token, "Content-Type": "application/json", **(headers or {})}, method=method)

{superb_memory-0.2.1 → superb_memory-0.2.3}/memorydb_mcp.py

@@ -17,7 +17,7 @@ sys.path.insert(0, str(__import__("pathlib").Path(__file__).resolve().parent))
 from memorydb import MemoryDB  # noqa: E402
 
 PROTOCOL_VERSION = "2024-11-05"
-SERVER_INFO = {"name": "memorydb", "version": "0.2.1"}
+SERVER_INFO = {"name": "memorydb", "version": "0.2.3"}
 
 TOOL_DEFS = [
     {"name": "memorydb_health", "description": "Server status, identity and transaction sequence.",
@@ -62,6 +62,20 @@ TOOL_DEFS = [
          "order_by": {"type": "string"}, "descending": {"type": "boolean"},
          "projection": {"type": "array", "items": {"type": "string"}},
          "limit": {"type": "integer", "default": 50}}, "required": ["collection"]}},
+    {"name": "memorydb_sync", "description": "Mirror a table/CSV/REST list into a collection. Only rows whose data changed are written; re-running is cheap.",
+     "inputSchema": {"type": "object", "properties": {
+         "source": {"type": "string", "description": "connector name, e.g. stripe or postgres"},
+         "collection": {"type": "string"},
+         "key_field": {"type": "string", "default": "id"},
+         "items": {"type": "array", "items": {"type": "object", "properties": {
+             "data": {"type": "object"}, "content": {"type": "string"}}},
+             "description": "up to 500 rows; each row must carry key_field"},
+         "delete_missing": {"type": "boolean", "default": False}},
+         "required": ["source", "collection", "items"]}},
+    {"name": "memorydb_list_sources", "description": "List the connectors that own rows in this workspace, with row counts and last sync time.",
+     "inputSchema": {"type": "object", "properties": {}}},
+    {"name": "memorydb_demo", "description": "Load the built-in sample workspace (four mirrored tables, notes and facts) so the console and search have data. Idempotent.",
+     "inputSchema": {"type": "object", "properties": {}}},
 ]
 
 
@@ -93,6 +107,14 @@ def handle(db, method, params):
     if method == "memorydb_query_documents":
         q = {k: v for k, v in params.items() if k != "collection"}
         return db.request("POST", "query/" + params["collection"] + "/", q)
+    if method == "memorydb_sync":
+        return db.sources.sync(params["source"], collection=params["collection"], items=params["items"],
+                               key_field=params.get("key_field", "id"),
+                               delete_missing=params.get("delete_missing", False))
+    if method == "memorydb_list_sources":
+        return db.sources.all()
+    if method == "memorydb_demo":
+        return db.demo_seed()
     raise ValueError("unknown tool " + method)
 
 

{superb_memory-0.2.1 → superb_memory-0.2.3}/pyproject.toml

@@ -3,7 +3,7 @@ requires = ["setuptools>=77"]
 build-backend = "setuptools.build_meta"
 [project]
 name = "superb-memory"
-version = "0.2.1"
+version = "0.2.3"
 description = "Python client, mdb CLI and MCP server for the MemoryDB Go document and agent memory database"
 readme = "README.md"
 requires-python = ">=3.10"

{superb_memory-0.2.1 → superb_memory-0.2.3}/superb_memory.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superb-memory
-Version: 0.2.1
+Version: 0.2.3
 Summary: Python client, mdb CLI and MCP server for the MemoryDB Go document and agent memory database
 Author: humaniods
 License-Expression: MIT