Metadata-Version: 2.4
Name: sonnet-graph
Version: 0.1.1
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.12
Requires-Dist: cypher-graphdb>=0.2.8
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`) |
