Graph

Neo4j implementation of BaseGraphCapability.

This module ports the Cypher-based graph operations from the legacy gllm_datastore.graph_data_store.neo4j_graph_data_store.Neo4jGraphDataStore onto the new capability interface. The capability is driver-bound (driver and database are injected by :class:Neo4jDataStore) and shares its retry policy.

Neo4jGraphCapability(driver, database=None, retry_config=None)

Bases: BaseGraphCapability

Neo4j implementation of :class:BaseGraphCapability.

The capability does not own the driver lifecycle; it borrows the driver from the parent :class:Neo4jDataStore and opens sessions on demand. All write and read operations route through :meth:retrieve, which wraps execution in a retry policy and binds the session to the configured database.

Agentic exploration methods are available via the :attr:agent sub-capability, which is an instance of :class:~gllm_datastore.data_store.neo4j.agentic_graph.Neo4jAgenticGraphCapability.

Attributes:

Name	Type	Description
driver	AsyncDriver	The Neo4j async driver shared with the data store.
database	str	Name of the Neo4j database to bind sessions to. Defaults to "neo4j".
retry_config	RetryConfig | None	Retry policy applied around every query execution. When None, queries are executed without retries.

Initialize the capability.

Parameters:

Name	Type	Description	Default
driver	AsyncDriver	Neo4j async driver. Typically supplied by :class:Neo4jDataStore via with_graph().	required
database	str | None	Database to bind sessions to. When None, falls back to "neo4j" (the standard default database name). Defaults to None.	None
retry_config	RetryConfig | None	Retry policy for query operations. Defaults to None, meaning no retries.	None

agent property

Return the agentic exploration sub-capability.

Returns:

Name	Type	Description
Neo4jAgenticGraphCapability	Neo4jAgenticGraphCapability	The agentic sub-capability instance.

delete_node(label, identifier_key, identifier_value) async

Delete a node and all of its relationships.

Cypher: MATCH (n:<label> {<identifier_key>: $identifier_value}) DETACH DELETE n.

Parameters:

Name	Type	Description	Default
label	str	Node label.	required
identifier_key	str	Property name identifying the node.	required
identifier_value	str	Value of identifier_key.	required

Returns:

Name	Type	Description
bool	bool	True when at least one node was deleted; False otherwise.

delete_nodes(properties, label=None) async

Delete all nodes matching the given properties, together with their relationships.

When label is None the query matches nodes of any label (full scan unless a global property index exists in Neo4j 5.x+).

Parameters:

Name	Type	Description	Default
properties	dict[str, Any]	Property key-value pairs to match.	required
label	str | None	Node label to restrict deletion. Defaults to None.	None

Returns:

Name	Type	Description
int	int	Number of nodes deleted.

Raises:

Type	Description
ValueError	If properties is None or empty.

delete_relationship(node_source_key, node_source_value, relation, node_target_key, node_target_value) async

Delete a directed relationship between two nodes.

Parameters:

Name	Type	Description	Default
node_source_key	str	Property name identifying the source node.	required
node_source_value	str	Value of the source node's identifier.	required
relation	str	Relationship type.	required
node_target_key	str	Property name identifying the target node.	required
node_target_value	str	Value of the target node's identifier.	required

Returns:

Name	Type	Description
bool	bool	True when at least one relationship was deleted; False otherwise.

query(query, parameters=None) async

Execute a read-write Cypher query and return result rows as dicts.

Routes the statement through session.execute_write so it lands on a leader/primary instance. Use :meth:retrieve for pure reads.

Parameters:

Name	Type	Description	Default
query	str	Cypher statement that may mutate the graph.	required
parameters	dict[str, Any] | None	Bind parameters. Defaults to None.	None

Returns:

Type	Description
list[dict[str, Any]]	list[dict[str, Any]]: Result records, each as record.data().

retrieve(query, parameters=None, max_results=_RETRIEVE_DEFAULT_MAX_RESULTS, timeout=_RETRIEVE_DEFAULT_TIMEOUT) async

Execute a read-only Cypher query and return result rows as dicts.

Routes the statement through session.execute_read so the driver can send it to a read replica when one is available. Use :meth:query for statements that mutate the graph.

Parameters:

Name	Type	Description	Default
query	str	Read-only Cypher statement.	required
parameters	dict[str, Any] | None	Bind parameters. Defaults to None.	None
max_results	int	Maximum number of rows to return. Defaults to _RETRIEVE_DEFAULT_MAX_RESULTS (100).	_RETRIEVE_DEFAULT_MAX_RESULTS
timeout	int	Transaction timeout in seconds. Defaults to _RETRIEVE_DEFAULT_TIMEOUT (60).	_RETRIEVE_DEFAULT_TIMEOUT

Returns:

Type	Description
list[dict[str, Any]]	list[dict[str, Any]]: Result records, each as record.data().

traverse_graph(node_properties, extracted_node_properties=None, extracted_relationship_properties=None, depth=3) async

Traverse the graph from a node, ignoring relationship direction, up to depth.

Example

nodes, relationships = await capability.traverse_graph(
    node_properties={"name": "John Doe"},
    extracted_node_properties=["name", "age"],
    extracted_relationship_properties=["since"],
    depth=1,
)

Parameters:

Name	Type	Description	Default
node_properties	dict[str, Any]	Properties matching the starting node. Must contain at least one entry.	required
extracted_node_properties	list[str] | None	Node properties to extract during traversal. None or empty list returns all properties. Defaults to None.	None
extracted_relationship_properties	list[str] | None	Relationship properties to extract. None or empty list returns all properties. Defaults to None.	None
depth	int	Maximum traversal depth. Must be >= 1. Defaults to 3.	3

Returns:

Type	Description
tuple[list[dict[str, Any]], list[dict[str, Any]]]	tuple[list[dict[str, Any]], list[dict[str, Any]]]: (nodes, relationships) where each item is {"id": <int>, "labels": [...], "properties": {...}} for nodes and {"id": <int>, "type": <str>, "start_node": <int>, "end_node": <int>, "properties": {...}} for relationships. Both lists are deduplicated.

Raises:

Type	Description
ValueError	If node_properties is empty or depth is less than 1.

upsert_node(node=None, label=None, identifier_key=None, identifier_value=None, properties=None) async

Create or update a node in the graph.

Cypher: MERGE (n:<label> {<identifier_key>: $identifier_value}) [SET n += $properties] RETURN n.

Parameters:

Name	Type	Description	Default
node	Node | None	A Node object (preferred). When provided, the legacy arguments are ignored. Defaults to None.	None
label	str | None	The label of the node. Deprecated -- use node instead. Defaults to None.	None
identifier_key	str | None	The key of the identifier. Deprecated -- use node instead. Defaults to None.	None
identifier_value	str | None	The value of the identifier. Deprecated -- use node instead. Defaults to None.	None
properties	dict[str, Any] | None	Extra node properties. Deprecated -- use node instead. Defaults to None.	None

Returns:

Type	Description
Node | None	Node | None: The upserted node reconstructed from the database response, or None if the database returned no rows.

upsert_relationship(edge=None, node_source_key=None, node_source_value=None, relation=None, node_target_key=None, node_target_value=None, properties=None) async

Create or update a directed relationship between two existing nodes.

Cypher (abridged):

MATCH (a {<node_source_key>: $node_source_value}),
      (b {<node_target_key>: $node_target_value})
MERGE (a)-[r:<relation>]->(b)
[SET r += $properties]
RETURN type(r), properties(r), a.<key>, b.<key>

Parameters:

Name	Type	Description	Default
edge	Edge | None	An Edge object (preferred). When provided, the legacy arguments are ignored. Defaults to None.	None
node_source_key	str | None	Property name identifying the source node. Deprecated -- use edge instead. Defaults to None.	None
node_source_value	str | None	Value of the source node's identifier. Deprecated -- use edge instead. Defaults to None.	None
relation	str | None	Relationship type. Deprecated -- use edge instead. Defaults to None.	None
node_target_key	str | None	Property name identifying the target node. Deprecated -- use edge instead. Defaults to None.	None
node_target_value	str | None	Value of the target node's identifier. Deprecated -- use edge instead. Defaults to None.	None
properties	dict[str, Any] | None	Relationship properties. Deprecated -- use edge instead. Defaults to None.	None

Returns:

Type	Description
Edge | None	Edge | None: The upserted edge reconstructed from the database response, or None if the database returned no rows (e.g. either node did not exist).