korm 2.0.0a3__py3-none-any.whl

korm/__init__.py

@@ -0,0 +1,32 @@
+"""korm — reference implementation of the KORM Protocol v2.
+
+KORM is a JSON request/response protocol for dynamic database operations::
+
+    import korm
+
+    db = korm.initialize_korm(url="sqlite:///app.db", schema="korm.schema.json")
+    result = db.process_sync({"korm": 2, "action": "list", "model": "users",
+                              "where": {"age": {"gte": 18}}, "limit": 20})
+"""
+from .facade import PROTOCOL_VERSION, SPEC_VERSION, Korm, initialize_korm
+from .protocol.errors import ErrorCode, KormError
+from .schema.introspect import diff, generate_schema, sync_database
+from .policy import Policy
+from .schema import Schema
+
+__version__ = "2.0.0a3"
+
+__all__ = [
+    "Korm",
+    "initialize_korm",
+    "Schema",
+    "Policy",
+    "ErrorCode",
+    "KormError",
+    "generate_schema",
+    "sync_database",
+    "diff",
+    "PROTOCOL_VERSION",
+    "SPEC_VERSION",
+    "__version__",
+]

korm/cli/__init__.py

@@ -0,0 +1,110 @@
+"""korm CLI: init, generate-schema, sync, diff, serve-mcp (spec §13)."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import sqlalchemy as sa
+
+from .. import __version__
+from ..schema.introspect import diff as schema_diff
+from ..schema.introspect import generate_schema, sync_database
+from ..schema import Schema
+
+_EXAMPLE_SCHEMA = {
+    "kormSchema": 2,
+    "models": {
+        "users": {
+            "table": "users",
+            "primaryKey": ["id"],
+            "softDelete": {"column": "deleted_at"},
+            "timestamps": {"createdAt": "created_at", "updatedAt": "updated_at"},
+            "columns": {
+                "id": {"type": "increments"},
+                "username": {"type": "string", "length": 80, "unique": True, "required": True},
+                "email": {"type": "string", "format": "email", "required": True},
+                "is_active": {"type": "boolean", "default": True},
+                "created_at": {"type": "datetime", "nullable": True},
+                "updated_at": {"type": "datetime", "nullable": True},
+                "deleted_at": {"type": "datetime", "nullable": True},
+            },
+        }
+    },
+}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="korm", description="KORM Protocol v2 tooling")
+    parser.add_argument("--version", action="version", version=f"korm {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_init = sub.add_parser("init", help="scaffold a korm.schema.json in the current directory")
+    p_init.add_argument("--ai", help="AI provider preset for agent tooling (recorded in the scaffold)")
+    p_init.add_argument("--out", default="korm.schema.json")
+
+    p_gen = sub.add_parser("generate-schema", help="introspect a database into korm.schema.json")
+    p_gen.add_argument("--url", required=True)
+    p_gen.add_argument("--out", default="korm.schema.json")
+
+    p_sync = sub.add_parser("sync", help="create missing tables from the schema (dev tool)")
+    p_sync.add_argument("--url", required=True)
+    p_sync.add_argument("--schema", default="korm.schema.json")
+
+    p_diff = sub.add_parser("diff", help="print a migration skeleton: schema vs live database")
+    p_diff.add_argument("--url", required=True)
+    p_diff.add_argument("--schema", default="korm.schema.json")
+
+    p_mcp = sub.add_parser("serve-mcp", help="serve per-model MCP tools over stdio")
+    p_mcp.add_argument("--url", required=True)
+    p_mcp.add_argument("--schema", default="korm.schema.json")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "init":
+        out = Path(args.out)
+        if out.exists():
+            print(f"{out} already exists; not overwriting", file=sys.stderr)
+            return 1
+        scaffold = dict(_EXAMPLE_SCHEMA)
+        if args.ai:
+            scaffold = {**scaffold, "x-ai-provider": args.ai}
+        out.write_text(json.dumps(scaffold, indent=2) + "\n")
+        print(f"wrote {out}")
+        return 0
+
+    if args.command == "generate-schema":
+        engine = sa.create_engine(args.url)
+        schema = generate_schema(engine)
+        Path(args.out).write_text(json.dumps(schema, indent=2) + "\n")
+        print(f"wrote {args.out} ({len(schema['models'])} models)")
+        return 0
+
+    if args.command == "sync":
+        engine = sa.create_engine(args.url)
+        sync_database(engine, Schema.load(args.schema))
+        print("database synced (dev tool — use migrations in production)")
+        return 0
+
+    if args.command == "diff":
+        engine = sa.create_engine(args.url)
+        lines = schema_diff(engine, Schema.load(args.schema))
+        if not lines:
+            print("-- no differences")
+        for line in lines:
+            print(line)
+        return 0
+
+    if args.command == "serve-mcp":
+        from ..facade import initialize_korm
+        from ..mcp import serve_mcp
+        korm = initialize_korm(url=args.url, schema=args.schema)
+        serve_mcp(korm)
+        return 0
+
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

korm/cli/__main__.py

@@ -0,0 +1,3 @@
+from . import main
+
+raise SystemExit(main())

korm/compat/__init__.py

@@ -0,0 +1,13 @@
+"""v1 compatibility layer (spec §12) — pure adapter over the v2 surface."""
+from .v1 import (
+    convert_v1_join_on,
+    convert_v1_request,
+    convert_v1_value,
+    convert_v1_where,
+    downconvert_response,
+    parse_formula,
+    resolve_refs,
+)
+
+__all__ = ["convert_v1_request", "convert_v1_value", "convert_v1_where",
+           "convert_v1_join_on", "downconvert_response", "parse_formula", "resolve_refs"]

korm/compat/v1.py

@@ -0,0 +1,249 @@
+"""v1 → v2 compatibility converter (spec §12) and batch $ref resolution (§8).
+
+The converter is pure and deterministic: any valid v1 request maps to one v2
+request. Responses to v1-marked requests are down-converted (bare count number,
+bare object for show) so existing clients keep working.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from ..protocol.errors import field_error, validation_failed
+
+_V1_ACTION_ALIASES = {"count", "sum"}
+
+
+# ---------------------------------------------------------------- values
+def _parse_scalar(s: str) -> Any:
+    try:
+        return int(s)
+    except ValueError:
+        try:
+            return float(s)
+        except ValueError:
+            return s.strip()
+
+
+def convert_v1_value(value: Any) -> Any:
+    """Convert one v1 stringly-typed operator value to a v2 operator object."""
+    if not isinstance(value, str):
+        return value
+    if value.startswith(">="):
+        return {"gte": _parse_scalar(value[2:])}
+    if value.startswith("<="):
+        return {"lte": _parse_scalar(value[2:])}
+    if value.startswith("><"):
+        parts = value[2:].split(",")
+        if len(parts) != 2:
+            raise validation_failed([field_error("where", "INVALID_VALUE", f"malformed v1 between {value!r}")])
+        return {"between": [_parse_scalar(parts[0]), _parse_scalar(parts[1])]}
+    if value.startswith(">"):
+        return {"gt": _parse_scalar(value[1:])}
+    if value.startswith("<"):
+        return {"lt": _parse_scalar(value[1:])}
+    if value.startswith("[]"):
+        return {"in": [_parse_scalar(p) for p in value[2:].split(",")]}
+    if value.startswith("!"):
+        return {"ne": _parse_scalar(value[1:])}
+    if "%" in value:
+        return {"like": value}
+    return value
+
+
+def convert_v1_where(where: Any) -> Any:
+    """Convert a v1 where object, honoring "Or:col" keys (left-to-right OR grouping)."""
+    if not isinstance(where, dict):
+        return where
+    and_part: dict[str, Any] = {}
+    or_parts: list[dict[str, Any]] = []
+    for key, value in where.items():
+        if key.startswith("Or:") or key.startswith("or:"):
+            col = key.split(":", 1)[1]
+            if isinstance(value, list):
+                or_parts.extend({col: convert_v1_value(v)} for v in value)
+            else:
+                or_parts.append({col: convert_v1_value(value)})
+        else:
+            and_part[key] = convert_v1_value(value)
+    if not or_parts:
+        return and_part
+    groups: list[dict[str, Any]] = []
+    if and_part:
+        groups.append(and_part)
+    groups.extend(or_parts)
+    return {"or": groups}
+
+
+# ---------------------------------------------------------------- sumFormula
+_TOKEN_RE = re.compile(r"\s*(?:(\d+\.\d+|\d+)|([A-Za-z_][A-Za-z0-9_]*)|([+\-*/()]))")
+
+
+def parse_formula(formula: str) -> Any:
+    """Parse a v1 sumFormula string ("salary + bonus * 2") into a v2 expression tree."""
+    tokens: list[Any] = []
+    pos = 0
+    while pos < len(formula):
+        m = _TOKEN_RE.match(formula, pos)
+        if not m or m.end() == pos:
+            if formula[pos:].strip():
+                raise validation_failed([
+                    field_error("sumFormula", "INVALID_VALUE", f"cannot parse formula at {formula[pos:]!r}"),
+                ])
+            break
+        num, ident, op = m.groups()
+        if num is not None:
+            tokens.append(float(num) if "." in num else int(num))
+        elif ident is not None:
+            tokens.append(ident)
+        else:
+            tokens.append(op)
+        pos = m.end()
+
+    idx = 0
+
+    def peek():
+        return tokens[idx] if idx < len(tokens) else None
+
+    def parse_expr():
+        nonlocal idx
+        node = parse_term()
+        while peek() in ("+", "-"):
+            op = tokens[idx]; idx += 1
+            rhs = parse_term()
+            node = {"add" if op == "+" else "sub": [node, rhs]}
+        return node
+
+    def parse_term():
+        nonlocal idx
+        node = parse_atom()
+        while peek() in ("*", "/"):
+            op = tokens[idx]; idx += 1
+            rhs = parse_atom()
+            node = {"mul" if op == "*" else "div": [node, rhs]}
+        return node
+
+    def parse_atom():
+        nonlocal idx
+        tok = peek()
+        if tok == "(":
+            idx += 1
+            node = parse_expr()
+            if peek() != ")":
+                raise validation_failed([field_error("sumFormula", "INVALID_VALUE", "unbalanced parentheses")])
+            idx += 1
+            return node
+        if isinstance(tok, (int, float, str)) and tok not in ("+", "-", "*", "/", ")", None):
+            idx += 1
+            return tok
+        raise validation_failed([field_error("sumFormula", "INVALID_VALUE", "unexpected token in formula")])
+
+    if not tokens:
+        raise validation_failed([field_error("sumFormula", "INVALID_VALUE", "empty formula")])
+    tree = parse_expr()
+    if idx != len(tokens):
+        raise validation_failed([field_error("sumFormula", "INVALID_VALUE", "trailing tokens in formula")])
+    return tree
+
+
+# ---------------------------------------------------------------- joins
+_JOIN_ON_RE = re.compile(
+    r"^\s*([A-Za-z_][\w]*)\.([A-Za-z_][\w]*)\s*=\s*([A-Za-z_][\w]*)\.([A-Za-z_][\w]*)\s*$"
+)
+
+
+def convert_v1_join_on(on: str) -> dict[str, str]:
+    """Parse a v1 string join condition into structured on; failure -> VALIDATION_FAILED (§12)."""
+    m = _JOIN_ON_RE.match(on)
+    if not m:
+        raise validation_failed([
+            field_error("join.on", "INVALID_VALUE", "v1 string join conditions must be \"a.col = b.col\""),
+        ])
+    lt, lc, rt, rc = m.groups()
+    return {"left": f"{lt}.{lc}", "right": f"{rt}.{rc}", "op": "eq"}
+
+
+# ---------------------------------------------------------------- requests
+def convert_v1_request(request: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any] | None]:
+    """Up-convert a request lacking the "korm": 2 marker. Returns (v2_request, downconvert_info)."""
+    req = dict(request)
+    downconvert: dict[str, Any] | None = None
+    action = req.get("action")
+
+    if req.get("where") is not None:
+        req["where"] = convert_v1_where(req["where"])
+
+    if action == "count":
+        req["action"] = "aggregate"
+        req["aggregates"] = [{"fn": "count", "as": "count"}]
+        downconvert = {"bare_number": "count"}
+    elif action == "sum":
+        formula = req.pop("sumFormula", None) or req.pop("column", None)
+        if formula is None:
+            raise validation_failed([field_error("sumFormula", "REQUIRED", "v1 sum requires sumFormula")])
+        req["action"] = "aggregate"
+        req["aggregates"] = [{"fn": "sum", "expr": parse_formula(str(formula)), "as": "sum"}]
+        downconvert = {"bare_number": "sum"}
+    elif action == "show":
+        downconvert = {"bare_object": True}
+
+    joins = req.get("join")
+    if isinstance(joins, list):
+        req["join"] = [
+            {**j, "on": convert_v1_join_on(j["on"])} if isinstance(j.get("on"), str) else j
+            for j in joins if isinstance(j, dict)
+        ]
+
+    req["korm"] = 2
+    return req, downconvert
+
+
+def downconvert_response(response: dict[str, Any], info: dict[str, Any]) -> dict[str, Any]:
+    """Down-convert a v2 response for a v1-marked request (§12, §14)."""
+    if not response.get("ok"):
+        return response
+    data = response.get("data")
+    if info.get("bare_number") and isinstance(data, list):
+        alias = info["bare_number"]
+        response = dict(response)
+        response["data"] = data[0].get(alias, 0) if data else 0
+    elif info.get("bare_object") and isinstance(data, list):
+        response = dict(response)
+        response["data"] = data[0] if data else None
+    return response
+
+
+# ---------------------------------------------------------------- batch $ref (§8)
+def resolve_refs(node: Any, by_id: dict[str, dict[str, Any]], path: str) -> Any:
+    """Replace {"$ref": "subId.json.path"} pointers with values from earlier sub-responses."""
+    if isinstance(node, dict):
+        if set(node) == {"$ref"} and isinstance(node["$ref"], str):
+            return _lookup_ref(node["$ref"], by_id, path)
+        return {k: resolve_refs(v, by_id, f"{path}.{k}") for k, v in node.items()}
+    if isinstance(node, list):
+        return [resolve_refs(v, by_id, f"{path}[{i}]") for i, v in enumerate(node)]
+    return node
+
+
+def _lookup_ref(ref: str, by_id: dict[str, dict[str, Any]], path: str) -> Any:
+    parts = ref.split(".")
+    sub_id = parts[0]
+    if sub_id not in by_id:
+        raise validation_failed([
+            field_error(path, "UNRESOLVED_REF", f"$ref {ref!r}: no earlier sub-request with id {sub_id!r}"),
+        ])
+    value: Any = by_id[sub_id]
+    for part in parts[1:]:
+        if isinstance(value, list):
+            try:
+                value = value[int(part)]
+                continue
+            except (ValueError, IndexError):
+                raise validation_failed([field_error(path, "UNRESOLVED_REF", f"$ref {ref!r}: bad index {part!r}")])
+        if isinstance(value, dict) and part in value:
+            value = value[part]
+        else:
+            raise validation_failed([
+                field_error(path, "UNRESOLVED_REF", f"$ref {ref!r}: path segment {part!r} not found"),
+            ])
+    return value

korm/exec/__init__.py

@@ -0,0 +1,4 @@
+"""Execution layer: cursor codec (and per-engine strategies as they grow)."""
+from .cursor import decode_cursor, encode_cursor
+
+__all__ = ["encode_cursor", "decode_cursor"]

korm/exec/cursor.py

@@ -0,0 +1,64 @@
+"""Opaque cursor tokens for keyset pagination (spec §5.3, §14).
+
+Cursors are base64url(JSON) with strict validation on decode: unknown keys,
+type mismatches, or columns not present in the request's orderBy return
+VALIDATION_FAILED — never a 500. Optional HMAC-SHA256 signing via cursor_secret.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+from typing import Any
+
+from ..protocol.errors import field_error, validation_failed
+
+_SCALARS = (str, int, float, bool, type(None))
+
+
+def _b64encode(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).decode().rstrip("=")
+
+
+def _b64decode(token: str) -> bytes:
+    pad = "=" * (-len(token) % 4)
+    return base64.urlsafe_b64decode(token + pad)
+
+
+def _sign(payload: str, secret: str) -> str:
+    return _b64encode(hmac.new(secret.encode(), payload.encode(), hashlib.sha256).digest())[:32]
+
+
+def encode_cursor(keys: dict[str, Any], secret: str | None = None) -> str:
+    payload = json.dumps({"k": keys}, separators=(",", ":"), default=str)
+    token = _b64encode(payload.encode())
+    if secret:
+        token = f"{token}.{_sign(payload, secret)}"
+    return token
+
+
+def decode_cursor(token: str, order_columns: list[str], secret: str | None = None) -> dict[str, Any]:
+    """Decode and strictly validate a cursor against the request's orderBy columns."""
+    err = lambda msg: validation_failed([field_error("cursor", "INVALID_CURSOR", msg)])  # noqa: E731
+    body, sig = (token.split(".", 1) + [None])[:2] if "." in token else (token, None)
+    try:
+        payload = _b64decode(body).decode()
+    except Exception:
+        raise err("cursor is not valid base64")
+    if secret:
+        if sig is None or not hmac.compare_digest(sig, _sign(payload, secret)):
+            raise err("cursor signature mismatch")
+    try:
+        obj = json.loads(payload)
+    except ValueError:
+        raise err("cursor payload is not valid JSON")
+    if not isinstance(obj, dict) or set(obj) != {"k"} or not isinstance(obj["k"], dict):
+        raise err("cursor payload has unexpected structure")
+    keys = obj["k"]
+    if set(keys) != set(order_columns):
+        raise err("cursor keys do not match the request's orderBy columns")
+    for k, v in keys.items():
+        if not isinstance(v, _SCALARS):
+            raise err(f"cursor value for {k!r} has unsupported type")
+    return keys