Graph (lexigram-graph)

Graph database support for the Lexigram Framework (Neo4j, in-memory).

Overview

lexigram-graph provides graph storage backends with DI wiring for in-memory and Neo4j implementations behind the graph contracts. It supports node and edge creation, graph traversal queries, Cypher compilation for Neo4j, and lazy graph creation with lifecycle events.

Install

uv add lexigram-graph
# With Neo4j support
uv add "lexigram-graph[neo4j]"

Quick Start

from lexigram import Application
from lexigram.di.module import Module, module
from lexigram.graph import GraphConfig, GraphModule
from lexigram.contracts.data.graph import GraphStoreProtocol, TraversalQuery, StartSpec, TraversalStep


@module(imports=[GraphModule.configure(GraphConfig(backend="memory"))])
class AppModule(Module):
    pass


async def main() -> None:
    async with Application.boot(modules=[AppModule]) as app:
        store = await app.container.resolve(GraphStoreProtocol)
        graph = await store.get_graph()

        await graph.create_node(["Person"], {"name": "Alice"}, node_id="alice")
        await graph.create_node(["Person"], {"name": "Bob"}, node_id="bob")
        await graph.create_edge("alice", "bob", "KNOWS")

        paths = await graph.traverse(
            TraversalQuery(
                start=StartSpec(node_ids=("alice",)),
                steps=(TraversalStep(edge_types=("KNOWS",)),),
            )
        )
        assert paths


if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

Configuration

Zero-config usage: Call GraphModule.configure() with no arguments to use all defaults (in-memory backend).

Option 1 — YAML file

graph:
  enabled: true
  backend: neo4j
  default_traversal_max_depth: 10
  neo4j:
    uri: bolt://localhost:7687
    password: "${NEO4J_PASSWORD}"

Option 2 — Profiles + Environment Variables (recommended)

export LEX_GRAPH__BACKEND=neo4j
export LEX_GRAPH__NEO4J__URI=bolt://localhost:7687

Option 3 — Python

from lexigram.graph import GraphConfig, GraphModule
from lexigram.graph.config import Neo4jConfig

GraphModule.configure(
    GraphConfig(
        backend="neo4j",
        neo4j=Neo4jConfig(
            uri="bolt://localhost:7687",
            password="${NEO4J_PASSWORD}",
        ),
    )
)

Config reference

Field	Default	Env var	Description
`enabled`	`true`	`LEX_GRAPH__ENABLED`	Enable or disable the graph subsystem
`backend`	`memory`	`LEX_GRAPH__BACKEND`	Graph backend to use (`memory` or `neo4j`)
`default_traversal_max_depth`	`10`	`LEX_GRAPH__DEFAULT_TRAVERSAL_MAX_DEPTH`	Maximum depth for graph traversals
`default_query_limit`	`100`	`LEX_GRAPH__DEFAULT_QUERY_LIMIT`	Default result limit for graph queries
`bulk_batch_size`	`1000`	`LEX_GRAPH__BULK_BATCH_SIZE`	Batch size for bulk insert and update operations
`max_retries`	`3`	`LEX_GRAPH__MAX_RETRIES`	Retry attempts on transient graph errors
`retry_delay`	`1.0`	`LEX_GRAPH__RETRY_DELAY`	Seconds between retry attempts
`neo4j.uri`	`bolt://localhost:7687`	`LEX_GRAPH__NEO4J__URI`	Neo4j Bolt connection URI
`neo4j.username`	`neo4j`	`LEX_GRAPH__NEO4J__USERNAME`	Neo4j authentication username
`neo4j.password`	—	`LEX_GRAPH__NEO4J__PASSWORD`	Neo4j authentication password (required for production)
`neo4j.database`	`neo4j`	`LEX_GRAPH__NEO4J__DATABASE`	Target Neo4j database name
`neo4j.max_connection_pool_size`	`100`	`LEX_GRAPH__NEO4J__MAX_CONNECTION_POOL_SIZE`	Maximum driver connection pool size
`memory.max_nodes`	`1000000`	`LEX_GRAPH__MEMORY__MAX_NODES`	Node capacity for the in-memory backend

Module Factory Methods

Method	Description
`GraphModule.configure(config=None)`	Register `GraphProvider` with a config
`GraphModule.stub(config=None)`	Lightweight test module with in-memory backend

Key Features

In-memory backend — no external service needed; for development and tests
Neo4j backend — async Neo4j driver with Cypher query compilation
Graph traversal — TraversalQuery, StartSpec, TraversalStep for graph walks
Named graphs — lazy graph creation per name with lifecycle events
Connection pooling — configurable pool size for Neo4j driver

Testing

async with Application.boot(modules=[GraphModule.stub()]) as app:
    store = await app.container.resolve(GraphStoreProtocol)
    graph = await store.get_graph()
    # Test with in-memory backend

Key Source Files

File	What it contains
`src/lexigram/graph/module.py`	`GraphModule.configure()`, `.stub()`
`src/lexigram/graph/config.py`	`GraphConfig`, `Neo4jConfig`
`src/lexigram/graph/di/provider.py`	`GraphProvider` boot and registration
`src/lexigram/graph/backends/memory/backend.py`	`InMemoryGraphStore` implementation
`src/lexigram/graph/backends/neo4j/backend.py`	`Neo4jGraphStore` implementation
`src/lexigram/graph/backends/neo4j/cypher.py`	`CypherCompiler`