kuzu-grid-schema 0.1.0__tar.gz

kuzu_grid_schema-0.1.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: kuzu-grid-schema
+Version: 0.1.0
+Summary: Shared Kuzu grid tier schemas, composed DDL, and per-tier Cypher CRUD
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: kuzu>=0.7.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# kuzu-grid-schema
+
+Pip-installable library that **owns** the Kuzu grid working-graph schema:
+
+- Tier 0–3 JSON contracts
+- One composed DDL for a **single** shared database
+- Per-tier Cypher CRUD (write statements never cross tier ownership)
+- `effective_*` refresh (`base → latest_actual → scenario → effective`)
+
+```bash
+pip install -e .
+```
+
+```python
+from kuzu_grid_schema import apply_schema, open_database, refresh_effective
+from kuzu_grid_schema.cypher import tier0, tier1, tier2, tier3
+
+db, conn = open_database(":memory:")
+apply_schema(conn)
+```
+
+Other packages (including `kuzu-mcp`) should depend on this library via pip — do not copy DDL.

kuzu_grid_schema-0.1.0/README.md

@@ -0,0 +1,22 @@
+# kuzu-grid-schema
+
+Pip-installable library that **owns** the Kuzu grid working-graph schema:
+
+- Tier 0–3 JSON contracts
+- One composed DDL for a **single** shared database
+- Per-tier Cypher CRUD (write statements never cross tier ownership)
+- `effective_*` refresh (`base → latest_actual → scenario → effective`)
+
+```bash
+pip install -e .
+```
+
+```python
+from kuzu_grid_schema import apply_schema, open_database, refresh_effective
+from kuzu_grid_schema.cypher import tier0, tier1, tier2, tier3
+
+db, conn = open_database(":memory:")
+apply_schema(conn)
+```
+
+Other packages (including `kuzu-mcp`) should depend on this library via pip — do not copy DDL.

kuzu_grid_schema-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kuzu-grid-schema"
+version = "0.1.0"
+description = "Shared Kuzu grid tier schemas, composed DDL, and per-tier Cypher CRUD"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "kuzu>=0.7.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["kuzu_grid_schema*"]
+
+[tool.setuptools.package-data]
+kuzu_grid_schema = ["schema/**/*.json", "schema/**/*.cypher"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

kuzu_grid_schema-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kuzu_grid_schema-0.1.0/src/kuzu_grid_schema/__init__.py

@@ -0,0 +1,17 @@
+"""Shared Kuzu grid schema: contracts, DDL, per-tier Cypher, effective refresh."""
+
+from kuzu_grid_schema.apply import apply_schema, open_database, query_rows
+from kuzu_grid_schema.effective_refresh import refresh_effective
+from kuzu_grid_schema.resources import load_composed_ddl, load_schema_contract, load_tier_schema
+
+__all__ = [
+    "apply_schema",
+    "open_database",
+    "query_rows",
+    "refresh_effective",
+    "load_composed_ddl",
+    "load_schema_contract",
+    "load_tier_schema",
+]
+
+__version__ = "0.1.0"

kuzu_grid_schema-0.1.0/src/kuzu_grid_schema/apply.py

@@ -0,0 +1,56 @@
+"""Apply composed DDL and open a single shared Kuzu database."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import kuzu
+
+from kuzu_grid_schema.resources import load_composed_ddl
+
+
+def open_database(path: str | Path = ":memory:") -> tuple[kuzu.Database, kuzu.Connection]:
+    """Open one Kuzu DB used by all tiers together."""
+    db = kuzu.Database(str(path))
+    conn = kuzu.Connection(db)
+    return db, conn
+
+
+def apply_schema(conn: kuzu.Connection, ddl: str | None = None) -> None:
+    """Apply the composed DDL (tiers 0–3) to a single connection."""
+    text = ddl if ddl is not None else load_composed_ddl()
+    for statement in _split_cypher(text):
+        if statement.strip():
+            conn.execute(statement)
+
+
+def query_rows(conn: kuzu.Connection, cypher: str, params: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+    """Return rows as dicts without requiring pandas/numpy."""
+    result = conn.execute(cypher, params or {})
+    columns = list(result.get_column_names())
+    rows: list[dict[str, Any]] = []
+    while result.has_next():
+        values = result.get_next()
+        rows.append(dict(zip(columns, values, strict=True)))
+    return rows
+
+
+def execute(conn: kuzu.Connection, cypher: str, params: dict[str, Any] | None = None) -> None:
+    conn.execute(cypher, params or {})
+
+
+def _split_cypher(text: str) -> list[str]:
+    statements: list[str] = []
+    current: list[str] = []
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("//"):
+            continue
+        current.append(line)
+        if stripped.endswith(";"):
+            statements.append("\n".join(current))
+            current = []
+    if current:
+        statements.append("\n".join(current))
+    return statements

kuzu_grid_schema-0.1.0/src/kuzu_grid_schema/cypher/__init__.py

@@ -0,0 +1,5 @@
+"""Per-tier Cypher CRUD modules (distinct write statements; no cross-tier SET)."""
+
+from kuzu_grid_schema.cypher import tier0, tier1, tier2, tier3
+
+__all__ = ["tier0", "tier1", "tier2", "tier3"]

kuzu_grid_schema-0.1.0/src/kuzu_grid_schema/cypher/tier0.py

@@ -0,0 +1,413 @@
+"""Tier 0 Cypher CRUD: topology + base_* only (never latest_actual_/scenario_/effective_)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kuzu_grid_schema.apply import execute, query_rows
+
+# Forbidden prefixes in this module's write statements (enforced by tests).
+FORBIDDEN_WRITE_PREFIXES = ("latest_actual_", "scenario_", "effective_", "dc_")
+
+CREATE_BUS = """
+CREATE (b:Bus {
+    bus_id: $bus_id,
+    name: $name,
+    base_kv: $base_kv,
+    bus_type: $bus_type,
+    zone: $zone,
+    in_service: $in_service,
+    is_slack: $is_slack,
+    base_in_service: $base_in_service,
+    geom: $geom
+})
+"""
+
+GET_BUS = """
+MATCH (b:Bus {bus_id: $bus_id})
+RETURN b.bus_id AS bus_id, b.name AS name, b.base_kv AS base_kv, b.bus_type AS bus_type,
+       b.zone AS zone, b.in_service AS in_service, b.is_slack AS is_slack,
+       b.base_in_service AS base_in_service, b.geom AS geom
+"""
+
+LIST_BUS = """
+MATCH (b:Bus)
+RETURN b.bus_id AS bus_id, b.name AS name, b.base_kv AS base_kv, b.bus_type AS bus_type,
+       b.zone AS zone, b.in_service AS in_service, b.is_slack AS is_slack,
+       b.base_in_service AS base_in_service, b.geom AS geom
+ORDER BY b.bus_id
+"""
+
+UPDATE_BUS = """
+MATCH (b:Bus {bus_id: $bus_id})
+SET b.name = coalesce($name, b.name),
+    b.base_kv = coalesce($base_kv, b.base_kv),
+    b.bus_type = coalesce($bus_type, b.bus_type),
+    b.zone = coalesce($zone, b.zone),
+    b.in_service = coalesce($in_service, b.in_service),
+    b.is_slack = coalesce($is_slack, b.is_slack),
+    b.base_in_service = coalesce($base_in_service, b.base_in_service),
+    b.geom = coalesce($geom, b.geom)
+"""
+
+DELETE_BUS = "MATCH (b:Bus {bus_id: $bus_id}) DETACH DELETE b"
+
+CREATE_GENERATOR = """
+CREATE (g:Generator {
+    gen_id: $gen_id,
+    fuel_type: $fuel_type,
+    control_mode: $control_mode,
+    pmax_mw: $pmax_mw,
+    pmin_mw: $pmin_mw,
+    base_p_mw: $base_p_mw,
+    q_mvar: $q_mvar,
+    vm_pu: $vm_pu,
+    base_in_service: $base_in_service
+})
+WITH g
+MATCH (b:Bus {bus_id: $bus_id})
+CREATE (g)-[:GENERATOR_AT_BUS]->(b)
+"""
+
+GET_GENERATOR = """
+MATCH (g:Generator {gen_id: $gen_id})
+OPTIONAL MATCH (g)-[:GENERATOR_AT_BUS]->(b:Bus)
+RETURN g.gen_id AS gen_id, b.bus_id AS bus_id, g.fuel_type AS fuel_type,
+       g.control_mode AS control_mode, g.pmax_mw AS pmax_mw, g.pmin_mw AS pmin_mw,
+       g.base_p_mw AS base_p_mw, g.q_mvar AS q_mvar, g.vm_pu AS vm_pu,
+       g.base_in_service AS base_in_service
+"""
+
+LIST_GENERATOR = """
+MATCH (g:Generator)
+OPTIONAL MATCH (g)-[:GENERATOR_AT_BUS]->(b:Bus)
+RETURN g.gen_id AS gen_id, b.bus_id AS bus_id, g.fuel_type AS fuel_type,
+       g.control_mode AS control_mode, g.pmax_mw AS pmax_mw, g.pmin_mw AS pmin_mw,
+       g.base_p_mw AS base_p_mw, g.q_mvar AS q_mvar, g.vm_pu AS vm_pu,
+       g.base_in_service AS base_in_service
+ORDER BY g.gen_id
+"""
+
+UPDATE_GENERATOR = """
+MATCH (g:Generator {gen_id: $gen_id})
+SET g.fuel_type = coalesce($fuel_type, g.fuel_type),
+    g.control_mode = coalesce($control_mode, g.control_mode),
+    g.pmax_mw = coalesce($pmax_mw, g.pmax_mw),
+    g.pmin_mw = coalesce($pmin_mw, g.pmin_mw),
+    g.base_p_mw = coalesce($base_p_mw, g.base_p_mw),
+    g.q_mvar = coalesce($q_mvar, g.q_mvar),
+    g.vm_pu = coalesce($vm_pu, g.vm_pu),
+    g.base_in_service = coalesce($base_in_service, g.base_in_service)
+"""
+
+DELETE_GENERATOR = "MATCH (g:Generator {gen_id: $gen_id}) DETACH DELETE g"
+
+CREATE_LOAD = """
+CREATE (l:Load {
+    load_id: $load_id,
+    load_zone: $load_zone,
+    base_p_mw: $base_p_mw,
+    base_q_mvar: $base_q_mvar,
+    scaling: $scaling,
+    base_in_service: $base_in_service
+})
+WITH l
+MATCH (b:Bus {bus_id: $bus_id})
+CREATE (l)-[:LOAD_AT_BUS]->(b)
+"""
+
+GET_LOAD = """
+MATCH (l:Load {load_id: $load_id})
+OPTIONAL MATCH (l)-[:LOAD_AT_BUS]->(b:Bus)
+RETURN l.load_id AS load_id, b.bus_id AS bus_id, l.load_zone AS load_zone,
+       l.base_p_mw AS base_p_mw, l.base_q_mvar AS base_q_mvar, l.scaling AS scaling,
+       l.base_in_service AS base_in_service
+"""
+
+LIST_LOAD = """
+MATCH (l:Load)
+OPTIONAL MATCH (l)-[:LOAD_AT_BUS]->(b:Bus)
+RETURN l.load_id AS load_id, b.bus_id AS bus_id, l.load_zone AS load_zone,
+       l.base_p_mw AS base_p_mw, l.base_q_mvar AS base_q_mvar, l.scaling AS scaling,
+       l.base_in_service AS base_in_service
+ORDER BY l.load_id
+"""
+
+UPDATE_LOAD = """
+MATCH (l:Load {load_id: $load_id})
+SET l.load_zone = coalesce($load_zone, l.load_zone),
+    l.base_p_mw = coalesce($base_p_mw, l.base_p_mw),
+    l.base_q_mvar = coalesce($base_q_mvar, l.base_q_mvar),
+    l.scaling = coalesce($scaling, l.scaling),
+    l.base_in_service = coalesce($base_in_service, l.base_in_service)
+"""
+
+DELETE_LOAD = "MATCH (l:Load {load_id: $load_id}) DETACH DELETE l"
+
+CREATE_BRANCH = """
+MATCH (a:Bus {bus_id: $from_bus_id}), (b:Bus {bus_id: $to_bus_id})
+CREATE (a)-[e:CONNECTED_TO {
+    branch_id: $branch_id,
+    element_kind: $element_kind,
+    r_pu: $r_pu,
+    x_pu: $x_pu,
+    b_pu: $b_pu,
+    c_nf_per_km: $c_nf_per_km,
+    g_us_per_km: $g_us_per_km,
+    rate_a_mva: $rate_a_mva,
+    base_rate_a_mva: $base_rate_a_mva,
+    length_km: $length_km,
+    tap_ratio: $tap_ratio,
+    phase_shift_deg: $phase_shift_deg,
+    pfe_kw: $pfe_kw,
+    i0_percent: $i0_percent,
+    status: $status,
+    base_in_service: $base_in_service,
+    parallel: $parallel
+}]->(b)
+"""
+
+GET_BRANCH = """
+MATCH (a:Bus)-[e:CONNECTED_TO {branch_id: $branch_id}]->(b:Bus)
+RETURN e.branch_id AS branch_id, a.bus_id AS from_bus_id, b.bus_id AS to_bus_id,
+       e.element_kind AS element_kind, e.r_pu AS r_pu, e.x_pu AS x_pu, e.b_pu AS b_pu,
+       e.rate_a_mva AS rate_a_mva, e.base_rate_a_mva AS base_rate_a_mva,
+       e.length_km AS length_km, e.status AS status, e.base_in_service AS base_in_service,
+       e.parallel AS parallel
+"""
+
+LIST_BRANCH = """
+MATCH (a:Bus)-[e:CONNECTED_TO]->(b:Bus)
+RETURN e.branch_id AS branch_id, a.bus_id AS from_bus_id, b.bus_id AS to_bus_id,
+       e.element_kind AS element_kind, e.r_pu AS r_pu, e.x_pu AS x_pu, e.b_pu AS b_pu,
+       e.rate_a_mva AS rate_a_mva, e.base_rate_a_mva AS base_rate_a_mva,
+       e.length_km AS length_km, e.status AS status, e.base_in_service AS base_in_service,
+       e.parallel AS parallel
+ORDER BY e.branch_id
+"""
+
+UPDATE_BRANCH = """
+MATCH ()-[e:CONNECTED_TO {branch_id: $branch_id}]->()
+SET e.element_kind = coalesce($element_kind, e.element_kind),
+    e.r_pu = coalesce($r_pu, e.r_pu),
+    e.x_pu = coalesce($x_pu, e.x_pu),
+    e.b_pu = coalesce($b_pu, e.b_pu),
+    e.rate_a_mva = coalesce($rate_a_mva, e.rate_a_mva),
+    e.base_rate_a_mva = coalesce($base_rate_a_mva, e.base_rate_a_mva),
+    e.length_km = coalesce($length_km, e.length_km),
+    e.status = coalesce($status, e.status),
+    e.base_in_service = coalesce($base_in_service, e.base_in_service),
+    e.parallel = coalesce($parallel, e.parallel)
+"""
+
+DELETE_BRANCH = "MATCH ()-[e:CONNECTED_TO {branch_id: $branch_id}]->() DELETE e"
+
+CREATE_BOUNDARY = """
+CREATE (bi:BoundaryInjection {
+    boundary_id: $boundary_id,
+    p_mw: $p_mw,
+    q_mvar: $q_mvar,
+    source: $source
+})
+WITH bi
+MATCH (b:Bus {bus_id: $bus_id})
+CREATE (bi)-[:BOUNDARY_AT_BUS]->(b)
+"""
+
+GET_BOUNDARY = """
+MATCH (bi:BoundaryInjection {boundary_id: $boundary_id})
+OPTIONAL MATCH (bi)-[:BOUNDARY_AT_BUS]->(b:Bus)
+RETURN bi.boundary_id AS boundary_id, b.bus_id AS bus_id, bi.p_mw AS p_mw,
+       bi.q_mvar AS q_mvar, bi.source AS source
+"""
+
+LIST_BOUNDARY = """
+MATCH (bi:BoundaryInjection)
+OPTIONAL MATCH (bi)-[:BOUNDARY_AT_BUS]->(b:Bus)
+RETURN bi.boundary_id AS boundary_id, b.bus_id AS bus_id, bi.p_mw AS p_mw,
+       bi.q_mvar AS q_mvar, bi.source AS source
+ORDER BY bi.boundary_id
+"""
+
+UPDATE_BOUNDARY = """
+MATCH (bi:BoundaryInjection {boundary_id: $boundary_id})
+SET bi.p_mw = coalesce($p_mw, bi.p_mw),
+    bi.q_mvar = coalesce($q_mvar, bi.q_mvar),
+    bi.source = coalesce($source, bi.source)
+"""
+
+DELETE_BOUNDARY = "MATCH (bi:BoundaryInjection {boundary_id: $boundary_id}) DETACH DELETE bi"
+
+
+def create_bus(conn, **params: Any) -> None:
+    defaults = {
+        "name": params.get("bus_id"),
+        "bus_type": "b",
+        "zone": "",
+        "in_service": True,
+        "is_slack": False,
+        "base_in_service": True,
+        "geom": None,
+        "base_kv": 0.0,
+    }
+    defaults.update({k: v for k, v in params.items() if v is not None})
+    execute(conn, CREATE_BUS, defaults)
+
+
+def get_bus(conn, bus_id: str) -> dict[str, Any] | None:
+    rows = query_rows(conn, GET_BUS, {"bus_id": bus_id})
+    return rows[0] if rows else None
+
+
+def list_buses(conn) -> list[dict[str, Any]]:
+    return query_rows(conn, LIST_BUS)
+
+
+def update_bus(conn, bus_id: str, **params: Any) -> None:
+    payload = {"bus_id": bus_id, "name": None, "base_kv": None, "bus_type": None, "zone": None,
+               "in_service": None, "is_slack": None, "base_in_service": None, "geom": None}
+    payload.update(params)
+    execute(conn, UPDATE_BUS, payload)
+
+
+def delete_bus(conn, bus_id: str) -> None:
+    execute(conn, DELETE_BUS, {"bus_id": bus_id})
+
+
+def create_generator(conn, **params: Any) -> None:
+    defaults = {
+        "fuel_type": "",
+        "control_mode": "PV",
+        "pmax_mw": 0.0,
+        "pmin_mw": 0.0,
+        "base_p_mw": 0.0,
+        "q_mvar": 0.0,
+        "vm_pu": 1.0,
+        "base_in_service": True,
+    }
+    defaults.update({k: v for k, v in params.items() if v is not None})
+    execute(conn, CREATE_GENERATOR, defaults)
+
+
+def get_generator(conn, gen_id: str) -> dict[str, Any] | None:
+    rows = query_rows(conn, GET_GENERATOR, {"gen_id": gen_id})
+    return rows[0] if rows else None
+
+
+def list_generators(conn) -> list[dict[str, Any]]:
+    return query_rows(conn, LIST_GENERATOR)
+
+
+def update_generator(conn, gen_id: str, **params: Any) -> None:
+    payload = {"gen_id": gen_id, "fuel_type": None, "control_mode": None, "pmax_mw": None,
+               "pmin_mw": None, "base_p_mw": None, "q_mvar": None, "vm_pu": None,
+               "base_in_service": None}
+    payload.update(params)
+    execute(conn, UPDATE_GENERATOR, payload)
+
+
+def delete_generator(conn, gen_id: str) -> None:
+    execute(conn, DELETE_GENERATOR, {"gen_id": gen_id})
+
+
+def create_load(conn, **params: Any) -> None:
+    defaults = {
+        "load_zone": "",
+        "base_p_mw": 0.0,
+        "base_q_mvar": 0.0,
+        "scaling": 1.0,
+        "base_in_service": True,
+    }
+    defaults.update({k: v for k, v in params.items() if v is not None})
+    execute(conn, CREATE_LOAD, defaults)
+
+
+def get_load(conn, load_id: str) -> dict[str, Any] | None:
+    rows = query_rows(conn, GET_LOAD, {"load_id": load_id})
+    return rows[0] if rows else None
+
+
+def list_loads(conn) -> list[dict[str, Any]]:
+    return query_rows(conn, LIST_LOAD)
+
+
+def update_load(conn, load_id: str, **params: Any) -> None:
+    payload = {"load_id": load_id, "load_zone": None, "base_p_mw": None, "base_q_mvar": None,
+               "scaling": None, "base_in_service": None}
+    payload.update(params)
+    execute(conn, UPDATE_LOAD, payload)
+
+
+def delete_load(conn, load_id: str) -> None:
+    execute(conn, DELETE_LOAD, {"load_id": load_id})
+
+
+def create_branch(conn, **params: Any) -> None:
+    defaults = {
+        "element_kind": "line",
+        "r_pu": 0.0,
+        "x_pu": 0.01,
+        "b_pu": 0.0,
+        "c_nf_per_km": 0.0,
+        "g_us_per_km": 0.0,
+        "rate_a_mva": None,
+        "base_rate_a_mva": None,
+        "length_km": 1.0,
+        "tap_ratio": 1.0,
+        "phase_shift_deg": 0.0,
+        "pfe_kw": 0.0,
+        "i0_percent": 0.0,
+        "status": True,
+        "base_in_service": True,
+        "parallel": 1,
+    }
+    defaults.update({k: v for k, v in params.items() if v is not None})
+    execute(conn, CREATE_BRANCH, defaults)
+
+
+def get_branch(conn, branch_id: str) -> dict[str, Any] | None:
+    rows = query_rows(conn, GET_BRANCH, {"branch_id": branch_id})
+    return rows[0] if rows else None
+
+
+def list_branches(conn) -> list[dict[str, Any]]:
+    return query_rows(conn, LIST_BRANCH)
+
+
+def update_branch(conn, branch_id: str, **params: Any) -> None:
+    payload = {
+        "branch_id": branch_id, "element_kind": None, "r_pu": None, "x_pu": None, "b_pu": None,
+        "rate_a_mva": None, "base_rate_a_mva": None, "length_km": None, "status": None,
+        "base_in_service": None, "parallel": None,
+    }
+    payload.update(params)
+    execute(conn, UPDATE_BRANCH, payload)
+
+
+def delete_branch(conn, branch_id: str) -> None:
+    execute(conn, DELETE_BRANCH, {"branch_id": branch_id})
+
+
+def create_boundary(conn, **params: Any) -> None:
+    defaults = {"p_mw": 0.0, "q_mvar": 0.0, "source": "equivalent"}
+    defaults.update({k: v for k, v in params.items() if v is not None})
+    execute(conn, CREATE_BOUNDARY, defaults)
+
+
+def get_boundary(conn, boundary_id: str) -> dict[str, Any] | None:
+    rows = query_rows(conn, GET_BOUNDARY, {"boundary_id": boundary_id})
+    return rows[0] if rows else None
+
+
+def list_boundaries(conn) -> list[dict[str, Any]]:
+    return query_rows(conn, LIST_BOUNDARY)
+
+
+def update_boundary(conn, boundary_id: str, **params: Any) -> None:
+    payload = {"boundary_id": boundary_id, "p_mw": None, "q_mvar": None, "source": None}
+    payload.update(params)
+    execute(conn, UPDATE_BOUNDARY, payload)
+
+
+def delete_boundary(conn, boundary_id: str) -> None:
+    execute(conn, DELETE_BOUNDARY, {"boundary_id": boundary_id})