SDK Reference

pip install substr8-langgraph

from langgraph.graph import StateGraph
from substr8_langgraph import instrument_graph
 
# Build and compile your graph
graph = StateGraph(MyState)
# ... add nodes and edges ...
compiled = graph.compile()
 
# Wrap with instrumentation
instrumented = instrument_graph(
    compiled,
    agent_id="my-agent",
    project="my-project",
)
 
# Invoke
result = instrumented.invoke({"input": "..."})

from langgraph.graph import StateGraph, END
from typing import TypedDict
from substr8_langgraph import instrument_graph
import json
 
class MyState(TypedDict):
    query: str
    result: str
 
def process(state):
    return {"result": f"Processed: {state['query']}"}
 
# Build graph
graph = StateGraph(MyState)
graph.add_node("process", process)
graph.set_entry_point("process")
graph.add_edge("process", END)
compiled = graph.compile()
 
# Instrument
instrumented = instrument_graph(compiled, agent_id="example", project="demo")
 
# Run
result = instrumented.invoke({"query": "Hello"})
 
# Save proof
with open("runproof.json", "w") as f:
    json.dump(result["proof"].model_dump(mode="json"), f, indent=2)
 
print(f"Run ID: {result['run_id']}")
print(f"Status: {result['proof_status']}")

pip install substr8-core

from substr8_core import RunProof
 
# Load from file
import json
with open("runproof.json") as f:
    data = json.load(f)
 
proof = RunProof.model_validate(data)
 
print(proof.header.proof_id)
print(proof.header.agent_id)
print(len(proof.trace))

from substr8_core import verify_runproof
 
result = verify_runproof(proof_dict)
 
if result.valid:
    print("✓ Proof is valid")
else:
    print(f"✗ Invalid: {result.errors}")

class VerificationResult:
    valid: bool
    errors: list[str]
    checks: dict[str, bool]  # Individual check results

from substr8_core import RunState, RunStatus
 
state = RunState(agent_id="my-agent", project="my-project")
 
# Start
state.start()
 
# Add events
state.add_event("tool_called", {"tool": "search", "query": "..."})
state.add_event("tool_result", {"result": "..."})
 
# End
state.end(RunStatus.COMPLETED, outputs={"answer": "..."})
 
# Build proof
proof = state.build_proof()

from substr8.runproof.v2 import verify as verify_cli
import json
 
with open("runproof.json") as f:
    proof = json.load(f)
 
result = verify_cli(proof)
print(f"Valid: {result.valid}")

class TraceEvent(BaseModel):
    type: str
    timestamp: datetime
    entry_hash: str
    prev_hash: str | None
    # ... event-specific fields

class Commitments(BaseModel):
    event_root: str      # Merkle root
    proof_hash: str      # Hash of proof
    signature: Signature

class Signature(BaseModel):
    algorithm: str       # "ed25519"
    public_key: str      # Public key
    value: str           # Signature bytes