Graph
NodeType
Bases: str, Enum
Enumeration of node types in the knowledge graph.
Currently supported node types are: UNKNOWN, DOCUMENT, CHUNK
Node
Bases: BaseModel
Represents a node in the knowledge graph.
Attributes:
| Name | Type | Description |
|---|---|---|
id |
UUID
|
Unique identifier for the node. |
properties |
dict
|
Dictionary of properties associated with the node. |
type |
NodeType
|
Type of the node. |
add_property
Adds a property to the node.
Raises:
| Type | Description |
|---|---|
ValueError
|
If the property already exists. |
Source code in src/ragas/testset/graph.py
get_property
Retrieves a property value by key.
Notes
The key is case-insensitive.
Relationship
Bases: BaseModel
Represents a relationship between two nodes in a knowledge graph.
Attributes:
| Name | Type | Description |
|---|---|---|
id |
(UUID, optional)
|
Unique identifier for the relationship. Defaults to a new UUID. |
type |
str
|
The type of the relationship. |
source |
Node
|
The source node of the relationship. |
target |
Node
|
The target node of the relationship. |
bidirectional |
(bool, optional)
|
Whether the relationship is bidirectional. Defaults to False. |
properties |
(dict, optional)
|
Dictionary of properties associated with the relationship. Defaults to an empty dict. |
get_property
KnowledgeGraph
dataclass
KnowledgeGraph(
nodes: List[Node] = list(),
relationships: List[Relationship] = list(),
)
Represents a knowledge graph containing nodes and relationships.
Attributes:
| Name | Type | Description |
|---|---|---|
nodes |
List[Node]
|
List of nodes in the knowledge graph. |
relationships |
List[Relationship]
|
List of relationships in the knowledge graph. |
add
add(item: Union[Node, Relationship])
Adds a node or relationship to the knowledge graph.
Raises:
| Type | Description |
|---|---|
ValueError
|
If the item type is not Node or Relationship. |
Source code in src/ragas/testset/graph.py
save
Saves the knowledge graph to a JSON file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
Union[str, Path]
|
Path where the JSON file should be saved. |
required |
Notes
The file is saved using UTF-8 encoding to ensure proper handling of Unicode characters across different platforms.
Source code in src/ragas/testset/graph.py
load
classmethod
load(path: Union[str, Path]) -> KnowledgeGraph
Loads a knowledge graph from a path.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
Union[str, Path]
|
Path to the JSON file containing the knowledge graph. |
required |
Returns:
| Type | Description |
|---|---|
KnowledgeGraph
|
The loaded knowledge graph. |
Notes
The file is read using UTF-8 encoding to ensure proper handling of Unicode characters across different platforms.
Source code in src/ragas/testset/graph.py
get_node_by_id
get_node_by_id(node_id: Union[UUID, str]) -> Optional[Node]
Retrieves a node by its ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
node_id
|
UUID
|
The ID of the node to retrieve. |
required |
Returns:
| Type | Description |
|---|---|
Node or None
|
The node with the specified ID, or None if not found. |
Source code in src/ragas/testset/graph.py
remove_node
remove_node(
node: Node, inplace: bool = True
) -> Optional[KnowledgeGraph]
Removes a node and its associated relationships from the knowledge graph.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
node
|
Node
|
The node to be removed from the knowledge graph. |
required |
inplace
|
bool
|
If True, modifies the knowledge graph in place. If False, returns a modified copy with the node removed. |
True
|
Returns:
| Type | Description |
|---|---|
KnowledgeGraph or None
|
Returns a modified copy of the knowledge graph if |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the node is not present in the knowledge graph. |
Source code in src/ragas/testset/graph.py
get_child_nodes
get_child_nodes(
node: Node, graph: KnowledgeGraph, level: int = 1
) -> List[Node]
Get the child nodes of a given node up to a specified level.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
node
|
Node
|
The node to get the children of. |
required |
graph
|
KnowledgeGraph
|
The knowledge graph containing the node. |
required |
level
|
int
|
The maximum level to which child nodes are searched. |
1
|
Returns:
| Type | Description |
|---|---|
List[Node]
|
The list of child nodes up to the specified level. |
Source code in src/ragas/testset/graph_queries.py
get_parent_nodes
get_parent_nodes(
node: Node, graph: KnowledgeGraph, level: int = 1
) -> List[Node]
Get the parent nodes of a given node up to a specified level.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
node
|
Node
|
The node to get the parents of. |
required |
graph
|
KnowledgeGraph
|
The knowledge graph containing the node. |
required |
level
|
int
|
The maximum level to which parent nodes are searched. |
1
|
Returns:
| Type | Description |
|---|---|
List[Node]
|
The list of parent nodes up to the specified level. |
Source code in src/ragas/testset/graph_queries.py
find_n_indirect_clusters
find_n_indirect_clusters(
graph: KnowledgeGraph,
n: int,
relationship_condition: Callable[
[Relationship], bool
] = lambda _: True,
depth_limit: int = 3,
) -> List[Set[Node]]
Return n indirect clusters of nodes in the knowledge graph based on a relationship condition. Optimized for large datasets by using an adjacency index for lookups and limiting path exploration relative to n.
A cluster represents a path through the graph. For example, if A -> B -> C -> D exists in the graph, then {A, B, C, D} forms a cluster. If there's also a path A -> B -> C -> E, it forms a separate cluster.
The method returns a list of up to n sets, where each set contains nodes forming a complete path from a starting node to a leaf node or a path segment up to depth_limit nodes long. The result may contain fewer than n clusters if the graph is very sparse or if there aren't enough nodes to form n distinct clusters.
To maximize diversity in the results: 1. Random starting nodes are selected 2. Paths from each starting node are grouped 3. Clusters are selected in round-robin fashion from each group until n unique clusters are found 4. Duplicate clusters are eliminated 5. When a superset cluster is found (e.g., {A,B,C,D}), any existing subset clusters (e.g., {A,B,C}) are removed to avoid redundancy
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
graph
|
KnowledgeGraph
|
The knowledge graph to search. |
required |
n
|
int
|
Target number of clusters to return. Must be at least 1. Should return n clusters unless the graph is extremely sparse. |
required |
relationship_condition
|
Callable[[Relationship], bool]
|
A function that takes a Relationship and returns a boolean, by default lambda _: True |
lambda _: True
|
depth_limit
|
int
|
Maximum depth for path exploration, by default 3. Must be at least 2 to form clusters by definition. |
3
|
Returns:
| Type | Description |
|---|---|
List[Set[Node]]
|
A list of sets, where each set contains nodes that form a cluster. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If depth_limit < 2, n < 1, or no relationships match the provided condition. |
Source code in src/ragas/testset/graph_queries.py
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 | |
find_two_nodes_single_rel
find_two_nodes_single_rel(
graph: KnowledgeGraph,
relationship_condition: Callable[
[Relationship], bool
] = lambda _: True,
) -> List[Tuple[Node, Relationship, Node]]
Finds nodes in the knowledge graph based on a relationship condition. (NodeA, NodeB, Rel) triples are considered as multi-hop nodes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
graph
|
KnowledgeGraph
|
The knowledge graph to search. |
required |
relationship_condition
|
Callable[[Relationship], bool]
|
A function that takes a Relationship and returns a boolean, by default lambda _: True |
lambda _: True
|
Returns:
| Type | Description |
|---|---|
List[Set[Node, Relationship, Node]]
|
A list of sets, where each set contains two nodes and a relationship forming a multi-hop node. |