sonnet-graph 0.3.2__tar.gz → 0.4.0__tar.gz

{sonnet_graph-0.3.2 → sonnet_graph-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sonnet-graph
-Version: 0.3.2
+Version: 0.4.0
 Summary: Graph database integration (cypher-graphdb) for sonnet-server applications
 Author-email: Wolfgang Miller <wolfgang.miller@petrarca-labs.com>
 License-Expression: Apache-2.0
@@ -12,7 +12,7 @@ Requires-Python: <4.0,>=3.14
 Description-Content-Type: text/markdown
 Requires-Dist: sonnet-core>=0.1.0
 Requires-Dist: sonnet-server>=0.4.0
-Requires-Dist: cypher-graphdb>=0.5.0
+Requires-Dist: cypher-graphdb>=0.7.1
 Requires-Dist: loguru>=0.7.3
 Requires-Dist: jinja2>=3.1.6
 Provides-Extra: dev

{sonnet_graph-0.3.2 → sonnet_graph-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sonnet-graph"
-version = "0.3.2"
+version = "0.4.0"
 authors = [
     { name = "Wolfgang Miller", email = "wolfgang.miller@petrarca-labs.com" },
 ]
@@ -21,7 +21,7 @@ classifiers = [
 dependencies = [
     "sonnet-core>=0.1.0",
     "sonnet-server>=0.4.0",
-    "cypher-graphdb>=0.5.0",
+    "cypher-graphdb>=0.7.1",
     "loguru>=0.7.3",
     "jinja2>=3.1.6",
 ]
@@ -37,6 +37,9 @@ dev = [
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+sonnet_graph = ["py.typed"]
+
 [tool.pytest.ini_options]
 markers = [
     "unit: marks tests as unit tests (default)",

{sonnet_graph-0.3.2 → sonnet_graph-0.4.0}/src/sonnet_graph/__init__.py

@@ -33,11 +33,9 @@ Public API:
 
   Graph metadata:
     GraphModelStore          -- load/save/remove :_GraphModel node (schema + description)
-    GraphQueryStore          -- load/save/remove :_NamedQuery nodes (queries)
     init_graph_metadata      -- initialize model + description (one-time setup)
-    seed_named_queries       -- seed :_NamedQuery nodes from file pairs
     get_graph_info           -- LLM-friendly schema + description in one call
-    resolve_template         -- Jinja2 template resolution for named queries
+    resolve_template         -- stateless Jinja2 template resolution
 
   FastAPI dependencies:
     get_graphdb_session      -- factory for router-level ambient session dependency
@@ -74,11 +72,9 @@ from sonnet_graph.dependencies import get_graphdb, get_graphdb_session
 from sonnet_graph.extension import GraphDBExtension
 from sonnet_graph.metadata import (
     GraphModelStore,
-    GraphQueryStore,
     get_graph_info,
     init_graph_metadata,
     resolve_template,
-    seed_named_queries,
 )
 from sonnet_graph.status import GraphPoolStatus, PoolInfo, snapshot_pools
 
@@ -118,9 +114,7 @@ __all__ = [
     "GraphdbStage",
     # Graph metadata
     "GraphModelStore",
-    "GraphQueryStore",
     "get_graph_info",
     "init_graph_metadata",
     "resolve_template",
-    "seed_named_queries",
 ]

{sonnet_graph-0.3.2 → sonnet_graph-0.4.0}/src/sonnet_graph/context.py

@@ -201,7 +201,13 @@ def register_graph(name: str, *, env_prefix: str | None = None, settings: Cypher
         raise ValueError("register_graph requires one of 'env_prefix' or 'settings' -- neither was given.")
     if env_prefix is not None and settings is not None:
         raise ValueError("register_graph requires exactly one of 'env_prefix' or 'settings' -- both were given.")
-    _graph_specs[name] = settings if settings is not None else env_prefix
+    # Exactly one is non-None here; assign in explicit branches so the narrowed
+    # (non-None) type is what lands in _graph_specs[str, CypherSettings | str].
+    if settings is not None:
+        _graph_specs[name] = settings
+    else:
+        assert env_prefix is not None  # guaranteed by the checks above; narrows for the type checker
+        _graph_specs[name] = env_prefix
     logger.debug("register_graph: '{}' registered ({})", name, "settings" if settings is not None else f"env_prefix={env_prefix}")
 
 

{sonnet_graph-0.3.2 → sonnet_graph-0.4.0}/src/sonnet_graph/metadata/__init__.py

@@ -1,13 +1,12 @@
-"""Graph metadata -- self-describing graph nodes for model, description, and queries.
+"""Graph metadata -- self-describing graph nodes for model and description.
 
-The graph stores its own metadata as dedicated nodes prefixed with
+The graph stores its own metadata as a dedicated node prefixed with
 underscore to indicate internal infrastructure:
 
 - :_GraphModel -- graph schema (node/edge types, properties) and
   human-readable description (markdown)
-- :_NamedQuery -- pre-defined queries with metadata (cypher, jinja2, datalog)
 
-Each metadata type has a facade store and a typed model.
+The metadata type has a facade store and a typed model.
 
 Two paths to seed a graph model:
 
@@ -40,12 +39,11 @@ Graph description (stored on the :_GraphModel node)::
         content, fmt = store.load_description()
         # -> ("# Tech Stack Graph\\n...", "text/markdown")
 
-Named queries::
+Initialize model + description in one call::
 
-    from sonnet_graph import borrow_graphdb, GraphQueryStore, init_graph_metadata, resolve_template
+    from sonnet_graph import borrow_graphdb, init_graph_metadata
 
     with borrow_graphdb("techstack") as cdb:
-        # Initialize model + description
         init_graph_metadata(
             cdb,
             models_path="plugins/tech_stack/graph_models.py",
@@ -53,58 +51,38 @@ Named queries::
         )
         cdb.commit()
 
-        # Or store individual queries
-        store = GraphQueryStore(cdb)
-        store.save(
-            query_key="hub-technologies",
-            title="Hub Technologies",
-            query_content="MATCH (t:Technology)<-[:USES]-(c) RETURN t, count(c) ORDER BY count(c) DESC",
-            language="cypher",
-            tags=["analysis"],
-        )
-        cdb.commit()
-
-        queries = store.list()                    # metadata only
-        query = store.load("hub-technologies")    # full detail
-        cypher = resolve_template(query["query_content"], language=query["language"])
+Named queries are a product-owned feature: their storage and lifecycle belong
+to the consuming application, not to graph metadata. sonnet-graph provides only
+``resolve_template`` (stateless Jinja2 rendering) for callers that resolve
+parameterized query text themselves.
 
 Public API:
 
   Stores:
     GraphModelStore          -- load/save/remove :_GraphModel node (schema + description)
-    GraphQueryStore          -- load/save/remove :_NamedQuery nodes
 
   Initialization:
     init_graph_metadata      -- initialize model + description (lauro graph init)
 
-  Query seeding:
-    seed_named_queries       -- seed :_NamedQuery nodes from file pairs
-
   Helpers:
     get_graph_info           -- LLM-friendly schema + description in one call
-    resolve_template         -- Jinja2 template resolution for named queries
+    resolve_template         -- stateless Jinja2 template resolution
 
   Node models:
     GraphModelNode           -- model for the _GraphModel label
-    NamedQueryNode           -- model for the _NamedQuery label
 """
 
 from sonnet_graph.metadata.graph_info import get_graph_info
 from sonnet_graph.metadata.model_store import GraphModelStore
-from sonnet_graph.metadata.models import GraphModelNode, NamedQueryNode
-from sonnet_graph.metadata.query_store import GraphQueryStore
-from sonnet_graph.metadata.seeding import QuerySeedResult, init_graph_metadata, seed_named_queries
+from sonnet_graph.metadata.models import GraphModelNode
+from sonnet_graph.metadata.seeding import init_graph_metadata
 from sonnet_graph.metadata.template_resolver import TemplateResolutionError, resolve_template
 
 __all__ = [
     "GraphModelNode",
     "GraphModelStore",
-    "GraphQueryStore",
-    "NamedQueryNode",
-    "QuerySeedResult",
     "TemplateResolutionError",
     "get_graph_info",
     "init_graph_metadata",
     "resolve_template",
-    "seed_named_queries",
 ]

{sonnet_graph-0.3.2 → sonnet_graph-0.4.0}/src/sonnet_graph/metadata/model_store.py

@@ -101,6 +101,8 @@ class GraphModelStore:
 
     - ``save_from_provider(provider)`` -- models already registered
       in a ModelProvider (e.g. a graph_models module's ``mp``)
+    - ``sync_from_provider(provider)`` -- the same, written only when the
+      stored schema, name or version differ
     - ``save_from_path(path)`` -- models in a Python file/directory
     - ``save_from_file(path)`` -- pre-generated graph.schema.json
     - ``save(schema_dict)`` -- raw schema dict
@@ -276,6 +278,20 @@ class GraphModelStore:
 
         self._cdb.create_or_merge(node)
 
+    @staticmethod
+    def schema_from_provider(provider: ModelProvider) -> dict[str, Any]:
+        """Generate the combined JSON Schema of a ModelProvider's registered models.
+
+        Raises:
+            ValueError: If the provider has no models with schemas.
+        """
+        from cypher_graphdb.utils.schema_utils import combine_schemas, extract_schemas_from_model_infos
+
+        model_infos = [info for info in provider.values() if info.graph_schema]
+        if not model_infos:
+            raise ValueError("No models with schemas found in the provider")
+        return combine_schemas(extract_schemas_from_model_infos(model_infos))
+
     def save_from_provider(
         self, provider: ModelProvider, *, name: str | None = None, version: str | None = None
     ) -> dict[str, Any]:
@@ -292,17 +308,41 @@ class GraphModelStore:
         Raises:
             ValueError: If the provider has no models with schemas.
         """
-        from cypher_graphdb.utils.schema_utils import combine_schemas, extract_schemas_from_model_infos
-
-        model_infos = [info for info in provider.values() if info.graph_schema]
-        if not model_infos:
-            raise ValueError("No models with schemas found in the provider")
-
-        schemas = extract_schemas_from_model_infos(model_infos)
-        combined = combine_schemas(schemas)
+        combined = self.schema_from_provider(provider)
         self.save(combined, name=name, version=version)
         return combined
 
+    def sync_from_provider(self, provider: ModelProvider, *, name: str | None = None, version: str | None = None) -> bool:
+        """Save the provider's schema unless the stored one is already the same; return whether it was written.
+
+        Compares in the stored form (the schema as JSON), with the name and
+        version ``save`` would write: a changed model, name or version
+        rewrites the node, an unchanged one leaves it -- and its
+        ``updated_at`` -- as it is. Either way the schema's types are
+        registered into the connection's ModelProvider, as after a save.
+
+        Raises:
+            ValueError: If the provider has no models with schemas.
+        """
+        schema = self.schema_from_provider(provider)
+        if self._is_stored(schema, name=name, version=version):
+            self._register_schema(schema)
+            return False
+        self.save(schema, name=name, version=version)
+        return True
+
+    def _is_stored(self, schema: dict[str, Any], *, name: str | None, version: str | None) -> bool:
+        """Whether the stored node holds exactly what ``save(schema, name=, version=)`` would write."""
+        node = self._load_node()
+        if node is None or not node.data:
+            return False
+        try:
+            stored = json.loads(node.data)
+        except json.JSONDecodeError, TypeError:
+            return False
+        as_stored = json.loads(json.dumps(schema, ensure_ascii=False))
+        return stored == as_stored and node.name == (name or schema.get("title", "")) and (node.version or "") == (version or "")
+
     def save_from_path(
         self,
         models_path: str | Path,

{sonnet_graph-0.3.2 → sonnet_graph-0.4.0}/src/sonnet_graph/metadata/models.py

@@ -18,7 +18,7 @@ metadata_provider = ModelProvider()
 
 
 def ensure_metadata_types(provider: ModelProvider | None) -> None:
-    """Seed the metadata node types (_GraphModel, _NamedQuery) into ``provider``.
+    """Seed the metadata node types (_GraphModel) into ``provider``.
 
     Idempotent and non-destructive: a graph that legitimately declares its own
     type under one of these labels keeps it (``overwrite=False``).
@@ -57,27 +57,3 @@ class GraphModelNode(GraphNode):
     description: str | None = None  # human-readable documentation (markdown)
     description_format: str | None = None  # MIME type: text/markdown, text/plain, text/html
     updated_at: str | None = None
-
-
-@metadata_provider.node(label="_NamedQuery", merge_keys=["query_key"])
-class NamedQueryNode(GraphNode):
-    """A pre-defined query with metadata.
-
-    Multiple per graph, keyed by ``query_key`` (``merge_keys=["query_key"]``).
-    The ``query_content`` holds the query text -- plain Cypher, a Jinja2
-    template, or Datalog rules. The ``language`` field discriminates.
-
-    The ``tags`` and ``params_schema`` and ``ui_schema`` fields are
-    JSON-serialized strings for cross-backend compatibility (AGE
-    stores arrays as JSON strings).
-    """
-
-    query_key: str | None = None
-    title: str | None = None
-    description: str | None = None
-    tags: str | None = None  # JSON-serialized list[str]
-    query_content: str | None = None
-    language: str | None = None  # cypher | jinja2 | datalog
-    params_schema: str | None = None  # JSON-serialized JSON Schema
-    ui_schema: str | None = None  # JSON-serialized UI hints
-    updated_at: str | None = None

sonnet_graph-0.4.0/src/sonnet_graph/metadata/seeding.py

@@ -0,0 +1,64 @@
+"""Graph metadata initialization.
+
+``init_graph_metadata(cdb, ...)`` -- initialize model and description
+    on the :_GraphModel node. One-time setup, called by
+    ``lauro graph init``. Raises on failure.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cypher_graphdb import CypherGraphDB
+from loguru import logger
+
+from sonnet_graph.metadata.model_store import GraphModelStore
+
+
+def init_graph_metadata(
+    cdb: CypherGraphDB,
+    *,
+    model: dict | None = None,
+    models_path: str | Path | None = None,
+    model_name: str | None = None,
+    model_version: str | None = None,
+    description: str | None = None,
+) -> None:
+    """Initialize graph metadata -- model schema and description.
+
+    Writes the :_GraphModel node with schema and optional description.
+    Intended for one-time graph initialization (``lauro graph init``).
+    Does NOT call ``commit()`` -- the caller is responsible.
+
+    Args:
+        cdb: Active CypherGraphDB connection.
+        model: JSON Schema dict to write as :_GraphModel node.
+        models_path: Path to a Python file or directory declaring graph
+            models on a ModelProvider. Generates and saves the schema.
+            Mutually exclusive with ``model``.
+        model_name: Graph model name.
+        model_version: Schema version string.
+        description: Markdown string stored on the :_GraphModel node.
+
+    Raises:
+        ValueError: If both ``model`` and ``models_path`` are provided.
+        ValueError: If ``description`` is provided without a model/models_path
+            and no :_GraphModel node already exists in the graph. Use
+            ``GraphModelStore.update_description()`` directly to update
+            an existing node's description independently.
+    """
+    if model is not None and models_path is not None:
+        raise ValueError("Provide either 'model' or 'models_path', not both")
+
+    store = GraphModelStore(cdb)
+
+    if model is not None:
+        store.save(model, name=model_name, version=model_version)
+        logger.debug("Initialized graph model '{}' from dict", model_name or "")
+    elif models_path is not None:
+        store.save_from_path(models_path, name=model_name, version=model_version)
+        logger.debug("Initialized graph model '{}' from path '{}'", model_name or "", models_path)
+
+    if description is not None:
+        store.update_description(description)
+        logger.debug("Updated graph description")

{sonnet_graph-0.3.2 → sonnet_graph-0.4.0}/src/sonnet_graph.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sonnet-graph
-Version: 0.3.2
+Version: 0.4.0
 Summary: Graph database integration (cypher-graphdb) for sonnet-server applications
 Author-email: Wolfgang Miller <wolfgang.miller@petrarca-labs.com>
 License-Expression: Apache-2.0
@@ -12,7 +12,7 @@ Requires-Python: <4.0,>=3.14
 Description-Content-Type: text/markdown
 Requires-Dist: sonnet-core>=0.1.0
 Requires-Dist: sonnet-server>=0.4.0
-Requires-Dist: cypher-graphdb>=0.5.0
+Requires-Dist: cypher-graphdb>=0.7.1
 Requires-Dist: loguru>=0.7.3
 Requires-Dist: jinja2>=3.1.6
 Provides-Extra: dev

{sonnet_graph-0.3.2 → sonnet_graph-0.4.0}/src/sonnet_graph.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ src/sonnet_graph/__init__.py
 src/sonnet_graph/context.py
 src/sonnet_graph/dependencies.py
 src/sonnet_graph/extension.py
+src/sonnet_graph/py.typed
 src/sonnet_graph/status.py
 src/sonnet_graph.egg-info/PKG-INFO
 src/sonnet_graph.egg-info/SOURCES.txt
@@ -18,6 +19,5 @@ src/sonnet_graph/metadata/__init__.py
 src/sonnet_graph/metadata/graph_info.py
 src/sonnet_graph/metadata/model_store.py
 src/sonnet_graph/metadata/models.py
-src/sonnet_graph/metadata/query_store.py
 src/sonnet_graph/metadata/seeding.py
 src/sonnet_graph/metadata/template_resolver.py

{sonnet_graph-0.3.2 → sonnet_graph-0.4.0}/src/sonnet_graph.egg-info/requires.txt

@@ -1,6 +1,6 @@
 sonnet-core>=0.1.0
 sonnet-server>=0.4.0
-cypher-graphdb>=0.5.0
+cypher-graphdb>=0.7.1
 loguru>=0.7.3
 jinja2>=3.1.6
 

sonnet_graph-0.3.2/src/sonnet_graph/metadata/query_store.py

@@ -1,264 +0,0 @@
-"""GraphQueryStore -- facade for :_NamedQuery nodes in a graph.
-
-Stores pre-defined queries with metadata. Multiple per graph, keyed
-by ``query_key`` (kebab-case). Supports three query languages:
-
-- ``cypher`` -- plain Cypher, executed directly
-- ``jinja2`` -- Jinja2 Cypher template, resolved via ``resolve_template()``
-  before execution
-- ``datalog`` -- Souffle-compatible Datalog rules, resolved by the
-  consumer's Datalog engine (e.g. lauro)
-
-The store is pure CRUD -- it never executes or resolves queries.
-Resolution is the consumer's responsibility.
-
-Usage::
-
-    from sonnet_graph import borrow_graphdb, GraphQueryStore
-
-    with borrow_graphdb("techstack") as cdb:
-        store = GraphQueryStore(cdb)
-
-        # Save a query
-        store.save(
-            query_key="hub-technologies",
-            title="Hub Technologies",
-            description="Technologies used by the most components",
-            tags=["analysis", "technology"],
-            query_content="MATCH (c:Component)-[:USES_TECHNOLOGY]->(t) ...",
-            language="cypher",
-        )
-        cdb.commit()
-
-        # List all (metadata only, no query_content)
-        queries = store.list()
-
-        # List filtered by tag
-        queries = store.list(tags=["analysis"])
-
-        # Load full query
-        query = store.load("hub-technologies")
-
-        # Remove one
-        store.remove("hub-technologies")
-
-        # Remove all (clean re-seed)
-        store.remove_all()
-        cdb.commit()
-"""
-
-from __future__ import annotations
-
-import builtins
-import json
-from typing import Any
-
-import arrow
-from cypher_graphdb import CypherGraphDB
-
-from sonnet_graph.metadata.models import NamedQueryNode, ensure_metadata_types
-
-
-class GraphQueryStore:
-    """Load/save/remove :_NamedQuery nodes in a graph.
-
-    Each query is identified by ``query_key`` (unique within the graph).
-    Uses ``create_or_merge`` with ``merge_keys=["query_key"]`` so each
-    node gets a proper ``gid_`` for cypher-graphdb identity.
-
-    The ``tags`` field is stored as a JSON-serialized string for
-    cross-backend compatibility (AGE stores arrays as JSON strings).
-    The ``list()`` and ``load()`` methods deserialize it back to
-    ``list[str]`` in the returned dicts.
-    """
-
-    def __init__(self, cdb: CypherGraphDB) -> None:
-        self._cdb = cdb
-        # The metadata types must be known to the connection's provider or
-        # these nodes come back as generic GraphNode. Seed them here so the
-        # store works on any connection, pooled or built directly.
-        ensure_metadata_types(cdb.model_provider)
-
-    # -- list ----------------------------------------------------------------
-
-    def list(self, *, tags: list[str] | None = None) -> list[dict[str, Any]]:
-        """List all named queries, optionally filtered by tags.
-
-        Returns metadata only (no ``query_content``) for lightweight
-        listing. Each entry is a dict with: ``query_key``, ``title``,
-        ``description``, ``tags``, ``language``, ``updated_at``.
-
-        Args:
-            tags: If provided, only return queries whose tags overlap
-                with at least one of the given tags.
-        """
-        result = self._cdb.execute(
-            "MATCH (q:_NamedQuery) RETURN q ORDER BY q.query_key",
-            unnest_result=True,
-        )
-        if not result:
-            return []
-
-        nodes = result if isinstance(result, list) else [result]
-        entries = []
-        for node in nodes:
-            if not isinstance(node, NamedQueryNode):
-                continue
-            node_tags = _deserialize_tags(node.tags)
-            if tags and not set(tags) & set(node_tags):
-                continue
-            entries.append(
-                {
-                    "query_key": node.query_key,
-                    "title": node.title,
-                    "description": node.description,
-                    "tags": node_tags,
-                    "language": node.language,
-                    "updated_at": node.updated_at,
-                }
-            )
-        return entries
-
-    # -- load ----------------------------------------------------------------
-
-    def load(self, query_key: str) -> dict[str, Any] | None:
-        """Load full query detail including query_content.
-
-        Returns a dict with all properties, or None if not found.
-        The ``tags``, ``params_schema``, and ``ui_schema`` fields
-        are deserialized from JSON strings.
-        """
-        node = self._load_node(query_key)
-        if node is None:
-            return None
-
-        return {
-            "query_key": node.query_key,
-            "title": node.title,
-            "description": node.description,
-            "tags": _deserialize_tags(node.tags),
-            "query_content": node.query_content,
-            "language": node.language,
-            "params_schema": _deserialize_json(node.params_schema),
-            "ui_schema": _deserialize_json(node.ui_schema),
-            "updated_at": node.updated_at,
-        }
-
-    def _load_node(self, query_key: str) -> NamedQueryNode | None:
-        """Load the raw NamedQueryNode by query_key, or None."""
-        result = self._cdb.execute(
-            "MATCH (q:_NamedQuery {query_key: $key}) RETURN q",
-            params={"key": query_key},
-            unnest_result=True,
-            fetch_one=True,
-        )
-        if not result or not isinstance(result, NamedQueryNode):
-            return None
-        return result
-
-    # -- save ----------------------------------------------------------------
-
-    def save(
-        self,
-        query_key: str,
-        *,
-        title: str | None = None,
-        description: str | None = None,
-        tags: builtins.list[str] | None = None,
-        query_content: str | None = None,
-        language: str | None = None,
-        params_schema: dict | None = None,
-        ui_schema: dict | None = None,
-    ) -> None:
-        """Create or update a named query.
-
-        Fetches the existing node (if any), updates only the provided
-        (non-None) fields, and persists via ``create_or_merge``. New
-        nodes get a ``gid_`` automatically.
-
-        Args:
-            query_key: Unique identifier (kebab-case).
-            title: Display name.
-            description: What the query does.
-            tags: Categorization tags (serialized to JSON).
-            query_content: The query text (Cypher, Jinja2, or Datalog).
-            language: ``"cypher"``, ``"jinja2"``, or ``"datalog"``.
-            params_schema: JSON Schema dict for parameter validation.
-            ui_schema: UI rendering hints dict for sonnet-ui.
-        """
-        existing = self._load_node(query_key)
-        node = existing if existing is not None else NamedQueryNode(query_key=query_key)
-
-        # Update only non-None fields (partial update)
-        if title is not None:
-            node.title = title
-        if description is not None:
-            node.description = description
-        if tags is not None:
-            node.tags = json.dumps(tags, ensure_ascii=False)
-        if query_content is not None:
-            node.query_content = query_content
-        if language is not None:
-            node.language = language
-        if params_schema is not None:
-            node.params_schema = json.dumps(params_schema, ensure_ascii=False)
-        if ui_schema is not None:
-            node.ui_schema = json.dumps(ui_schema, ensure_ascii=False)
-
-        node.updated_at = arrow.utcnow().isoformat()
-
-        self._cdb.create_or_merge(node)
-
-    # -- remove --------------------------------------------------------------
-
-    def remove(self, query_key: str) -> bool:
-        """Remove a named query. Returns True if it existed."""
-        existing = self._load_node(query_key)
-        if existing is None:
-            return False
-        self._cdb.delete(existing)
-        return True
-
-    def remove_all(self) -> int:
-        """Remove all named queries. Returns count removed.
-
-        Used for clean re-seeding.
-        """
-        result = self._cdb.execute(
-            "MATCH (q:_NamedQuery) RETURN count(q)",
-            unnest_result=True,
-            fetch_one=True,
-        )
-        count = int(result) if result else 0
-        if count > 0:
-            self._cdb.execute("MATCH (q:_NamedQuery) DELETE q")
-        return count
-
-
-# -- helpers -----------------------------------------------------------------
-
-
-def _deserialize_tags(tags_str: str | None) -> list[str]:
-    """Deserialize tags from JSON string to list."""
-    if not tags_str:
-        return []
-    try:
-        parsed = json.loads(tags_str)
-        if isinstance(parsed, list):
-            return parsed
-    except json.JSONDecodeError, TypeError:
-        pass
-    return []
-
-
-def _deserialize_json(value: str | None) -> dict | None:
-    """Deserialize a JSON string to dict, or None."""
-    if not value:
-        return None
-    try:
-        parsed = json.loads(value)
-        if isinstance(parsed, dict):
-            return parsed
-    except json.JSONDecodeError, TypeError:
-        pass
-    return None

sonnet_graph-0.3.2/src/sonnet_graph/metadata/seeding.py

@@ -1,170 +0,0 @@
-"""Graph metadata initialization and query seeding utilities.
-
-Two separate concerns:
-
-``init_graph_metadata(cdb, ...)`` -- initialize model and description
-    on the :_GraphModel node. One-time setup, called by
-    ``lauro graph init``. Raises on failure.
-
-``seed_named_queries(cdb, queries_dir)`` -- seed :_NamedQuery nodes from
-    file pairs (.json + .cypher/.jinja/.dl). Data seeding, idempotent
-    via MERGE. Returns ``QuerySeedResult`` with saved/skipped counts.
-"""
-
-from __future__ import annotations
-
-import json
-from dataclasses import dataclass, field
-from pathlib import Path
-
-from cypher_graphdb import CypherGraphDB
-from loguru import logger
-
-from sonnet_graph.metadata.model_store import GraphModelStore
-from sonnet_graph.metadata.query_store import GraphQueryStore
-
-# File extensions mapped to query language.
-_QUERY_EXTENSIONS: dict[str, str] = {
-    ".cypher": "cypher",
-    ".jinja": "jinja2",
-    ".jinja2": "jinja2",
-    ".dl": "datalog",
-}
-
-
-@dataclass
-class QuerySeedResult:
-    """Result of a ``seed_named_queries`` call.
-
-    Carries the partial-failure outcome: which query files were saved
-    and which were skipped (e.g. missing matching query file, parse
-    error). Callers use this to log, warn, or fail.
-    """
-
-    queries_saved: list[str] = field(default_factory=list)
-    queries_skipped: list[str] = field(default_factory=list)
-
-
-def init_graph_metadata(
-    cdb: CypherGraphDB,
-    *,
-    model: dict | None = None,
-    models_path: str | Path | None = None,
-    model_name: str | None = None,
-    model_version: str | None = None,
-    description: str | None = None,
-) -> None:
-    """Initialize graph metadata -- model schema and description.
-
-    Writes the :_GraphModel node with schema and optional description.
-    Intended for one-time graph initialization (``lauro graph init``).
-    Does NOT call ``commit()`` -- the caller is responsible.
-
-    Args:
-        cdb: Active CypherGraphDB connection.
-        model: JSON Schema dict to write as :_GraphModel node.
-        models_path: Path to a Python file or directory declaring graph
-            models on a ModelProvider. Generates and saves the schema.
-            Mutually exclusive with ``model``.
-        model_name: Graph model name.
-        model_version: Schema version string.
-        description: Markdown string stored on the :_GraphModel node.
-
-    Raises:
-        ValueError: If both ``model`` and ``models_path`` are provided.
-        ValueError: If ``description`` is provided without a model/models_path
-            and no :_GraphModel node already exists in the graph. Use
-            ``GraphModelStore.update_description()`` directly to update
-            an existing node's description independently.
-    """
-    if model is not None and models_path is not None:
-        raise ValueError("Provide either 'model' or 'models_path', not both")
-
-    store = GraphModelStore(cdb)
-
-    if model is not None:
-        store.save(model, name=model_name, version=model_version)
-        logger.debug("Initialized graph model '{}' from dict", model_name or "")
-    elif models_path is not None:
-        store.save_from_path(models_path, name=model_name, version=model_version)
-        logger.debug("Initialized graph model '{}' from path '{}'", model_name or "", models_path)
-
-    if description is not None:
-        store.update_description(description)
-        logger.debug("Updated graph description")
-
-
-def seed_named_queries(
-    cdb: CypherGraphDB,
-    queries_dir: str | Path,
-) -> QuerySeedResult:
-    """Seed :_NamedQuery nodes from file pairs in a directory.
-
-    Each pair is a ``.json`` metadata file + a query file (``.cypher``,
-    ``.jinja``, ``.jinja2``, or ``.dl``). The file stem is used as
-    ``query_key`` if not specified in the JSON.
-
-    Does NOT call ``commit()`` -- the caller is responsible.
-
-    Args:
-        cdb: Active CypherGraphDB connection.
-        queries_dir: Directory with query file pairs.
-
-    Returns:
-        QuerySeedResult with saved and skipped query keys.
-    """
-    result = QuerySeedResult()
-    _seed_queries(GraphQueryStore(cdb), Path(queries_dir), result)
-    return result
-
-
-def _seed_queries(store: GraphQueryStore, queries_dir: Path, result: QuerySeedResult) -> None:
-    """Seed named queries from file pairs in a directory."""
-    if not queries_dir.is_dir():
-        logger.warning("Queries directory does not exist: {}", queries_dir)
-        return
-
-    for json_path in sorted(queries_dir.glob("*.json")):
-        stem = json_path.stem
-        query_path = _find_query_file(queries_dir, stem)
-        if query_path is None:
-            logger.warning("No query file found for {}.json (expected .cypher, .jinja, .jinja2, or .dl)", stem)
-            result.queries_skipped.append(stem)
-            continue
-
-        try:
-            _seed_one_query(store, json_path, query_path, stem)
-            result.queries_saved.append(stem)
-            logger.debug("Seeded query '{}'", stem)
-        except Exception:
-            logger.exception("Failed to seed query '{}' from {}", stem, json_path)
-            result.queries_skipped.append(stem)
-
-
-def _find_query_file(directory: Path, stem: str) -> Path | None:
-    """Find the query file matching a JSON metadata file."""
-    for ext in _QUERY_EXTENSIONS:
-        candidate = directory / f"{stem}{ext}"
-        if candidate.is_file():
-            return candidate
-    return None
-
-
-def _seed_one_query(store: GraphQueryStore, json_path: Path, query_path: Path, stem: str) -> None:
-    """Read a file pair and save as a named query."""
-    metadata = json.loads(json_path.read_text(encoding="utf-8"))
-    query_content = query_path.read_text(encoding="utf-8")
-    language = _QUERY_EXTENSIONS.get(query_path.suffix, "cypher")
-
-    query_key = metadata.get("template_key") or metadata.get("query_key") or stem
-
-    store.save(
-        query_key,
-        title=metadata.get("title"),
-        description=metadata.get("description"),
-        tags=metadata.get("tags"),
-        query_content=query_content,
-        language=language,
-        params_schema=metadata.get("json_schema") or metadata.get("params_schema"),
-        ui_schema=metadata.get("ui_schema"),
-    )