Metadata-Version: 2.4
Name: sonnet-graph
Version: 0.3.2
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-core>=0.1.0
Requires-Dist: sonnet-server>=0.4.0
Requires-Dist: cypher-graphdb>=0.5.0
Requires-Dist: loguru>=0.7.3
Requires-Dist: jinja2>=3.1.6
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"
Requires-Dist: testcontainers[postgres]>=4.0.0; extra == "dev"

# sonnet-graph

Cypher graph database access for sonnet-server applications. It is the seam
between the driver and a running process: pooling, lifecycle, readiness and
in-graph metadata.

Version 0.3.1. It wraps `cypher-graphdb>=0.5.0` and does not re-abstract it --
query building, result parsing, bulk loading, indexes and the differences
between the two backends all stay in the driver. The backends are Apache AGE
(on PostgreSQL) and Memgraph.

## What it provides

- **`GraphDBExtension`** -- pool lifecycle bound to the sonnet-server
  application lifecycle, with an optional mode for services where the graph is
  not required.
- **Pools** -- named pools as the addressing scheme, `borrow_graphdb()` as the
  entry point and `get_current_graphdb()` for the ambient connection. Managed
  mode adds lazy creation and idle reaping when the set of graphs is
  open-ended.
- **Readiness and status** -- `GraphdbStage` initialization and health checks
  on the sonnet-core readiness pipeline, plus pool snapshots for operations.
- **FastAPI dependencies** -- `get_graphdb()` and `get_graphdb_session()` for
  router-level ambient connections.
- **Typed results** -- per-pool model providers so query results come back as
  your own Pydantic classes.
- **Graph metadata** -- stores that keep a graph's schema, documentation and
  named queries as nodes inside the graph itself.

It defines no SQLModel tables and ships no migrations.

## Install

```bash
uv add sonnet-graph
```

Depends on [`sonnet-core`](../sonnet-core/README.md),
[`sonnet-server`](../sonnet-server/README.md), `cypher-graphdb`, loguru and
jinja2. The backend drivers arrive with `cypher-graphdb`, so there is no
per-backend extra. The only extra is `dev`.

## Usage

Register the extension once, then borrow a connection from anywhere in the
process.

```python
from sonnet_graph import GraphDBExtension, borrow_graphdb

registry = create_extension_registry(
    DatabaseExtension(),
    GraphDBExtension(),
)

with borrow_graphdb() as cdb:
    result = cdb.execute("MATCH (n:Product) RETURN n LIMIT 10")
```

`GraphDBExtension(optional=True)` skips startup instead of raising when the
graph is unconfigured.

## Configuration

The connection is configured through `cypher-graphdb`'s own `CGDB_`
environment variables rather than being 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 the graph, AGE only (default: `false`) |

## Documentation

- **Usage** -- [`docs/usage/index.md`](docs/usage/index.md)
- **Design** -- [`docs/design/index.md`](docs/design/index.md)
- **Workspace** -- [`../../docs/README.md`](../../docs/README.md)

## License

Apache 2.0 -- see [LICENSE.md](../../LICENSE.md).
