sonnet-graph 0.1.0__tar.gz

sonnet_graph-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: sonnet-graph
+Version: 0.1.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
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <4.0,>=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: sonnet-server>=0.1.11
+Requires-Dist: cypher-graphdb>=0.2.7
+Requires-Dist: loguru>=0.7.3
+Provides-Extra: dev
+Requires-Dist: ruff>=0.3.0; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+
+# sonnet-graph
+
+Graph database integration (cypher-graphdb) for sonnet-server applications.
+
+Provides reusable infrastructure for sonnet-server apps that need a
+cypher-graphdb connection pool:
+
+- **`GraphDBExtension`** -- sonnet-server extension managing pool lifecycle
+  (startup/shutdown), with optional mode for apps where graph is not required.
+- **Pool context** -- `borrow_graphdb()` context manager and `get_current_graphdb()`
+  ambient session accessor via `ContextVar`.
+- **Readiness checks** -- `GraphdbStage` with initialization and health checks
+  for the sonnet-server readiness pipeline.
+- **FastAPI dependencies** -- `get_graphdb_session()` async generator for
+  router-level ambient sessions.
+
+## Installation
+
+```bash
+pip install sonnet-graph
+```
+
+## Usage
+
+```python
+from sonnet_graph import GraphDBExtension, borrow_graphdb, get_current_graphdb
+
+# In app.py -- register the extension
+_extension_registry = create_extension_registry(
+    DatabaseExtension(),
+    GraphDBExtension(),          # required (raises on missing CGDB_* settings)
+    GraphDBExtension(optional=True),  # or optional (skips if unconfigured)
+    ...
+)
+
+# In service code -- borrow a connection
+with borrow_graphdb() as db:
+    db.execute("MATCH (n) RETURN count(n)")
+
+# In service code -- ambient session (within borrow_graphdb scope)
+db = get_current_graphdb()
+```
+
+## Configuration
+
+Graph connection is configured via cypher-graphdb's own environment variables
+(not duplicated in consumer settings):
+
+| Variable | Description |
+|---|---|
+| `CGDB_BACKEND` | Backend type: `age` or `memgraph` |
+| `CGDB_CINFO` | Connection string / DSN |
+| `CGDB_GRAPH` | Graph name |
+| `CGDB_READ_ONLY` | Read-only mode (default: `false`) |
+| `CGDB_CREATE_GRAPH_IF_NOT_EXISTS` | Auto-create graph, AGE only (default: `false`) |

sonnet_graph-0.1.0/README.md

@@ -0,0 +1,55 @@
+# sonnet-graph
+
+Graph database integration (cypher-graphdb) for sonnet-server applications.
+
+Provides reusable infrastructure for sonnet-server apps that need a
+cypher-graphdb connection pool:
+
+- **`GraphDBExtension`** -- sonnet-server extension managing pool lifecycle
+  (startup/shutdown), with optional mode for apps where graph is not required.
+- **Pool context** -- `borrow_graphdb()` context manager and `get_current_graphdb()`
+  ambient session accessor via `ContextVar`.
+- **Readiness checks** -- `GraphdbStage` with initialization and health checks
+  for the sonnet-server readiness pipeline.
+- **FastAPI dependencies** -- `get_graphdb_session()` async generator for
+  router-level ambient sessions.
+
+## Installation
+
+```bash
+pip install sonnet-graph
+```
+
+## Usage
+
+```python
+from sonnet_graph import GraphDBExtension, borrow_graphdb, get_current_graphdb
+
+# In app.py -- register the extension
+_extension_registry = create_extension_registry(
+    DatabaseExtension(),
+    GraphDBExtension(),          # required (raises on missing CGDB_* settings)
+    GraphDBExtension(optional=True),  # or optional (skips if unconfigured)
+    ...
+)
+
+# In service code -- borrow a connection
+with borrow_graphdb() as db:
+    db.execute("MATCH (n) RETURN count(n)")
+
+# In service code -- ambient session (within borrow_graphdb scope)
+db = get_current_graphdb()
+```
+
+## Configuration
+
+Graph connection is configured via cypher-graphdb's own environment variables
+(not duplicated in consumer settings):
+
+| Variable | Description |
+|---|---|
+| `CGDB_BACKEND` | Backend type: `age` or `memgraph` |
+| `CGDB_CINFO` | Connection string / DSN |
+| `CGDB_GRAPH` | Graph name |
+| `CGDB_READ_ONLY` | Read-only mode (default: `false`) |
+| `CGDB_CREATE_GRAPH_IF_NOT_EXISTS` | Auto-create graph, AGE only (default: `false`) |

sonnet_graph-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sonnet-graph"
+version = "0.1.0"
+authors = [
+    { name = "Wolfgang Miller", email = "wolfgang.miller@petrarca-labs.com" },
+]
+description = "Graph database integration (cypher-graphdb) for sonnet-server applications"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.14,<4.0"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "sonnet-server>=0.1.11",
+    "cypher-graphdb>=0.2.7",
+    "loguru>=0.7.3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.3.0",
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.23.0",
+]
+
+[tool.uv.sources]
+sonnet-server = { workspace = true }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+markers = [
+    "unit: marks tests as unit tests (default)",
+    "integration: marks tests as integration tests",
+]
+testpaths = ["tests"]
+addopts = [
+    "-m unit",
+    "--strict-markers",
+]
+asyncio_mode = "auto"

sonnet_graph-0.1.0/setup.cfg

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

sonnet_graph-0.1.0/src/sonnet_graph/__init__.py

@@ -0,0 +1,51 @@
+"""sonnet-graph -- Graph database integration for sonnet-server applications.
+
+Public API:
+
+  Extension (register in app.py):
+    GraphDBExtension         -- pool lifecycle, readiness checks
+
+  Pool context:
+    borrow_graphdb           -- context manager: acquire connection + set ContextVar
+    get_current_graphdb      -- read ambient CypherGraphDB from ContextVar
+    init_graphdb_pool        -- lazily create the pool singleton
+    dispose_graphdb_pool     -- close and discard the pool
+    is_pool_initialized      -- check if pool exists
+    graphdb_configured       -- check if CGDB_* settings are present
+
+  FastAPI dependencies:
+    get_graphdb_session      -- async generator for router-level ambient session
+    get_graphdb              -- sync generator yielding CypherGraphDB explicitly
+
+  Readiness pipeline (auto-registered by GraphDBExtension):
+    GraphdbStage             -- pipeline stage marker (order=40)
+"""
+
+from sonnet_graph.checks.stages import GraphdbStage
+from sonnet_graph.context import (
+    borrow_graphdb,
+    dispose_graphdb_pool,
+    get_current_graphdb,
+    graphdb_configured,
+    init_graphdb_pool,
+    is_pool_initialized,
+)
+from sonnet_graph.dependencies import get_graphdb, get_graphdb_session
+from sonnet_graph.extension import GraphDBExtension
+
+__all__ = [
+    # Extension
+    "GraphDBExtension",
+    # Pool context
+    "borrow_graphdb",
+    "dispose_graphdb_pool",
+    "get_current_graphdb",
+    "graphdb_configured",
+    "init_graphdb_pool",
+    "is_pool_initialized",
+    # FastAPI dependencies
+    "get_graphdb",
+    "get_graphdb_session",
+    # Readiness pipeline
+    "GraphdbStage",
+]

sonnet_graph-0.1.0/src/sonnet_graph/checks/__init__.py

@@ -0,0 +1,11 @@
+"""Graph DB readiness checks for the sonnet-graph package.
+
+Importing this package registers ``GraphdbStage`` in the global stage
+registry (via the ``@readiness_stage`` decorator in ``stages.py``).
+
+Check classes are registered lazily -- they are imported by
+``GraphDBExtension.on_startup()`` so they only appear in the pipeline
+when the extension is active.
+"""
+
+from sonnet_graph.checks.stages import GraphdbStage  # noqa: F401 -- registers stage

sonnet_graph-0.1.0/src/sonnet_graph/checks/graphdb_health_check.py

@@ -0,0 +1,35 @@
+"""GraphDB connection health check for readiness pipeline."""
+
+from loguru import logger
+
+from sonnet_graph.checks.stages import GraphdbStage
+from sonnet_graph.context import borrow_graphdb
+from sonnet_server.readiness_pipeline import ReadinessCheck, ReadinessCheckResult, readiness_check
+
+
+@readiness_check(stage=GraphdbStage, is_critical=True, run_once=False, order=1)
+class GraphDBHealthCheck(ReadinessCheck):
+    """Verifies a live connection to the graph database."""
+
+    def __init__(self) -> None:
+        super().__init__("graphdb_health_check")
+
+    def _execute(self) -> ReadinessCheckResult:
+        logger.info("Checking GraphDB connection health")
+        try:
+            with borrow_graphdb() as cdb:
+                if not cdb.check_connection():
+                    return self.failed(
+                        "CypherGraphDB connection check failed",
+                        {"graph": getattr(cdb, "graph_name", None)},
+                    )
+                return self.success(
+                    "CypherGraphDB connection is healthy",
+                    {
+                        "id": getattr(cdb, "id", None),
+                        "graph": getattr(cdb, "graph_name", None),
+                    },
+                )
+        except (OSError, RuntimeError, ConnectionError, TimeoutError) as e:
+            logger.error("GraphDB health check failed: {}", e)
+            return self.failed(f"GraphDB health check failed: {e}", {"error": str(e)})

sonnet_graph-0.1.0/src/sonnet_graph/checks/graphdb_initialization.py

@@ -0,0 +1,28 @@
+"""GraphDB pool initialization check for readiness pipeline."""
+
+from loguru import logger
+
+from sonnet_graph.checks.stages import GraphdbStage
+from sonnet_graph.context import init_graphdb_pool, is_pool_initialized
+from sonnet_server.readiness_pipeline import ReadinessCheck, ReadinessCheckResult, readiness_check
+
+
+@readiness_check(stage=GraphdbStage, is_critical=True, run_once=True, order=0)
+class GraphDBInitializationCheck(ReadinessCheck):
+    """Ensures the CypherGraphDB connection pool is initialized."""
+
+    def __init__(self) -> None:
+        super().__init__("graphdb_initialization")
+
+    def _execute(self) -> ReadinessCheckResult:
+        logger.info("Checking GraphDB pool initialization")
+        try:
+            if not is_pool_initialized():
+                init_graphdb_pool()
+            return self.success("CypherGraphDB pool initialized", {"initialized": True})
+        except (OSError, RuntimeError, ConnectionError, TimeoutError) as e:
+            logger.error("CypherGraphDB initialization failed: {}", e)
+            return self.failed(
+                f"CypherGraphDB initialization failed: {e}",
+                {"error": str(e), "type": type(e).__name__, "initialized": False},
+            )

sonnet_graph-0.1.0/src/sonnet_graph/checks/stages.py

@@ -0,0 +1,13 @@
+"""Graph database readiness pipeline stage.
+
+Registered at import time via the @readiness_stage decorator.
+Order 40 places it after database (1), messaging (2), cache (3)
+but before application-specific stages (50+).
+"""
+
+from sonnet_server.readiness_pipeline import readiness_stage
+
+
+@readiness_stage(order=40, description="Graph database checks", is_critical=False, fail_fast=True)
+class GraphdbStage:
+    """CypherGraphDB connection pool initialization and health."""

sonnet_graph-0.1.0/src/sonnet_graph/context.py

@@ -0,0 +1,151 @@
+"""Graph DB connection pool lifecycle and ambient session management.
+
+Provides:
+    - ``init_graphdb_pool()``    -- lazily initialise the connection pool
+    - ``dispose_graphdb_pool()`` -- close and discard the pool
+    - ``borrow_graphdb()``       -- context manager: acquire connection, set ContextVar
+    - ``get_current_graphdb()``  -- read the ambient CypherGraphDB from ContextVar
+    - ``is_pool_initialized()``  -- check if the pool has been created
+    - ``graphdb_configured()``   -- check if CGDB_* settings are present
+
+Configuration comes from cypher-graphdb's own settings
+(CGDB_BACKEND, CGDB_CINFO, CGDB_GRAPH) -- not duplicated here.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager, suppress
+from contextvars import ContextVar
+
+from cypher_graphdb import CypherGraphDB
+from cypher_graphdb.dbpool import CypherGraphDBPool
+from cypher_graphdb.settings import Settings as CypherSettings
+from cypher_graphdb.settings import get_settings as get_cypher_settings
+from loguru import logger
+
+_current_graphdb: ContextVar[CypherGraphDB | None] = ContextVar("_current_graphdb", default=None)
+
+# Held as a module-level variable so dispose_graphdb_pool() can close it
+# without risk of accidentally recreating it.
+_pool_instance: CypherGraphDBPool | None = None
+
+
+def graphdb_configured(settings: CypherSettings | None = None) -> bool:
+    """Return True if the required CGDB_* environment variables are set."""
+    s = settings or get_cypher_settings()
+    return bool(s.backend and s.cinfo and s.graph)
+
+
+def get_current_graphdb() -> CypherGraphDB:
+    """Return the ambient CypherGraphDB session.
+
+    Must be called within a ``borrow_graphdb()`` context.
+
+    Raises:
+        RuntimeError: If no active session exists.
+    """
+    cdb = _current_graphdb.get()
+    if cdb is None:
+        raise RuntimeError("No active CypherGraphDB session -- call within borrow_graphdb() context")
+    return cdb
+
+
+@contextmanager
+def borrow_graphdb(block: bool = True, timeout: float = 10.0) -> Iterator[CypherGraphDB]:
+    """Acquire a CypherGraphDB from the pool and set the ambient ContextVar.
+
+    The connection is returned to the pool when the context exits.
+
+    Args:
+        block: Whether to block if no connections are available.
+        timeout: Maximum seconds to wait for a connection.
+    """
+    pool = _get_or_create_pool()
+    with pool.acquire(block=block, timeout=timeout) as cdb:
+        token = _current_graphdb.set(cdb)
+        try:
+            yield cdb
+        finally:
+            _current_graphdb.reset(token)
+
+
+def init_graphdb_pool(*, pool_size: int = 3) -> bool:
+    """Initialize the graph DB connection pool.
+
+    Must be called before the first ``borrow_graphdb()`` to configure
+    pool_size. Safe to call multiple times -- idempotent once created.
+
+    Returns True if the pool was created, False if CGDB_* settings are missing.
+    """
+    global _pool_instance
+    if not graphdb_configured():
+        return False
+    if _pool_instance is None:
+        _pool_instance = _create_pool(pool_size)
+        logger.info("GraphDB pool initialized")
+    return True
+
+
+def dispose_graphdb_pool() -> None:
+    """Shut down the pool and release all connections."""
+    global _pool_instance
+    if _pool_instance is not None:
+        with suppress(RuntimeError, ConnectionError, OSError):
+            _pool_instance.close()
+        _pool_instance = None
+    logger.info("GraphDB pool disposed")
+
+
+def is_pool_initialized() -> bool:
+    """Return True if the pool has been created."""
+    return _pool_instance is not None
+
+
+# -- internal ----------------------------------------------------------------
+
+
+def _get_or_create_pool() -> CypherGraphDBPool:
+    """Return the existing pool or create one with default pool_size=3.
+
+    Called by ``borrow_graphdb()`` when the pool was not pre-initialized
+    via ``init_graphdb_pool()``. Falls back to pool_size=3.
+    """
+    global _pool_instance
+    if _pool_instance is None:
+        _pool_instance = _create_pool(pool_size=3)
+    return _pool_instance
+
+
+def _create_pool(pool_size: int) -> CypherGraphDBPool:
+    """Create and return a new CypherGraphDBPool."""
+    settings = get_cypher_settings()
+    if not settings.backend:
+        raise RuntimeError("Graph backend not configured. Set CGDB_BACKEND.")
+    if not settings.cinfo:
+        raise RuntimeError("Graph connection not configured. Set CGDB_CINFO.")
+    if not settings.graph:
+        raise RuntimeError("Graph name not configured. Set CGDB_GRAPH.")
+
+    connect_params = {
+        "cinfo": settings.cinfo,
+        "graph_name": settings.graph,
+        "read_only": settings.read_only,
+        "create_graph": settings.create_graph,
+    }
+    # 0 means "no timeout" -- don't pass it (leave backend at its own default).
+    if settings.query_timeout_s:
+        connect_params["query_timeout_s"] = settings.query_timeout_s
+    pool = CypherGraphDBPool(
+        backend=settings.backend,
+        connect_params=connect_params,
+        pool_size=pool_size,
+        auto_connect=True,
+    )
+    logger.debug(
+        "GraphDB pool created: backend={}, graph={}, pool_size={}",
+        settings.backend,
+        settings.graph,
+        pool_size,
+    )
+    return pool

sonnet_graph-0.1.0/src/sonnet_graph/dependencies.py

@@ -0,0 +1,53 @@
+"""FastAPI dependencies for graph database access.
+
+Provides two dependency patterns:
+
+1. **Ambient session** (recommended) -- use ``graphdb_router()`` from
+   sonnet-server's ``api.dependencies`` module, or add
+   ``get_graphdb_session`` as a router-level dependency. Services then
+   call ``get_current_graphdb()`` without parameters.
+
+2. **Explicit parameter** -- use ``Depends(get_graphdb)`` on individual
+   endpoints to receive a ``CypherGraphDB`` instance directly.
+
+Example::
+
+    from fastapi import APIRouter, Depends
+    from sonnet_graph.dependencies import get_graphdb_session
+    from sonnet_graph.context import get_current_graphdb
+
+    router = APIRouter(dependencies=[Depends(get_graphdb_session)])
+
+    @router.get("/nodes")
+    def list_nodes():
+        db = get_current_graphdb()
+        return db.execute("MATCH (n) RETURN n LIMIT 10")
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator
+
+from cypher_graphdb import CypherGraphDB
+
+from sonnet_graph.context import borrow_graphdb
+
+
+async def get_graphdb_session() -> AsyncIterator[None]:
+    """Router-level dependency establishing an ambient graphdb session.
+
+    Sets the ContextVar so services can call ``get_current_graphdb()``
+    without receiving CypherGraphDB as a parameter.
+    """
+    with borrow_graphdb():
+        yield
+
+
+def get_graphdb() -> Iterator[CypherGraphDB]:
+    """Endpoint-level dependency yielding a CypherGraphDB instance explicitly.
+
+    Prefer the ambient session pattern (``get_graphdb_session`` + ``get_current_graphdb``)
+    for new code.
+    """
+    with borrow_graphdb() as db:
+        yield db

sonnet_graph-0.1.0/src/sonnet_graph/extension.py

@@ -0,0 +1,72 @@
+"""GraphDB infrastructure extension for sonnet-server applications.
+
+Manages the CypherGraphDB connection pool lifecycle (startup/shutdown)
+and optionally registers readiness checks.
+
+Usage in app.py::
+
+    from sonnet_graph import GraphDBExtension
+
+    _extension_registry = create_extension_registry(
+        GraphDBExtension(),               # required -- raises if CGDB_* missing
+        GraphDBExtension(optional=True),   # optional -- skips if unconfigured
+    )
+"""
+
+from __future__ import annotations
+
+from loguru import logger
+
+from sonnet_server.extensions import Extension
+from sonnet_server.settings import Settings
+
+
+class GraphDBExtension(Extension):
+    """Infrastructure extension for the CypherGraphDB connection pool.
+
+    Starts unconditionally (no profile). Initialises the pool on startup
+    and disposes it on shutdown.
+
+    Args:
+        optional: If True, silently skip when CGDB_* settings are absent.
+            If False (default), raise RuntimeError on missing settings.
+        pool_size: Maximum number of pooled connections (default: 3).
+    """
+
+    def __init__(self, *, optional: bool = False, pool_size: int = 3) -> None:
+        self._optional = optional
+        self._pool_size = pool_size
+        self._active = False
+
+    @property
+    def name(self) -> str:
+        return "graphdb"
+
+    async def on_startup(self, settings: Settings) -> None:
+        from sonnet_graph.context import graphdb_configured, init_graphdb_pool
+
+        if not graphdb_configured():
+            if self._optional:
+                logger.info("GraphDBExtension: CGDB_* settings not configured, skipping (optional)")
+                return
+            raise RuntimeError(
+                "GraphDBExtension: graph database not configured. "
+                "Set CGDB_BACKEND, CGDB_CINFO, and CGDB_GRAPH environment variables."
+            )
+
+        init_graphdb_pool(pool_size=self._pool_size)
+        self._active = True
+
+        # Import check modules to trigger @readiness_check decorator registration.
+        import sonnet_graph.checks.graphdb_health_check  # noqa: F401
+        import sonnet_graph.checks.graphdb_initialization  # noqa: F401
+
+        logger.info("GraphDBExtension: pool initialized, readiness checks registered")
+
+    async def on_shutdown(self) -> None:
+        if not self._active:
+            return
+        from sonnet_graph.context import dispose_graphdb_pool
+
+        dispose_graphdb_pool()
+        self._active = False

sonnet_graph-0.1.0/src/sonnet_graph.egg-info/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: sonnet-graph
+Version: 0.1.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
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <4.0,>=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: sonnet-server>=0.1.11
+Requires-Dist: cypher-graphdb>=0.2.7
+Requires-Dist: loguru>=0.7.3
+Provides-Extra: dev
+Requires-Dist: ruff>=0.3.0; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+
+# sonnet-graph
+
+Graph database integration (cypher-graphdb) for sonnet-server applications.
+
+Provides reusable infrastructure for sonnet-server apps that need a
+cypher-graphdb connection pool:
+
+- **`GraphDBExtension`** -- sonnet-server extension managing pool lifecycle
+  (startup/shutdown), with optional mode for apps where graph is not required.
+- **Pool context** -- `borrow_graphdb()` context manager and `get_current_graphdb()`
+  ambient session accessor via `ContextVar`.
+- **Readiness checks** -- `GraphdbStage` with initialization and health checks
+  for the sonnet-server readiness pipeline.
+- **FastAPI dependencies** -- `get_graphdb_session()` async generator for
+  router-level ambient sessions.
+
+## Installation
+
+```bash
+pip install sonnet-graph
+```
+
+## Usage
+
+```python
+from sonnet_graph import GraphDBExtension, borrow_graphdb, get_current_graphdb
+
+# In app.py -- register the extension
+_extension_registry = create_extension_registry(
+    DatabaseExtension(),
+    GraphDBExtension(),          # required (raises on missing CGDB_* settings)
+    GraphDBExtension(optional=True),  # or optional (skips if unconfigured)
+    ...
+)
+
+# In service code -- borrow a connection
+with borrow_graphdb() as db:
+    db.execute("MATCH (n) RETURN count(n)")
+
+# In service code -- ambient session (within borrow_graphdb scope)
+db = get_current_graphdb()
+```
+
+## Configuration
+
+Graph connection is configured via cypher-graphdb's own environment variables
+(not duplicated in consumer settings):
+
+| Variable | Description |
+|---|---|
+| `CGDB_BACKEND` | Backend type: `age` or `memgraph` |
+| `CGDB_CINFO` | Connection string / DSN |
+| `CGDB_GRAPH` | Graph name |
+| `CGDB_READ_ONLY` | Read-only mode (default: `false`) |
+| `CGDB_CREATE_GRAPH_IF_NOT_EXISTS` | Auto-create graph, AGE only (default: `false`) |

sonnet_graph-0.1.0/src/sonnet_graph.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+src/sonnet_graph/__init__.py
+src/sonnet_graph/context.py
+src/sonnet_graph/dependencies.py
+src/sonnet_graph/extension.py
+src/sonnet_graph.egg-info/PKG-INFO
+src/sonnet_graph.egg-info/SOURCES.txt
+src/sonnet_graph.egg-info/dependency_links.txt
+src/sonnet_graph.egg-info/requires.txt
+src/sonnet_graph.egg-info/top_level.txt
+src/sonnet_graph/checks/__init__.py
+src/sonnet_graph/checks/graphdb_health_check.py
+src/sonnet_graph/checks/graphdb_initialization.py
+src/sonnet_graph/checks/stages.py
+tests/test_checks.py
+tests/test_context.py
+tests/test_extension.py

sonnet_graph-0.1.0/src/sonnet_graph.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sonnet_graph-0.1.0/src/sonnet_graph.egg-info/requires.txt

@@ -0,0 +1,8 @@
+sonnet-server>=0.1.11
+cypher-graphdb>=0.2.7
+loguru>=0.7.3
+
+[dev]
+ruff>=0.3.0
+pytest>=7.0.0
+pytest-asyncio>=0.23.0

sonnet_graph-0.1.0/src/sonnet_graph.egg-info/top_level.txt

@@ -0,0 +1 @@
+sonnet_graph

sonnet_graph-0.1.0/tests/test_checks.py

@@ -0,0 +1,123 @@
+"""Unit tests for sonnet_graph readiness checks."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+# ---------------------------------------------------------------------------
+# GraphDBInitializationCheck
+# ---------------------------------------------------------------------------
+
+
+class TestGraphDBInitializationCheck:
+    def test_success_when_already_initialized(self):
+        from sonnet_graph.checks.graphdb_initialization import GraphDBInitializationCheck
+
+        check = GraphDBInitializationCheck()
+        with patch("sonnet_graph.checks.graphdb_initialization.is_pool_initialized", return_value=True):
+            result = check._execute()
+        assert result.status == "success"
+
+    def test_success_when_init_succeeds(self):
+        from sonnet_graph.checks.graphdb_initialization import GraphDBInitializationCheck
+
+        check = GraphDBInitializationCheck()
+        with (
+            patch("sonnet_graph.checks.graphdb_initialization.is_pool_initialized", return_value=False),
+            patch("sonnet_graph.checks.graphdb_initialization.init_graphdb_pool"),
+        ):
+            result = check._execute()
+        assert result.status == "success"
+
+    def test_failed_when_init_raises_runtime_error(self):
+        from sonnet_graph.checks.graphdb_initialization import GraphDBInitializationCheck
+
+        check = GraphDBInitializationCheck()
+        with (
+            patch("sonnet_graph.checks.graphdb_initialization.is_pool_initialized", return_value=False),
+            patch("sonnet_graph.checks.graphdb_initialization.init_graphdb_pool", side_effect=RuntimeError("no backend")),
+        ):
+            result = check._execute()
+        assert result.status == "failed"
+        assert "no backend" in result.message
+
+    def test_failed_when_init_raises_os_error(self):
+        from sonnet_graph.checks.graphdb_initialization import GraphDBInitializationCheck
+
+        check = GraphDBInitializationCheck()
+        with (
+            patch("sonnet_graph.checks.graphdb_initialization.is_pool_initialized", return_value=False),
+            patch("sonnet_graph.checks.graphdb_initialization.init_graphdb_pool", side_effect=OSError("conn refused")),
+        ):
+            result = check._execute()
+        assert result.status == "failed"
+
+    def test_failed_when_init_raises_timeout_error(self):
+        from sonnet_graph.checks.graphdb_initialization import GraphDBInitializationCheck
+
+        check = GraphDBInitializationCheck()
+        with (
+            patch("sonnet_graph.checks.graphdb_initialization.is_pool_initialized", return_value=False),
+            patch("sonnet_graph.checks.graphdb_initialization.init_graphdb_pool", side_effect=TimeoutError("timed out")),
+        ):
+            result = check._execute()
+        assert result.status == "failed"
+
+
+# ---------------------------------------------------------------------------
+# GraphDBHealthCheck
+# ---------------------------------------------------------------------------
+
+
+class TestGraphDBHealthCheck:
+    def test_success_when_connection_healthy(self):
+        from sonnet_graph.checks.graphdb_health_check import GraphDBHealthCheck
+
+        check = GraphDBHealthCheck()
+        mock_cdb = MagicMock()
+        mock_cdb.check_connection.return_value = True
+        mock_cdb.id = "test-id"
+        mock_cdb.graph_name = "test-graph"
+
+        with patch("sonnet_graph.checks.graphdb_health_check.borrow_graphdb") as mock_borrow:
+            mock_borrow.return_value.__enter__ = MagicMock(return_value=mock_cdb)
+            mock_borrow.return_value.__exit__ = MagicMock(return_value=False)
+            result = check._execute()
+
+        assert result.status == "success"
+        assert "healthy" in result.message
+        assert result.details.get("id") == "test-id"
+        assert result.details.get("graph") == "test-graph"
+
+    def test_failed_when_check_returns_false(self):
+        from sonnet_graph.checks.graphdb_health_check import GraphDBHealthCheck
+
+        check = GraphDBHealthCheck()
+        mock_cdb = MagicMock()
+        mock_cdb.check_connection.return_value = False
+
+        with patch("sonnet_graph.checks.graphdb_health_check.borrow_graphdb") as mock_borrow:
+            mock_borrow.return_value.__enter__ = MagicMock(return_value=mock_cdb)
+            mock_borrow.return_value.__exit__ = MagicMock(return_value=False)
+            result = check._execute()
+
+        assert result.status == "failed"
+
+    def test_failed_when_borrow_raises_runtime_error(self):
+        from sonnet_graph.checks.graphdb_health_check import GraphDBHealthCheck
+
+        check = GraphDBHealthCheck()
+        with patch("sonnet_graph.checks.graphdb_health_check.borrow_graphdb", side_effect=RuntimeError("pool exhausted")):
+            result = check._execute()
+
+        assert result.status == "failed"
+        assert "pool exhausted" in result.message
+
+    def test_failed_when_borrow_raises_timeout_error(self):
+        from sonnet_graph.checks.graphdb_health_check import GraphDBHealthCheck
+
+        check = GraphDBHealthCheck()
+        with patch("sonnet_graph.checks.graphdb_health_check.borrow_graphdb", side_effect=TimeoutError("timed out")):
+            result = check._execute()
+
+        assert result.status == "failed"

sonnet_graph-0.1.0/tests/test_context.py

@@ -0,0 +1,193 @@
+"""Unit tests for sonnet_graph.context -- pool lifecycle and ambient session."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+import sonnet_graph.context as _ctx
+from sonnet_graph.context import (
+    borrow_graphdb,
+    dispose_graphdb_pool,
+    get_current_graphdb,
+    graphdb_configured,
+    init_graphdb_pool,
+    is_pool_initialized,
+)
+
+# ---------------------------------------------------------------------------
+# graphdb_configured
+# ---------------------------------------------------------------------------
+
+
+class TestGraphdbConfigured:
+    def test_returns_false_when_no_backend(self):
+        settings = MagicMock(backend=None, cinfo="bolt://localhost", graph="test")
+        assert graphdb_configured(settings) is False
+
+    def test_returns_false_when_no_cinfo(self):
+        settings = MagicMock(backend="age", cinfo=None, graph="test")
+        assert graphdb_configured(settings) is False
+
+    def test_returns_false_when_no_graph(self):
+        settings = MagicMock(backend="age", cinfo="bolt://localhost", graph=None)
+        assert graphdb_configured(settings) is False
+
+    def test_returns_false_when_all_empty(self):
+        settings = MagicMock(backend="", cinfo="", graph="")
+        assert graphdb_configured(settings) is False
+
+    def test_returns_true_when_all_set(self):
+        settings = MagicMock(backend="age", cinfo="host=localhost", graph="test")
+        assert graphdb_configured(settings) is True
+
+
+# ---------------------------------------------------------------------------
+# get_current_graphdb
+# ---------------------------------------------------------------------------
+
+
+class TestGetCurrentGraphdb:
+    def test_raises_outside_borrow_context(self):
+        with pytest.raises(RuntimeError, match="No active CypherGraphDB session"):
+            get_current_graphdb()
+
+
+# ---------------------------------------------------------------------------
+# init / dispose / is_pool_initialized
+# ---------------------------------------------------------------------------
+
+
+class TestPoolLifecycle:
+    @patch("sonnet_graph.context.graphdb_configured", return_value=False)
+    def test_init_returns_false_when_not_configured(self, _mock):
+        assert init_graphdb_pool() is False
+        assert is_pool_initialized() is False
+
+    @patch("sonnet_graph.context.get_cypher_settings")
+    @patch("sonnet_graph.context.CypherGraphDBPool")
+    def test_init_creates_pool_when_configured(self, mock_pool_cls, mock_settings):
+        mock_settings.return_value = MagicMock(
+            backend="age",
+            cinfo="host=localhost",
+            graph="test",
+            read_only=False,
+            create_graph=True,
+            query_timeout_s=None,  # None = no timeout, omitted from connect_params
+        )
+        mock_pool_cls.return_value = MagicMock()
+
+        result = init_graphdb_pool(pool_size=5)
+
+        assert result is True
+        assert is_pool_initialized() is True
+        mock_pool_cls.assert_called_once_with(
+            backend="age",
+            connect_params={
+                "cinfo": "host=localhost",
+                "graph_name": "test",
+                "read_only": False,
+                "create_graph": True,
+            },
+            pool_size=5,
+            auto_connect=True,
+        )
+
+    @patch("sonnet_graph.context.get_cypher_settings")
+    @patch("sonnet_graph.context.CypherGraphDBPool")
+    def test_init_is_idempotent(self, mock_pool_cls, mock_settings):
+        """Calling init_graphdb_pool twice must not create a second pool."""
+        mock_settings.return_value = MagicMock(
+            backend="age",
+            cinfo="host=localhost",
+            graph="test",
+            read_only=False,
+            create_graph=False,
+            query_timeout_s=None,
+        )
+        mock_pool_cls.return_value = MagicMock()
+
+        init_graphdb_pool()
+        init_graphdb_pool()
+
+        mock_pool_cls.assert_called_once()
+
+    @patch("sonnet_graph.context.get_cypher_settings")
+    @patch("sonnet_graph.context.CypherGraphDBPool")
+    def test_dispose_closes_pool(self, mock_pool_cls, mock_settings):
+        mock_settings.return_value = MagicMock(
+            backend="age",
+            cinfo="host=localhost",
+            graph="test",
+            read_only=False,
+            create_graph=False,
+            query_timeout_s=None,
+        )
+        mock_pool = MagicMock()
+        mock_pool_cls.return_value = mock_pool
+
+        init_graphdb_pool()
+        assert is_pool_initialized() is True
+
+        dispose_graphdb_pool()
+        assert is_pool_initialized() is False
+        mock_pool.close.assert_called_once()
+
+    def test_dispose_safe_when_no_pool(self):
+        assert _ctx._pool_instance is None
+        dispose_graphdb_pool()  # must not raise
+
+    @patch("sonnet_graph.context.get_cypher_settings")
+    @patch("sonnet_graph.context.CypherGraphDBPool")
+    def test_pool_size_reset_after_dispose(self, mock_pool_cls, mock_settings):
+        """pool_size from first init must not bleed into a second init after dispose."""
+        mock_settings.return_value = MagicMock(
+            backend="age",
+            cinfo="host=localhost",
+            graph="test",
+            read_only=False,
+            create_graph=False,
+            query_timeout_s=None,
+        )
+        mock_pool_cls.return_value = MagicMock()
+
+        init_graphdb_pool(pool_size=10)
+        dispose_graphdb_pool()
+        init_graphdb_pool(pool_size=3)
+
+        calls = mock_pool_cls.call_args_list
+        assert calls[0][1]["pool_size"] == 10
+        assert calls[1][1]["pool_size"] == 3
+
+
+# ---------------------------------------------------------------------------
+# borrow_graphdb
+# ---------------------------------------------------------------------------
+
+
+class TestBorrowGraphdb:
+    @patch("sonnet_graph.context.get_cypher_settings")
+    @patch("sonnet_graph.context.CypherGraphDBPool")
+    def test_sets_and_resets_contextvar(self, mock_pool_cls, mock_settings):
+        mock_settings.return_value = MagicMock(
+            backend="age",
+            cinfo="host=localhost",
+            graph="test",
+            read_only=False,
+            create_graph=False,
+            query_timeout_s=None,
+        )
+        mock_cdb = MagicMock()
+        mock_pool = MagicMock()
+        mock_pool.acquire.return_value.__enter__ = MagicMock(return_value=mock_cdb)
+        mock_pool.acquire.return_value.__exit__ = MagicMock(return_value=False)
+        mock_pool_cls.return_value = mock_pool
+
+        with borrow_graphdb() as db:
+            assert db is mock_cdb
+            assert get_current_graphdb() is mock_cdb
+
+        # After exit, ContextVar must be reset
+        with pytest.raises(RuntimeError, match="No active CypherGraphDB session"):
+            get_current_graphdb()

sonnet_graph-0.1.0/tests/test_extension.py

@@ -0,0 +1,66 @@
+"""Unit tests for sonnet_graph.extension -- GraphDBExtension."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from sonnet_graph.extension import GraphDBExtension
+
+
+class TestGraphDBExtension:
+    def test_name(self):
+        assert GraphDBExtension().name == "graphdb"
+
+    def test_profile_is_none(self):
+        assert GraphDBExtension().profile is None
+
+    def test_default_not_optional(self):
+        assert GraphDBExtension()._optional is False
+
+    def test_optional_flag(self):
+        assert GraphDBExtension(optional=True)._optional is True
+
+    @patch("sonnet_graph.context.graphdb_configured", return_value=False)
+    async def test_raises_when_not_configured_and_required(self, _mock):
+        ext = GraphDBExtension(optional=False)
+        with pytest.raises(RuntimeError, match="graph database not configured"):
+            await ext.on_startup(MagicMock())
+
+    @patch("sonnet_graph.context.graphdb_configured", return_value=False)
+    async def test_skips_when_not_configured_and_optional(self, _mock):
+        ext = GraphDBExtension(optional=True)
+        await ext.on_startup(MagicMock())
+        assert ext._active is False
+
+    @patch("sonnet_graph.checks.graphdb_health_check", create=True)
+    @patch("sonnet_graph.checks.graphdb_initialization", create=True)
+    @patch("sonnet_graph.context.init_graphdb_pool")
+    @patch("sonnet_graph.context.graphdb_configured", return_value=True)
+    async def test_initializes_pool_when_configured(self, _configured, mock_init, _check1, _check2):
+        ext = GraphDBExtension(pool_size=5)
+        await ext.on_startup(MagicMock())
+        assert ext._active is True
+        mock_init.assert_called_once_with(pool_size=5)
+
+    async def test_shutdown_noop_when_not_active(self):
+        ext = GraphDBExtension()
+        await ext.on_shutdown()  # must not raise
+
+    @patch("sonnet_graph.context.dispose_graphdb_pool")
+    async def test_shutdown_disposes_pool_when_active(self, mock_dispose):
+        ext = GraphDBExtension()
+        ext._active = True
+        await ext.on_shutdown()
+        mock_dispose.assert_called_once()
+        assert ext._active is False
+
+    @patch("sonnet_graph.context.dispose_graphdb_pool")
+    async def test_shutdown_is_idempotent(self, mock_dispose):
+        """Calling on_shutdown twice must not double-dispose."""
+        ext = GraphDBExtension()
+        ext._active = True
+        await ext.on_shutdown()
+        await ext.on_shutdown()
+        mock_dispose.assert_called_once()