sonnet-graph 0.1.0__py3-none-any.whl

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/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/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/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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+sonnet_graph/__init__.py,sha256=fFQOGmLtKebF3gcrw3NmAk_KvCWXNWWcjb5HmgmrIdE,1634
+sonnet_graph/context.py,sha256=bpohxZZeU-Hw_crxty-GeFiC6uNXFkcKHOXe5d9F9lo,5263
+sonnet_graph/dependencies.py,sha256=9Cbse8q9Wwcy06sHpgCgM_GBQG3hpsAwMTjoy5NuNVE,1639
+sonnet_graph/extension.py,sha256=zxONLgP2Dg0h1RqtM0HWgzic9vL2ph6cRIk8dO21g90,2466
+sonnet_graph/checks/__init__.py,sha256=YjS-WiUifxxmznb6hjclpT3uVoelUhgYwH8zLMngIQ4,449
+sonnet_graph/checks/graphdb_health_check.py,sha256=4O1QPpOkEmvZtWzdea-4nEF1MeQwWyJUwSN6rueLyI4,1468
+sonnet_graph/checks/graphdb_initialization.py,sha256=45-sX3cMBqgWfbwU0l1rPtirxjFD6_CA6NALhDReWs8,1224
+sonnet_graph/checks/stages.py,sha256=pZbMcGKr-0vwSQQcK_F_pdPCD5Mo3y4aJC8rF_Gtl4I,471
+sonnet_graph-0.1.0.dist-info/METADATA,sha256=nsyTdsVRsimmuw1bT1y0dfxqVfJxU3UWbnfPF_52AAM,2561
+sonnet_graph-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sonnet_graph-0.1.0.dist-info/top_level.txt,sha256=HCrJGvnLfVHPBz2E9t6WM-QHMQTDOeE1QjH1k-XZtiU,13
+sonnet_graph-0.1.0.dist-info/RECORD,,

sonnet_graph-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sonnet_graph-0.1.0.dist-info/top_level.txt

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