Agentic graph capability
Base class definition for agentic graph exploration operations.
This module defines BaseAgenticGraphCapability that graph datastores supporting agentic workflows should implement. It provides read-only, context-aware exploration methods adapted from GRASP (Graph Retrieval-Augmented Search Pattern).
BaseAgenticGraphCapability
Bases: ABC
Base class for agentic graph exploration operations.
Provides read-only, context-aware graph exploration methods for AI agents. All methods enforce read-only access to prevent unintended graph mutations.
This capability is designed to be composed via multiple inheritance alongside
:class:~gllm_datastore.core.capabilities.graph_capability.BaseGraphCapability:
.. code-block:: python
class Neo4jGraphCapability(BaseGraphCapability, BaseAgenticGraphCapability):
...
This allows consumers to type-hint against either capability independently:
.. code-block:: python
def ingest(graph: BaseGraphCapability): ... # CRUD only
def explore(graph: BaseAgenticGraphCapability): ... # exploration only
get_neighborhood(node_id=None, relationship_type=None, target_node_id=None, limit=10)
abstractmethod
async
Get graph patterns matching partial constraints.
Provide at least one of: node_id, relationship_type, or
target_node_id. Returns up to limit diverse patterns to help
understand the graph structure.
Differs from traverse_graph() in that it discovers patterns matching
given constraints without requiring a specific traversal path or starting
point.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
node_id
|
str | None
|
Source node ID to filter by. Defaults to None. |
None
|
relationship_type
|
str | None
|
Relationship type to filter by. Defaults to None. |
None
|
target_node_id
|
str | None
|
Target node ID to filter by. Defaults to None. |
None
|
limit
|
int
|
Maximum number of patterns to return. Defaults to 10. |
10
|
Returns:
| Type | Description |
|---|---|
list[Triplet]
|
list[Triplet]: List of source-relationship-target triplets matching the constraints. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If none of |
NotImplementedError
|
This is an abstract method that must be implemented by subclasses. |
search_autocomplete(query, query_pattern, search_var, limit=10)
abstractmethod
async
Context-sensitive search constrained by a partial query pattern.
Executes a partial query pattern and searches for nodes that can be bound
to search_var. The pattern provides context for the search.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
query
|
str
|
Search query string. |
required |
query_pattern
|
str
|
Partial query with a variable placeholder. |
required |
search_var
|
str
|
Variable name to search for (e.g., |
required |
limit
|
int
|
Maximum number of results to return. Defaults to 10. |
10
|
Returns:
| Type | Description |
|---|---|
list[Node]
|
list[Node]: List of nodes matching the query within the pattern context. |
Raises:
| Type | Description |
|---|---|
NotImplementedError
|
This is an abstract method that must be implemented by subclasses. |
search_constrained(query, position, source_node_id=None, relationship_type=None, target_node_id=None, limit=10)
abstractmethod
async
Search for items in a specific pattern position under constraints.
Builds a graph pattern with the given constraints and searches for items in the specified position (source, relationship, or target).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
query
|
str
|
Search query string. |
required |
position
|
SearchPosition
|
What to search for: SOURCE, RELATIONSHIP, or TARGET. |
required |
source_node_id
|
str | None
|
Constraint on the source node. Defaults to None. |
None
|
relationship_type
|
str | None
|
Constraint on the relationship type. Defaults to None. |
None
|
target_node_id
|
str | None
|
Constraint on the target node. Defaults to None. |
None
|
limit
|
int
|
Maximum number of results to return. Defaults to 10. |
10
|
Returns:
| Type | Description |
|---|---|
list[Node] | list[Triplet]
|
list[Node] | list[Triplet]: Nodes when |
Raises:
| Type | Description |
|---|---|
NotImplementedError
|
This is an abstract method that must be implemented by subclasses. |
search_node(query, node_label=None, limit=10)
abstractmethod
async
Search for nodes using case-insensitive substring matching.
Searches across common properties: id, name, title,
description.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
query
|
str
|
Search query string. |
required |
node_label
|
str | None
|
Optional node label to filter results. Defaults to None. |
None
|
limit
|
int
|
Maximum number of results to return. Defaults to 10. |
10
|
Returns:
| Type | Description |
|---|---|
list[Node]
|
list[Node]: List of matching nodes. |
Raises:
| Type | Description |
|---|---|
NotImplementedError
|
This is an abstract method that must be implemented by subclasses. |
search_rel_of_node(query, node_id, direction=RelationshipDirection.BOTH, limit=10)
abstractmethod
async
Search for relationship types connected to a specific node.
More context-sensitive than :meth:search_relationship — only returns
relationships that connect to the given node.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
query
|
str
|
Search query string. |
required |
node_id
|
str
|
Node ID to search relationships for. |
required |
direction
|
RelationshipDirection
|
Direction to search.
Defaults to :attr: |
BOTH
|
limit
|
int
|
Maximum number of results to return. Defaults to 10. |
10
|
Returns:
| Type | Description |
|---|---|
list[Triplet]
|
list[Triplet]: List of triplets for relationships connected to the node. |
Raises:
| Type | Description |
|---|---|
NotImplementedError
|
This is an abstract method that must be implemented by subclasses. |
search_relationship(query, node_label=None, limit=10)
abstractmethod
async
Search for relationship types using substring matching.
Returns relationship types that exist in the graph with usage counts. Helps agents avoid hallucinating relationship type names.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
query
|
str
|
Search query string. |
required |
node_label
|
str | None
|
Optional node label to filter relationships. Defaults to None. |
None
|
limit
|
int
|
Maximum number of results to return. Defaults to 10. |
10
|
Returns:
| Type | Description |
|---|---|
list[Triplet]
|
list[Triplet]: List of triplets representing relationship types found in the graph. |
Raises:
| Type | Description |
|---|---|
NotImplementedError
|
This is an abstract method that must be implemented by subclasses. |
search_target_of_rel(query, relationship_type, source_node_id=None, limit=10)
abstractmethod
async
Search for target nodes reachable via a relationship type.
If source_node_id is provided, finds targets reachable only from
that node. Otherwise finds all nodes reachable via the relationship type.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
query
|
str
|
Search query string. |
required |
relationship_type
|
str
|
Relationship type to traverse. |
required |
source_node_id
|
str | None
|
Optional source node to start from. Defaults to None. |
None
|
limit
|
int
|
Maximum number of results to return. Defaults to 10. |
10
|
Returns:
| Type | Description |
|---|---|
list[Node]
|
list[Node]: List of target nodes matching the query. |
Raises:
| Type | Description |
|---|---|
NotImplementedError
|
This is an abstract method that must be implemented by subclasses. |
RelationshipDirection
Bases: StrEnum
Direction for relationship traversal.
SearchPosition
Bases: StrEnum
Position in a graph pattern for constrained search.