Getting Started

# Core library (includes Graphantic schema validation)
pip install ison-graph

# Using npm (includes Graphantic schema validation)
npm install ison-graph-ts

# Using yarn
yarn add ison-graph-ts

[dependencies]
# Includes Graphantic schema validation
ison-graph-rs = "1.0"

cargo add ison-graph-rs

# Download the header
curl -O https://raw.githubusercontent.com/maheshvaikri-code/ison/main/isongraph/ison-graph-cpp/include/ison_graph.hpp

# Include in your project
#include "ison_graph.hpp"

find_package(ison-graph-cpp REQUIRED)
target_link_libraries(your_target ison-graph-cpp::ison-graph-cpp)

from ison_graph import ISONGraph, Direction

# Create a new graph
graph = ISONGraph(name='social')

# Add nodes with properties
graph.add_node('person', 1, name='Alice', age=30, city='NYC')
graph.add_node('person', 2, name='Bob', age=25, city='LA')
graph.add_node('person', 3, name='Carol', age=28, city='Chicago')
graph.add_node('company', 100, name='TechCorp', employees=500)

# Add edges (relationships)
graph.add_edge('KNOWS', ('person', 1), ('person', 2), since=2020)
graph.add_edge('KNOWS', ('person', 2), ('person', 3), since=2021)
graph.add_edge('WORKS_AT', ('person', 1), ('company', 100), role='Engineer')

# Query neighbors
friends = graph.neighbors(('person', 1), 'KNOWS')
print(f"Alice knows: {friends}")
# Output: Alice knows: [('person', 2)]

# Multi-hop traversal (friends of friends)
fof = graph.multi_hop(('person', 1), 'KNOWS', hops=2)
print(f"Friends of friends: {fof}")
# Output: Friends of friends: [('person', 3)]

# Find shortest path
path = graph.shortest_path(('person', 1), ('person', 3))
print(f"Path: {path}")
# Output: Path: person:1 -> person:2 -> person:3

# Serialize to ISON format (token-efficient)
print(graph.to_ison())

nodes.person
id  name    age  city
1   Alice   30   NYC
2   Bob     25   LA
3   Carol   28   Chicago

nodes.company
id   name      employees
100  TechCorp  500

edges.KNOWS
source      target      since
:person:1   :person:2   2020
:person:2   :person:3   2021

edges.WORKS_AT
source      target        role
:person:1   :company:100  Engineer

# Basic node
graph.add_node('user', 'alice')

# Node with properties
graph.add_node('user', 'bob', name='Bob Smith', age=25, active=True)

# Properties can be any JSON-serializable type
graph.add_node('product', 'p123',
    name='Widget',
    price=29.99,
    tags=['electronics', 'gadgets'],
    metadata={'sku': 'WDG-123'}
)

# Get a node
node = graph.get_node('user', 'alice')
print(node.properties)  # {'name': 'Bob Smith', 'age': 25}

# Update properties
graph.update_node('user', 'bob', age=26, title='Engineer')

# Check if node exists
if graph.has_node('user', 'alice'):
    print("Node exists!")

# Basic edge
graph.add_edge('FOLLOWS', ('user', 'alice'), ('user', 'bob'))

# Edge with properties
graph.add_edge('PURCHASED', ('user', 'alice'), ('product', 'p123'),
    quantity=2,
    date='2024-01-15',
    total=59.98
)

# Get an edge
edge = graph.get_edge('FOLLOWS', ('user', 'alice'), ('user', 'bob'))
print(edge.properties)

# Check if edge exists
if graph.has_edge('FOLLOWS', ('user', 'alice'), ('user', 'bob')):
    print("Edge exists!")

from ison_graph import Direction

# Get immediate neighbors
neighbors = graph.neighbors(('user', 'alice'), 'FOLLOWS')

# Direction: OUT (default), IN, or BOTH
followers = graph.neighbors(('user', 'bob'), 'FOLLOWS', Direction.IN)

# Multi-hop traversal
two_hops = graph.multi_hop(('user', 'alice'), 'FOLLOWS', hops=2)

# Range traversal (1-3 hops)
range_results = graph.multi_hop_range(('user', 'alice'), 'FOLLOWS', min_hops=1, max_hops=3)

# Fluent API for complex traversals
results = graph.start(('user', 'alice')) \
    .hop('FOLLOWS') \
    .hop('PURCHASED') \
    .filter(lambda n: n.properties.get('price', 0) > 20) \
    .collect()

# Find shortest path
path = graph.shortest_path(('user', 'alice'), ('user', 'charlie'))

# Find all paths (up to max_hops)
all_paths = graph.all_paths(('user', 'alice'), ('user', 'charlie'), max_hops=5)

# Serialize to ISON format (token-efficient)
ison_text = graph.to_ison()

# Parse from ISON
graph2 = ISONGraph.from_ison(ison_text)

# ISONL format (streaming, line-based)
isonl_text = graph.to_isonl()

# Save to file
graph.save('my_graph.ison')

# Load from file
loaded = ISONGraph.load('my_graph.ison')

# JSON export (for compatibility)
json_data = graph.to_dict()

# JSON import
graph3 = ISONGraph.from_dict(json_data)