Introduction

A unified framework for Python workflow orchestration. DAG pipelines, agentic workflows, and everything in between.

• Unified - One framework for data pipelines and agentic AI. Same elegant code.

• Hierarchical - Graphs nest as nodes. Build big from small, tested pieces.

• Versatile - Sync, async, streaming. Branches, loops, human-in-the-loop. No limits.

• Minimal - Pure functions with named outputs. Edges inferred automatically.

Quick Start

Define functions. Name their outputs. Hypergraph connects them automatically.

from hypergraph import Graph, node, SyncRunner

@node(output_name="embedding")
def embed(text: str) -> list[float]:
    # Your embedding model here
    return [0.1, 0.2, 0.3]

@node(output_name="docs")
def retrieve(embedding: list[float]) -> list[str]:
    # Your vector search here
    return ["Document 1", "Document 2"]

@node(output_name="answer")
def generate(docs: list[str], query: str) -> str:
    # Your LLM here
    return f"Based on {len(docs)} docs: answer to {query}"

# Edges inferred from matching names
graph = Graph(nodes=[embed, retrieve, generate])

# Run the graph
runner = SyncRunner()
result = runner.run(graph, {"text": "RAG tutorial", "query": "What is RAG?"})
print(result["answer"])

embed produces embedding. retrieve takes embedding. Connected automatically.

Why Hypergraph?

Pure Functions Stay Pure

# Test without the framework
def test_embed():
    result = embed.func("hello")
    assert len(result) == 768

Your functions are just functions. Test them directly, with any test framework.

Build-Time Validation

Graph([producer, consumer], strict_types=True)
# GraphConfigError: Type mismatch on edge 'producer' → 'consumer'
#   Output type: int
#   Input type:  str

Type mismatches, missing connections, invalid configurations - caught when you build the graph, not at runtime.

Hierarchical Composition

# Inner graph: RAG pipeline
rag = Graph(nodes=[embed, retrieve, generate], name="rag")

# Outer graph: full workflow
workflow = Graph(nodes=[
    validate_input,
    rag.as_node(),      # Nested graph as a node
    format_output,
])

Test pieces independently. Reuse across workflows.

Documentation

Getting Started

• What is Hypergraph? - The problem, solution, and key differentiators

• When to Use - Is hypergraph right for your use case?

• Quick Start - Get running in 5 minutes

• Comparison - How hypergraph compares to other frameworks

Core Concepts

• Getting Started - Core concepts, creating nodes, building graphs, running workflows

Patterns

• Simple Pipeline - Linear DAGs, data transformations

• Routing - Conditional routing with @ifelse and @route

• Agentic Loops - Iterative refinement, multi-turn workflows

• Hierarchical Composition - Nest graphs, Think Singular Scale with Map

• Multi-Agent - Agent teams, orchestration patterns

• Streaming - Stream LLM responses token-by-token

• Human-in-the-Loop - @interrupt decorator, pause/resume, and handler patterns

• Caching - Skip redundant computation with in-memory or disk caching

Real-World Examples

• RAG Pipeline - Single-pass retrieval-augmented generation

• Multi-Turn RAG - Conversational RAG with follow-up questions

• Evaluation Harness - Test conversation systems at scale

• Data Pipeline - Classic ETL without LLMs

• Prompt Optimization - Iterative prompt improvement with nested graphs

How-To Guides

• Batch Processing - Process multiple inputs with runner.map()

• Rename and Adapt - Reuse functions in different contexts

• Integrate with LLMs - Patterns for OpenAI, Anthropic, and others

• Test Without Framework - Test nodes as pure functions

• Observe Execution - Progress bars, custom event processors, and monitoring

• Visualize Graphs - Interactive graph visualization in notebooks and HTML

API Reference

• Graph - Graph construction, validation, and properties

• Nodes - FunctionNode, GraphNode, and HyperNode

• Gates - RouteNode, IfElseNode, @route, @ifelse

• Runners - SyncRunner, AsyncRunner, and execution model

• Events - Event types, processors, and RichProgressProcessor

• InputSpec - Input categorization and requirements

Design

• Guiding Principles - Design rubric and invariants

• Philosophy - Why hypergraph exists and design principles

• Inspiration - Frameworks that influenced hypergraph's design

• Roadmap - What's implemented, what's coming next

• Changelog - Release history and changes

Design Principles

1. Pure functions - Nodes are testable without the framework

2. Automatic wiring - Edges inferred from matching output/input names

3. Composition over configuration - Nest graphs, don't configure flags

4. Unified execution - Topo over SCCs, local iteration for feedback

5. Fail fast - Validate at build time, not runtime

6. Explicit dependencies - All inputs visible in function signatures

Beyond AI/ML

While the examples focus on AI/ML use cases, hypergraph is a general-purpose workflow framework. It has no dependencies on LLMs, vector databases, or any AI tooling. Use it for any multi-step workflow: ETL pipelines, business process automation, testing harnesses, or anything else that benefits from graph-based orchestration.