# 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.

```python
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**

```python
# 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**

```python
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**

```python
# 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?](https://gilad-rubin.gitbook.io/hypergraph/getting-started/what-is-hypergraph) - The problem, solution, and key differentiators
* [When to Use](https://gilad-rubin.gitbook.io/hypergraph/getting-started/when-to-use) - Is hypergraph right for your use case?
* [Quick Start](https://gilad-rubin.gitbook.io/hypergraph/getting-started/quick-start) - Get running in 5 minutes
* [Comparison](https://gilad-rubin.gitbook.io/hypergraph/getting-started/comparison) - How hypergraph compares to other frameworks

### Core Concepts

* [Getting Started](https://gilad-rubin.gitbook.io/hypergraph/core-concepts/getting-started) - Core concepts, creating nodes, building graphs, running workflows

### Patterns

* [Simple Pipeline](https://gilad-rubin.gitbook.io/hypergraph/patterns/01-simple-pipeline) - Linear DAGs, data transformations
* [Routing](https://gilad-rubin.gitbook.io/hypergraph/patterns/02-routing) - Conditional routing with @ifelse and @route
* [Agentic Loops](https://gilad-rubin.gitbook.io/hypergraph/patterns/03-agentic-loops) - Iterative refinement, multi-turn workflows
* [Hierarchical Composition](https://gilad-rubin.gitbook.io/hypergraph/patterns/04-hierarchical) - Nest graphs, Think Singular Scale with Map
* [Multi-Agent](https://gilad-rubin.gitbook.io/hypergraph/patterns/05-multi-agent) - Agent teams, orchestration patterns
* [Streaming](https://gilad-rubin.gitbook.io/hypergraph/patterns/06-streaming) - Stream LLM responses token-by-token
* [Human-in-the-Loop](https://gilad-rubin.gitbook.io/hypergraph/patterns/07-human-in-the-loop) - `@interrupt` decorator, pause/resume, and handler patterns
* [Caching](https://gilad-rubin.gitbook.io/hypergraph/patterns/08-caching) - Skip redundant computation with in-memory or disk caching

### Real-World Examples

* [RAG Pipeline](https://gilad-rubin.gitbook.io/hypergraph/real-world-examples/rag-pipeline) - Single-pass retrieval-augmented generation
* [Multi-Turn RAG](https://gilad-rubin.gitbook.io/hypergraph/real-world-examples/multi-turn-rag) - Conversational RAG with follow-up questions
* [Evaluation Harness](https://gilad-rubin.gitbook.io/hypergraph/real-world-examples/evaluation-harness) - Test conversation systems at scale
* [Data Pipeline](https://gilad-rubin.gitbook.io/hypergraph/real-world-examples/data-pipeline) - Classic ETL without LLMs
* [Prompt Optimization](https://gilad-rubin.gitbook.io/hypergraph/real-world-examples/prompt-optimization) - Iterative prompt improvement with nested graphs

### How-To Guides

* [Batch Processing](https://gilad-rubin.gitbook.io/hypergraph/how-to-guides/batch-processing) - Process multiple inputs with runner.map()
* [Rename and Adapt](https://gilad-rubin.gitbook.io/hypergraph/how-to-guides/rename-and-adapt) - Reuse functions in different contexts
* [Integrate with LLMs](https://gilad-rubin.gitbook.io/hypergraph/how-to-guides/integrate-with-llms) - Patterns for OpenAI, Anthropic, and others
* [Test Without Framework](https://gilad-rubin.gitbook.io/hypergraph/how-to-guides/test-without-framework) - Test nodes as pure functions
* [Observe Execution](https://gilad-rubin.gitbook.io/hypergraph/how-to-guides/observe-execution) - Progress bars, custom event processors, and monitoring
* [Visualize Graphs](https://gilad-rubin.gitbook.io/hypergraph/how-to-guides/visualize-graphs) - Interactive graph visualization in notebooks and HTML

### API Reference

* [Graph](https://gilad-rubin.gitbook.io/hypergraph/api-reference/graph) - Graph construction, validation, and properties
* [Nodes](https://gilad-rubin.gitbook.io/hypergraph/api-reference/nodes) - FunctionNode, GraphNode, and HyperNode
* [Gates](https://gilad-rubin.gitbook.io/hypergraph/api-reference/gates) - RouteNode, IfElseNode, @route, @ifelse
* [Runners](https://gilad-rubin.gitbook.io/hypergraph/api-reference/runners) - SyncRunner, AsyncRunner, and execution model
* [Events](https://gilad-rubin.gitbook.io/hypergraph/api-reference/events) - Event types, processors, and RichProgressProcessor
* [InputSpec](https://gilad-rubin.gitbook.io/hypergraph/api-reference/inputspec) - Input categorization and requirements

### Design

* [Guiding Principles](https://gilad-rubin.gitbook.io/hypergraph/design/guiding-principles) - Design rubric and invariants
* [Philosophy](https://gilad-rubin.gitbook.io/hypergraph/design/philosophy) - Why hypergraph exists and design principles
* [Inspiration](https://gilad-rubin.gitbook.io/hypergraph/design/inspiration) - Frameworks that influenced hypergraph's design
* [Roadmap](https://gilad-rubin.gitbook.io/hypergraph/design/roadmap) - What's implemented, what's coming next
* [Changelog](https://gilad-rubin.gitbook.io/hypergraph/design/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.