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

### Core Concepts

* [Getting Started](/hypergraph/core-concepts/getting-started.md) - Core concepts, creating nodes, building graphs, running workflows

### Patterns

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

### Real-World Examples

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

### How-To Guides

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

### API Reference

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

### Design

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gilad-rubin.gitbook.io/hypergraph/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.