API Documentation

ISONGraph(name: str = "graph", directed: bool = True)

NodeRef = Tuple[str, Any]  # e.g., ('person', 1), ('company', 'acme')

@dataclass
class Node:
    type: str           # Node type (e.g., 'person', 'product')
    id: Any             # Unique ID within type
    properties: Dict    # Key-value properties

@dataclass
class Edge:
    rel_type: str       # Relationship type (e.g., 'KNOWS', 'PURCHASED')
    source: NodeRef     # Source node reference
    target: NodeRef     # Target node reference
    properties: Dict    # Key-value properties

@dataclass
class Path:
    nodes: List[NodeRef]  # Nodes in order
    edges: List[Edge]     # Edges connecting nodes
    length: int           # Number of edges
    start: NodeRef        # First node
    end: NodeRef          # Last node

class Direction(Enum):
    OUT = "out"    # Outgoing edges (default)
    IN = "in"      # Incoming edges
    BOTH = "both"  # Both directions

add_node(type: str, id: Any, **properties) -> Node

graph.add_node('person', 1, name='Alice', age=30)
graph.add_node('company', 'acme', name='ACME Corp', employees=500)

get_node(type: str, id: Any) -> Optional[Node]

node = graph.get_node('person', 1)
if node:
    print(node.properties['name'])  # 'Alice'

has_node(type: str, id: Any) -> bool

update_node(type: str, id: Any, **properties) -> Optional[Node]

remove_node(type: str, id: Any) -> bool

nodes(type: Optional[str] = None) -> Iterator[Node]

# All nodes
for node in graph.nodes():
    print(node)

# Only person nodes
for person in graph.nodes('person'):
    print(person.properties['name'])

add_edge(rel_type: str, source: NodeRef, target: NodeRef, **properties) -> Edge

graph.add_edge('KNOWS', ('person', 1), ('person', 2), since=2020)
graph.add_edge('WORKS_AT', ('person', 1), ('company', 'acme'), role='Engineer')

neighbors(
    node: NodeRef,
    rel_type: Optional[str] = None,
    direction: Direction = Direction.OUT
) -> List[NodeRef]

# People Alice knows
friends = graph.neighbors(('person', 1), 'KNOWS')

# People who know Alice
followers = graph.neighbors(('person', 1), 'KNOWS', Direction.IN)

# All connections (any relationship)
all_neighbors = graph.neighbors(('person', 1), direction=Direction.BOTH)

multi_hop(
    start: NodeRef,
    rel_type: str,
    hops: int,
    direction: Direction = Direction.OUT
) -> List[NodeRef]

# Friends of friends
fof = graph.multi_hop(('person', 1), 'KNOWS', hops=2)

# 3 hops away
distant = graph.multi_hop(('person', 1), 'KNOWS', hops=3)

graph.start(node_ref)
    .hop(rel_type, direction, where)  # Single hop
    .hops(n, rel_type, direction)     # N hops
    .filter(predicate_fn)             # Filter nodes
    .collect()                        # -> List[NodeRef]
    .collect_nodes()                  # -> List[Node]
    .count()                          # -> int
    .first()                          # -> Optional[NodeRef]

# Complex traversal example
results = graph.start(('person', 1)) \
    .hop('KNOWS') \
    .hop('WORKS_AT') \
    .filter(lambda n: n.properties.get('employees', 0) > 100) \
    .collect_nodes()

for company in results:
    print(company.properties['name'])

shortest_path(
    start: NodeRef,
    end: NodeRef,
    rel_type: Optional[str] = None,
    max_hops: int = 10
) -> Optional[Path]

path = graph.shortest_path(('person', 1), ('person', 5))
if path:
    print(f"Length: {path.length}")
    print(f"Nodes: {path.nodes}")

all_paths(
    start: NodeRef,
    end: NodeRef,
    rel_type: Optional[str] = None,
    max_hops: int = 10
) -> List[Path]

# Incoming edges count
in_deg = graph.in_degree(('person', 1))

# Outgoing edges count
out_deg = graph.out_degree(('person', 1))

# Total degree
total = graph.degree(('person', 1))

is_connected() -> bool

has_cycle(rel_type: Optional[str] = None) -> bool

# Check for cycles in KNOWS relationships
if graph.has_cycle('KNOWS'):
    print("Circular friendships detected!")

# Check entire graph
if graph.has_cycle():
    print("Graph contains cycles")