Skip to main content

​
Current Status: Alpha

Core features are working and stable. API may still change before 1.0.
Hypergraph is production-ready for early adopters. The API is mostly stable, but we reserve the right to make breaking changes based on feedback before the 1.0 release.

​
What’s Working Now

​
Core Primitives

@node Decorator

Wrap functions (sync, async, generators) with automatic metadata

Graph Construction

Automatic edge inference from matching names

InputSpec

Categorize inputs as required, optional, bound, or internal

Rename API

.with_inputs(), .with_outputs(), .with_name() for adaptation
Build-time validation catches errors at graph construction with helpful messages.

​
Composition & Scaling

Hierarchical Composition

Nest graphs as nodes with .as_node()

Batch Processing

Fan out over collections with .map_over()

​
Execution

SyncRunner

Sequential execution for simple workflows

AsyncRunner

Concurrent execution with max_concurrency control

Batch Map

runner.map() with zip and product modes

​
Control Flow

@route Decorator

Conditional routing with END sentinel

@ifelse Decorator

Binary boolean routing

Cyclic Graphs

Agentic loops and multi-turn workflows

​
Human-in-the-Loop

InterruptNode

Pause execution and wait for user input

Resume

Continue with user-provided data

Auto-Resolve

Handler functions for automated input resolution

​
Caching

Opt-In Caching

@node(cache=True) per-node caching

Multiple Backends

InMemoryCache (LRU) and DiskCache (persistent)

Custom Backends

Implement CacheBackend protocol

Auto-Invalidation

Cache invalidates on code changes via definition_hash

​
Events & Observability

Event System

EventProcessor, AsyncEventProcessor, TypedEventProcessor

Rich Progress

RichProgressProcessor with hierarchical bars
Event types: RunStartEvent, RunEndEvent, NodeStartEvent, NodeEndEvent, NodeErrorEvent, RouteDecisionEvent, InterruptEvent, CacheHitEvent, StopRequestedEvent

​
Visualization

Interactive Rendering

graph.visualize() for notebooks and standalone HTML

Theme Support

Dark, light, and auto themes

Expandable Hierarchy

Expand/collapse nested graphs interactively

Type Annotations

show_types=True for debugging
Built-in React Flow — constraint-based layout, works offline, no CDN dependencies.

​
Validation

Strict Types

strict_types=True for type checking at construction

Helpful Errors

Type mismatch and route target validation with clear messages

​
Coming Soon

​
Checkpointing and Durability

State Snapshots

Save graph state after each node execution

Resume from Checkpoint

Continue from last successful node after failures

Storage Backends

Local file system, Redis, S3 support
Checkpointing will enable long-running workflows to survive crashes and restarts, with minimal performance overhead.

​
Observability Integrations

OpenTelemetry

Integration with tracing systems

Structured Logging

Per-node execution logs

Performance Metrics

Track latency, token usage, and resource consumption

​
Future Considerations

​
Distributed Execution

Daft Integration

Distributed processing for large-scale workflows

Parallel Execution

Execute across multiple machines

Auto Partitioning

Automatic data partitioning for scale
Distributed execution is a future consideration. The current focus is on making single-machine execution rock-solid.

​
Execution Trace Visualization

Trace Overlay

Overlay execution traces on graph visualization

Timing Display

Show per-node timing and bottlenecks

Value Inspection

Inspect intermediate values at each node

Error Highlighting

Visual indication of failed nodes

​
Persistence

  • State snapshots for long-running workflows
  • Version control for graph definitions
  • Migration utilities for schema changes

​
Non-Goals

Things we’re explicitly not building:

Infrastructure Orchestration

Use Prefect, Airflow, or Temporal for job scheduling

Model Serving

Use dedicated serving infrastructure like Ray Serve

Data Storage

Hypergraph orchestrates, doesn’t store

UI Framework

We’re a library, not a platform
Hypergraph focuses on graph execution and composition. For infrastructure concerns like scheduling, monitoring, and deployment, integrate with existing tools.

​
Contributing

See the GitHub repository for contribution guidelines. Areas where help is welcome:
  • Additional runner implementations
  • Storage backend integrations
  • Visualization tools and enhancements
  • Documentation improvements
  • Real-world example contributions
Early contributors have significant influence on the project’s direction. Join us in shaping the future of workflow orchestration.

Build docs developers (and LLMs) love

Get started for freeTalk to us