pythia-mongo 0.1.0__py3-none-any.whl

pythia_mongo/__init__.py

@@ -0,0 +1,5 @@
+"""pythia for MongoDB: database development for AI agents, over pythia-core.
+Alpha — see README.md for what works today."""
+__version__ = "0.1.0"     # kept equal to pyproject.toml (tests/test_mongo.py)
+
+from .engine import MongoEngine  # noqa: E402,F401 — needs __version__ first

pythia_mongo/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

pythia_mongo/catalog.py

@@ -0,0 +1,124 @@
+"""Where pythia-mongo's commands live and how they are run.
+
+MongoDB takes command documents, not SQL. Every command pythia-mongo sends
+is a file in commands/, under the contract the SQL engines keep for their
+query files: what it is for, the binds it takes, what it returns, and
+nothing else — reviewable in isolation. A bind is written {"$bind": "name"}
+where its value goes, so text from a person or an agent always lands as a
+value, never as an operator or a command of its own.
+"""
+import json
+import pathlib
+import re
+import sys
+
+COMMAND_DIR = pathlib.Path(__file__).resolve().parent / "commands"
+
+COMMAND_BINDS = {
+    "server-build.json": set(),
+    "server-hello.json": set(),
+    "collections.json": {"p"},
+    "collection.json": {"n"},
+    "indexes.json": {"n"},
+    "sample.json": {"n", "k"},
+    "count.json": {"n"},
+    "invalid.json": {"n", "v"},
+    "view-run.json": {"n", "k"},
+    "probe.json": {"n", "f"},
+    "probe-sample.json": {"n", "f", "k"},
+    "duplicates.json": {"n", "f", "g"},
+    "pipeline-run.json": {"n", "p"},
+    "connection-status.json": set(),
+}
+
+# every command file reads: never a write, a $out or a $merge (the suite
+# checks). A statement's own command is not a file: it is the developer's.
+READ_COMMANDS = frozenset(COMMAND_BINDS)
+
+# commands whose answer is a cursor to read to the end
+CURSOR_COMMANDS = ("listCollections", "listIndexes", "aggregate", "find")
+
+_CACHE = {}
+
+
+def _load(name):
+    if name not in _CACHE:
+        path = COMMAND_DIR / name
+        if name not in COMMAND_BINDS or not path.is_file():
+            sys.exit(f"No command file {name} in {COMMAND_DIR}.")
+        _CACHE[name] = json.loads(path.read_text(encoding="utf-8"))
+    return _CACHE[name]
+
+
+def placeholders(value):
+    """Every bind name a command document uses."""
+    if isinstance(value, dict):
+        if set(value) == {"$bind"}:
+            return {value["$bind"]}
+        return set().union(*(placeholders(v) for v in value.values())) if value else set()
+    if isinstance(value, list):
+        return set().union(*(placeholders(v) for v in value)) if value else set()
+    return set()
+
+
+def _fill(value, binds):
+    if isinstance(value, dict):
+        if set(value) == {"$bind"}:
+            return binds[value["$bind"]]
+        return {k: _fill(v, binds) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_fill(v, binds) for v in value]
+    return value
+
+
+def command_of(name, **binds):
+    """The command document of one file, its binds in place. A bind the
+    file declares and the caller left out, or one it does not declare, is
+    refused rather than guessed at."""
+    doc = _load(name)
+    want = COMMAND_BINDS[name]
+    if set(binds) != want:
+        gap = sorted(want - set(binds))
+        extra = sorted(set(binds) - want)
+        sys.exit(f"{name}: " + "; ".join(
+            ([f"bind {', '.join(gap)} not given"] if gap else [])
+            + ([f"{', '.join(extra)} is not a bind of this command"] if extra else [])))
+    return _fill(doc["command"], binds)
+
+
+def run(conn, name, **binds):
+    """The answer to one command file: every document of a cursor, or the
+    reply document."""
+    command = command_of(name, **binds)
+    cursor = next(iter(command)) in CURSOR_COMMANDS
+    return conn.run(name, command, cursor, _load(name).get("database") == "admin")
+
+
+def like_regex(pattern):
+    """A LIKE-style pattern (% any run, _ one character) as an anchored,
+    case-sensitive regular expression — MongoDB names are case-sensitive."""
+    return "^" + "".join(".*" if c == "%" else "." if c == "_" else re.escape(c)
+                         for c in str(pattern)) + "$"
+
+
+def ejson(value, indent=2):
+    """value as relaxed Extended JSON: ObjectId, dates and decimals keep
+    their type ({"$oid": ...}), plain values read as plain JSON."""
+    try:
+        from bson import json_util
+    except ImportError:                       # the suite runs without the driver
+        return json.dumps(value, indent=indent, default=str, ensure_ascii=False)
+    return json_util.dumps(value, json_options=json_util.RELAXED_JSON_OPTIONS,
+                           indent=indent, ensure_ascii=False)
+
+
+def to_bson(value):
+    """A value parsed from a statement as plain JSON, with its Extended JSON
+    forms ({"$oid": ...}, {"$date": ...}) turned into BSON types, as the
+    server must receive them."""
+    try:
+        from bson import json_util
+    except ImportError:                       # the suite runs without the driver
+        return value
+    return json_util.loads(json.dumps(value))
+

pythia_mongo/cli.py

@@ -0,0 +1,8 @@
+"""The `pythia-mongo` command: pythia-core's command line, handed this engine."""
+from pythia_core import cli
+
+from .engine import MongoEngine
+
+
+def main(argv=None):
+    return cli.main(MongoEngine(), argv)

pythia_mongo/commands/collection.json

@@ -0,0 +1,16 @@
+{
+  "purpose": "one collection or view by its exact name",
+  "binds": {
+    "n": "the name, as written"
+  },
+  "returns": "listCollections cursor: at most one document (name, type, options)",
+  "command": {
+    "listCollections": 1,
+    "filter": {
+      "name": {
+        "$bind": "n"
+      }
+    },
+    "nameOnly": false
+  }
+}

pythia_mongo/commands/collections.json

@@ -0,0 +1,29 @@
+{
+  "purpose": "every collection and view whose name matches a pattern, system collections left out",
+  "binds": {
+    "p": "the name as an anchored regular expression (catalog.like_regex)"
+  },
+  "returns": "listCollections cursor: name, type, options (validator, validationLevel, validationAction, viewOn, pipeline, ...)",
+  "command": {
+    "listCollections": 1,
+    "filter": {
+      "$and": [
+        {
+          "name": {
+            "$regex": {
+              "$bind": "p"
+            }
+          }
+        },
+        {
+          "name": {
+            "$not": {
+              "$regex": "^system\\."
+            }
+          }
+        }
+      ]
+    },
+    "nameOnly": false
+  }
+}

pythia_mongo/commands/connection-status.json

@@ -0,0 +1,8 @@
+{
+  "purpose": "who this connection is, and the roles it holds, for the privilege warning",
+  "binds": {},
+  "returns": "connectionStatus: authInfo (authenticatedUsers, authenticatedUserRoles)",
+  "command": {
+    "connectionStatus": 1
+  }
+}

pythia_mongo/commands/count.json

@@ -0,0 +1,12 @@
+{
+  "purpose": "about how many documents a collection holds (from its metadata, without a scan)",
+  "binds": {
+    "n": "the collection or view"
+  },
+  "returns": "count: n",
+  "command": {
+    "count": {
+      "$bind": "n"
+    }
+  }
+}

pythia_mongo/commands/duplicates.json

@@ -0,0 +1,43 @@
+{
+  "purpose": "the keys a unique index would meet more than once, for its prediction",
+  "binds": {
+    "n": "the collection",
+    "f": "the documents the index holds (partialFilterExpression, or the sparse rule)",
+    "g": "the index key as a group key: {field: \"$field\"}"
+  },
+  "returns": "aggregate cursor: up to 3 documents {_id: the key, n}",
+  "command": {
+    "aggregate": {
+      "$bind": "n"
+    },
+    "pipeline": [
+      {
+        "$match": {
+          "$bind": "f"
+        }
+      },
+      {
+        "$group": {
+          "_id": {
+            "$bind": "g"
+          },
+          "n": {
+            "$sum": 1
+          }
+        }
+      },
+      {
+        "$match": {
+          "n": {
+            "$gt": 1
+          }
+        }
+      },
+      {
+        "$limit": 3
+      }
+    ],
+    "cursor": {},
+    "maxTimeMS": 30000
+  }
+}

pythia_mongo/commands/indexes.json

@@ -0,0 +1,12 @@
+{
+  "purpose": "the indexes of one collection, for `ddl`",
+  "binds": {
+    "n": "the collection's name"
+  },
+  "returns": "listIndexes cursor: v, key, name and each index's options",
+  "command": {
+    "listIndexes": {
+      "$bind": "n"
+    }
+  }
+}

pythia_mongo/commands/invalid.json

@@ -0,0 +1,45 @@
+{
+  "purpose": "how many documents break a collection's validator as it stands, and the first of them",
+  "binds": {
+    "n": "the collection",
+    "v": "its validator, as listCollections gives it"
+  },
+  "returns": "aggregate cursor: one document {n: [{n}], first: [{_id}]}",
+  "command": {
+    "aggregate": {
+      "$bind": "n"
+    },
+    "pipeline": [
+      {
+        "$match": {
+          "$nor": [
+            {
+              "$bind": "v"
+            }
+          ]
+        }
+      },
+      {
+        "$facet": {
+          "n": [
+            {
+              "$count": "n"
+            }
+          ],
+          "first": [
+            {
+              "$limit": 3
+            },
+            {
+              "$project": {
+                "_id": 1
+              }
+            }
+          ]
+        }
+      }
+    ],
+    "cursor": {},
+    "maxTimeMS": 30000
+  }
+}

pythia_mongo/commands/pipeline-run.json

@@ -0,0 +1,18 @@
+{
+  "purpose": "a view's pipeline run over its source, for its prediction: once over no documents (does MongoDB accept it?) and once over the first documents (does it run?)",
+  "binds": {
+    "n": "the collection or view the pipeline reads",
+    "p": "the pipeline, ending in $count; classify refuses $out, $merge and JavaScript in any statement it comes from"
+  },
+  "returns": "aggregate cursor: one document {n}, or none",
+  "command": {
+    "aggregate": {
+      "$bind": "n"
+    },
+    "pipeline": {
+      "$bind": "p"
+    },
+    "cursor": {},
+    "maxTimeMS": 30000
+  }
+}

pythia_mongo/commands/probe-sample.json

@@ -0,0 +1,28 @@
+{
+  "purpose": "the first documents an UPDATE or DELETE filter matches, for the preview",
+  "binds": {
+    "n": "the collection",
+    "f": "the statement's own filter",
+    "k": "one more than are shown, so a cut is announced"
+  },
+  "returns": "aggregate cursor: the documents",
+  "command": {
+    "aggregate": {
+      "$bind": "n"
+    },
+    "pipeline": [
+      {
+        "$match": {
+          "$bind": "f"
+        }
+      },
+      {
+        "$limit": {
+          "$bind": "k"
+        }
+      }
+    ],
+    "cursor": {},
+    "maxTimeMS": 30000
+  }
+}

pythia_mongo/commands/probe.json

@@ -0,0 +1,37 @@
+{
+  "purpose": "how many documents an UPDATE or DELETE filter matches, and an order-independent fingerprint of them (any document joining, leaving or changing moves it)",
+  "binds": {
+    "n": "the collection",
+    "f": "the statement's own filter"
+  },
+  "returns": "aggregate cursor: one document {n, h}, or none when nothing matches",
+  "command": {
+    "aggregate": {
+      "$bind": "n"
+    },
+    "pipeline": [
+      {
+        "$match": {
+          "$bind": "f"
+        }
+      },
+      {
+        "$group": {
+          "_id": null,
+          "n": {
+            "$sum": 1
+          },
+          "h": {
+            "$sum": {
+              "$toDecimal": {
+                "$toHashedIndexKey": "$$ROOT"
+              }
+            }
+          }
+        }
+      }
+    ],
+    "cursor": {},
+    "maxTimeMS": 30000
+  }
+}

pythia_mongo/commands/sample.json

@@ -0,0 +1,23 @@
+{
+  "purpose": "a random sample of documents, for `cols` to read field names and types from",
+  "binds": {
+    "n": "the collection or view",
+    "k": "how many documents at most"
+  },
+  "returns": "aggregate cursor: the sampled documents",
+  "command": {
+    "aggregate": {
+      "$bind": "n"
+    },
+    "pipeline": [
+      {
+        "$sample": {
+          "size": {
+            "$bind": "k"
+          }
+        }
+      }
+    ],
+    "cursor": {}
+  }
+}

pythia_mongo/commands/server-build.json

@@ -0,0 +1,9 @@
+{
+  "purpose": "the server's version, for `check`",
+  "binds": {},
+  "returns": "buildInfo: version",
+  "database": "admin",
+  "command": {
+    "buildInfo": 1
+  }
+}

pythia_mongo/commands/server-hello.json

@@ -0,0 +1,9 @@
+{
+  "purpose": "what this server is: standalone, a replica set member (primary or not), or mongos",
+  "binds": {},
+  "returns": "hello: setName, isWritablePrimary, secondary, msg",
+  "database": "admin",
+  "command": {
+    "hello": 1
+  }
+}

pythia_mongo/commands/view-run.json

@@ -0,0 +1,24 @@
+{
+  "purpose": "whether a view's pipeline still runs, over its first documents",
+  "binds": {
+    "n": "the view",
+    "k": "how many documents to run it on"
+  },
+  "returns": "aggregate cursor: one document {n} (or none for an empty view)",
+  "command": {
+    "aggregate": {
+      "$bind": "n"
+    },
+    "pipeline": [
+      {
+        "$limit": {
+          "$bind": "k"
+        }
+      },
+      {
+        "$count": "n"
+      }
+    ],
+    "cursor": {}
+  }
+}