# https://github.com/The-Pocket/PocketFlow Project Manual

Generated at: 2026-06-18 19:37:24 UTC

## Table of Contents

- [Core Framework Architecture: Node, Flow, and Graph Abstraction](#page-1)
- [Design Patterns: Agent, Workflow, RAG, and Multi-Agent](#page-2)
- [Utility Functions: LLM, Embeddings, Vector, TTS, Web Search, and Visualization](#page-3)
- [Cookbook Examples, Human-in-the-Loop, and Deployment](#page-4)

<a id='page-1'></a>

## Core Framework Architecture: Node, Flow, and Graph Abstraction

### Related Pages

Related topics: [Design Patterns: Agent, Workflow, RAG, and Multi-Agent](#page-2), [Utility Functions: LLM, Embeddings, Vector, TTS, Web Search, and Visualization](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [pocketflow/__init__.py](https://github.com/The-Pocket/PocketFlow/blob/main/pocketflow/__init__.py)
- [pocketflow/__init__.pyi](https://github.com/The-Pocket/PocketFlow/blob/main/pocketflow/__init__.pyi)
- [setup.py](https://github.com/The-Pocket/PocketFlow/blob/main/setup.py)
- [docs/core_abstraction/node.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/core_abstraction/node.md)
- [docs/core_abstraction/flow.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/core_abstraction/flow.md)
- [docs/core_abstraction/communication.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/core_abstraction/communication.md)
- [docs/core_abstraction/batch.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/core_abstraction/batch.md)
- [cookbook/pocketflow-workflow/flow.py](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-workflow/flow.py)
- [cookbook/pocketflow-agent/nodes.py](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-agent/nodes.py)
- [cookbook/pocketflow-deep-research/flow.py](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-deep-research/flow.py)
</details>

# Core Framework Architecture: Node, Flow, and Graph Abstraction

## Overview and Design Philosophy

PocketFlow is a deliberately minimal LLM-application framework (~100 lines of core code) whose entire execution model rests on three abstractions: **Node**, **Flow**, and a **shared store** that mediates inter-node communication. As described in the repository README, the framework is positioned as a "100-line LLM framework" centered on a graph-of-thoughts paradigm, in which users compose deterministic, inspectable, and asynchronous graphs rather than opaque chain objects.

The core abstractions live in the single module [pocketflow/__init__.py](https://github.com/The-Pocket/PocketFlow/blob/main/pocketflow/__init__.py) and are exposed for type checking via [pocketflow/__init__.pyi](https://github.com/The-Pocket/PocketFlow/blob/main/pocketflow/__init__.pyi). The package is distributed as a zero-dependency Python wheel declared in [setup.py](https://github.com/The-Pocket/PocketFlow/blob/main/setup.py). The corresponding concept documentation is split across [docs/core_abstraction/node.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/core_abstraction/node.md), [docs/core_abstraction/flow.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/core_abstraction/flow.md), and [docs/core_abstraction/communication.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/core_abstraction/communication.md).

```mermaid
graph LR
    A[prep: read shared] --> B[exec: compute]
    B --> C[post: write shared & choose next]
    C -->|action string| D((successor node))
    C -->|default| E((next in chain))
```

## The Node Abstraction

Every step in a PocketFlow graph is a `Node` subclass (or a `BatchNode` subclass for fan-out work). A node's lifecycle is intentionally split into three asynchronous-aware methods documented in [docs/core_abstraction/node.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/core_abstraction/node.md):

| Phase | Method | Responsibility |
| --- | --- | --- |
| Prepare | `prep(shared)` | Read state from the shared store and return a context for execution. |
| Execute | `exec(prep_res)` | Perform the actual computation (e.g., an LLM call) without touching the shared store. |
| Post-process | `post(shared, prep_res, exec_res)` | Write results back to the shared store and return an *action string* that selects the next node. |

The return value of `post` is the routing key: the Flow engine looks up the action in the node's successor map and moves to the corresponding node (or terminates the graph). Because `exec` is forbidden from mutating the shared store, side effects are isolated and the graph is easier to reason about and visualize — a property the community has explicitly leveraged in tooling such as the PocketFlow Creator GUI proposed in [#139](https://github.com/The-Pocket/PocketFlow/issues/139). Reliability is also baked in: nodes can override `exec_fallback` to return a graceful result on failure, and a configurable retry counter (default 1) re-invokes `exec` on exceptions, as illustrated by the three-attempt summarizer in [cookbook/pocketflow-node/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-node/README.md).

`BatchNode`, described in [docs/core_abstraction/batch.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/core_abstraction/batch.md), simply re-runs `exec` once per item in a list returned by `prep`, enabling per-item parallelism; the translation example in [cookbook/pocketflow-batch/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-batch/README.md) uses this to fan out across languages.

## The Flow and Graph Abstraction

A `Flow` is a thin orchestration wrapper around a single start node; the start node's successors define the rest of the graph. Graph topology is declared using operator overloading — `>>` chains nodes sequentially and `-` registers a conditional branch keyed by the action string returned from `post`. This DSL is documented in [docs/core_abstraction/flow.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/core_abstraction/flow.md) and is visible in nearly every cookbook, for example the three-step article pipeline in [cookbook/pocketflow-workflow/flow.py](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-workflow/flow.py) and the planner/researcher/synthesizer loop in [cookbook/pocketflow-deep-research/flow.py](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-deep-research/flow.py), where the synthesizer routes back to the planner with the action `"research"` and terminates with `"finalize"`.

The operator syntax is intentionally small but expressive enough to encode the four design patterns promoted throughout the README — *Workflow*, *Agent*, *Batch*, and *Map-Reduce* — and more advanced patterns like *Agentic RAG*. Conditional labels are first-class: when a user requested better support for labeled conditional edges in [#66](https://github.com/The-Pocket/PocketFlow/issues/66), the maintainers added explicit support so the resulting Mermaid diagrams include action labels, e.g. `A --|search| B`. The same topic surfaced again in [#136](https://github.com/The-Pocket/PocketFlow/issues/136), which pointed out that the bundled visualizer could not render router nodes that fan out to several targets. Because the underlying graph stores successors as a dictionary keyed on action string, adding more terminal branches is purely additive — a property that makes PocketFlow well suited to the agentic patterns requested in [#104](https://github.com/The-Pocket/PocketFlow/issues/104) and [#117](https://github.com/The-Pocket/PocketFlow/issues/117).

## Communication: The Shared Store

Nodes never call one another; they communicate exclusively through a *shared store* — an ordinary Python dictionary handed to every node. The contract is documented in [docs/core_abstraction/communication.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/core_abstraction/communication.md): `prep` reads from it, `post` writes to it, and `exec` does not touch it. This single-channel model is what keeps the graph declarative and trivially serializable, and it is the same design choice that the typing proposal in [#106](https://github.com/The-Pocket/PocketFlow/issues/106) targets: turning the untyped `SharedData` (currently annotated in [pocketflow/__init__.pyi](https://github.com/The-Pocket/PocketFlow/blob/main/pocketflow/__init__.pyi)) into a generic so `TypedDict` subclasses can be checked at lint time. The Chinese-language thread in [#110](https://github.com/The-Pocket/PocketFlow/issues/110) goes further, arguing that the free-form shared dict is the main obstacle to converting low-code orchestrators (e.g., Dify) to PocketFlow, and suggests standardizing node input/output schemas.

## Failure Modes and Common Pitfalls

Three classes of bug recur across the issues and cookbooks:

1. **Forgetting to return an action string from `post`.** Because routing is value-driven, returning `None` causes the flow to terminate immediately — by design, since "no successor" is the canonical stop signal. The deep-research synthesizer deliberately returns either `"research"` or `"finalize"` to make the loop explicit.
2. **Letting `exec` mutate the shared store.** This breaks the prep/exec/post separation that makes retries safe; nodes should accumulate results in `exec_res` and write them in `post`.
3. **Visualizer gaps.** As reported in [#66](https://github.com/The-Pocket/PocketFlow/issues/66) and [#136](https://github.com/The-Pocket/PocketFlow/issues/136), the auto-generated Mermaid diagram must include the action label on every `-` edge for the routing logic to be visible; hand-rolled `build_mermaid` helpers are the current workaround.

## See Also

- Design patterns: [Workflow](https://the-pocket.github.io/PocketFlow/design_pattern/workflow.html), [Agent](https://the-pocket.github.io/PocketFlow/design_pattern/agent.html), [Batch](https://the-pocket.github.io/PocketFlow/core_abstraction/batch.html), [Map-Reduce](https://the-pocket.github.io/PocketFlow/design_pattern/mapreduce.html), [Agentic RAG](https://the-pocket.github.io/PocketFlow/design_pattern/rag.html)
- Cookbook examples referenced above: `pocketflow-workflow`, `pocketflow-agent`, `pocketflow-batch`, `pocketflow-deep-research`, `pocketflow-node`
- Human-in-the-loop integration: `pocketflow-fastapi-hitl`, `pocketflow-cli-hitl`, `pocketflow-streamlit-fsm`

---

<a id='page-2'></a>

## Design Patterns: Agent, Workflow, RAG, and Multi-Agent

### Related Pages

Related topics: [Core Framework Architecture: Node, Flow, and Graph Abstraction](#page-1), [Utility Functions: LLM, Embeddings, Vector, TTS, Web Search, and Visualization](#page-3), [Cookbook Examples, Human-in-the-Loop, and Deployment](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [docs/design_pattern/agent.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/design_pattern/agent.md)
- [docs/design_pattern/workflow.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/design_pattern/workflow.md)
- [docs/design_pattern/rag.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/design_pattern/rag.md)
- [docs/design_pattern/multi_agent.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/design_pattern/multi_agent.md)
- [docs/design_pattern/mapreduce.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/design_pattern/mapreduce.md)
- [docs/design_pattern/structure.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/design_pattern/structure.md)
- [cookbook/pocketflow-workflow/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-workflow/README.md)
- [cookbook/pocketflow-rag/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-rag/README.md)
- [cookbook/pocketflow-agentic-rag/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-agentic-rag/README.md)
- [cookbook/pocketflow-supervisor/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-supervisor/README.md)
- [cookbook/pocketflow-deep-research/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-deep-research/README.md)
- [cookbook/pocketflow-newsletter/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-newsletter/README.md)
- [cookbook/pocketflow-agent-skills/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-agent-skills/README.md)
</details>

# Design Patterns: Agent, Workflow, RAG, and Multi-Agent

## Overview

PocketFlow is a 100-line LLM framework whose entire design vocabulary reduces to three primitives: `Node`, `Flow`, and a shared dictionary that flows between nodes (`shared`). Rather than inventing a new DSL, PocketFlow encourages developers to express LLM applications as a small number of reusable, composable **design patterns**. The official documentation dedicates an entire section to these patterns and references them throughout the cookbook: Workflow, Agent, RAG, and Multi-Agent, with Map-Reduce and Batch sitting alongside them as execution-time patterns.

Source: [docs/design_pattern/structure.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/design_pattern/structure.md)

The four canonical patterns differ along two axes: **who controls control flow** (developer vs. LLM) and **how knowledge enters the model** (parameters only vs. retrieved context vs. tool feedback). The table below summarizes how the patterns map to concrete node graphs and cookbook examples.

### Pattern Comparison

| Pattern | Control Flow | Knowledge Source | Typical Node Graph | Reference Cookbook |
|---|---|---|---|---|
| Workflow | Developer-defined DAG | Prompt + shared state | `A >> B >> C` linear/branching | `pocketflow-workflow`, `pocketflow-newsletter` |
| Agent | LLM-driven loop | Prompt + tool results | `decide -> action -> decide` | `pocketflow-agent-skills`, `pocketflow-self-healing-mermaid` |
| RAG | Developer-defined pipeline | Retrieved documents | `chunk -> embed -> index -> retrieve -> generate` | `pocketflow-rag`, `pocketflow-agentic-rag` |
| Multi-Agent | Outer + inner loops | Supervisor judgment | `supervisor -> inner_agent -> supervisor` | `pocketflow-supervisor` |

## Workflow Pattern

The Workflow pattern is a deterministic, developer-authored DAG. Each node performs a well-defined transformation and the developer wires the order with the `>>` operator. There is no back-edge to the LLM — the flow runs from start to finish in a predictable shape.

A canonical example is the Article Writing Workflow, which chains `Generate Outline → Write Content → Apply Style`. Source: [cookbook/pocketflow-workflow/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-workflow/README.md). The Newsletter cookbook extends this with a four-node linear pipeline `CurateSources → FilterStories → SummarizeStories → FormatNewsletter` and exposes a `--topic` CLI flag that simply seeds `shared["topic"]` before the flow runs. Source: [cookbook/pocketflow-newsletter/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-newsletter/README.md).

Workflows are the right choice when the steps are known up front, the cost of a wrong LLM call is bounded, and the user benefits from seeing the entire pipeline at a glance — the same "100-line" aesthetic that community contributors repeatedly praise (see [Issue #31](https://github.com/The-Pocket/PocketFlow/issues/31)).

## Agent Pattern

The Agent pattern inverts control: the LLM chooses the next action at runtime. The classic shape is a `DecideAction` node whose `post()` method returns an action string that routes the flow to either a tool node or a terminal `Answer` node, with a back-edge to `DecideAction` to continue the loop. PocketFlow's action-based branching makes this loop a one-liner: `node_a - "search" >> search_node; node_a - "answer" >> answer_node`.

The Agent Skills cookbook shows a stripped-down two-node variant where `SelectSkill` chooses a reusable markdown skill and `ApplySkill` executes the task with the LLM. Source: [cookbook/pocketflow-agent-skills/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-agent-skills/README.md). The Self-Healing Mermaid generator is a tighter example of the agent loop: `WriteChart → CompileChart`, and on failure the compiler returns a `"fix"` action that routes back to the writer, capping retries at three. Source: [cookbook/pocketflow-self-healing-mermaid/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-self-healing-mermaid/README.md).

Community interest in this pattern is high: [Issue #104](https://github.com/The-Pocket/PocketFlow/issues/104) requests a Claude-Code-style subagent cookbook, and [Issue #128](https://github.com/The-Pocket/PocketFlow/issues/128) proposes adding the Agent Skills standard as a first-class routing mechanism — both of which the existing `pocketflow-agent-skills` example already sketches.

## RAG Pattern

RAG in PocketFlow is split into an offline indexing subgraph and an online retrieval subgraph, both expressed as ordinary Flows. The RAG cookbook wires `ChunkDocumentsNode → EmbedDocumentsNode → CreateIndexNode` offline and `EmbedQueryNode → RetrieveDocumentNode → GenerateAnswerNode` online, with FAISS providing the vector index. Source: [cookbook/pocketflow-rag/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-rag/README.md).

When retrieval should be selective rather than top-K blind, PocketFlow composes RAG with the Agent pattern. The Agentic RAG cookbook uses `DecideAction` to pick which document summary to read next, looping `read → decide` until the model emits `answer`. Source: [cookbook/pocketflow-agentic-rag/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-agentic-rag/README.md). The Deep Research cookbook is the most elaborate variant, layering a `PlannerNode → ResearcherNode (BatchNode) → SynthesizerNode` flow with a self-referential `research` action that re-enters the planner until the report is deemed complete. Source: [cookbook/pocketflow-deep-research/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-deep-research/README.md).

Community contributors have asked to harden the RAG story further: [Issue #117](https://github.com/The-Pocket/PocketFlow/issues/117) requests a database-to-natural-language tutorial, and [Issue #132](https://github.com/The-Pocket/PocketFlow/issues/132) proposes a 100-line RAG example that exposes a debug mode for 16 known RAG failure patterns.

## Multi-Agent Pattern

The Multi-Agent pattern nests one agent inside another. The outer flow wraps the inner agent and inspects its output, deciding whether to accept the result, request a re-run, or terminate. The Supervisor cookbook demonstrates this directly: an inner `DecideAction → SearchWeb/UnreliableAnswer → DecideAction` research agent is wrapped by a `SupervisorNode` that re-injects the prompt until the answer meets a quality bar. Source: [cookbook/pocketflow-supervisor/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-supervisor/README.md).

This pattern is also where the framework's `shared` dictionary becomes load-bearing. The supervisor reads whatever the inner agent wrote into `shared` and writes a verdict back into it; the inner agent's `prep()` picks up the verdict on the next iteration. Community feedback ([Issue #110](https://github.com/The-Pocket/PocketFlow/issues/110)) and [Issue #106](https://github.com/The-Pocket/PocketFlow/issues/106) both call out that the untyped `shared` object is the main obstacle to scaling this pattern, motivating a future `SharedData` generic so that lint catches mismatches between `prep` and `post`.

## Choosing a Pattern

A practical decision rule, distilled from the docs and cookbook READMEs:

- **Steps are known and stable?** Use a Workflow. It is the most testable and the easiest to visualize (see the Mermaid graphs in every cookbook).
- **The next step depends on intermediate results?** Use an Agent. Bound it with a retry counter and a self-healing loop.
- **Answers require external knowledge?** Use RAG. Upgrade to Agentic RAG when retrieval should be selective, and add Map-Reduce or Batch nodes for parallel fact extraction.
- **The LLM is unreliable or specialized?** Wrap it in a Multi-Agent supervisor that validates and re-prompts.

Map-Reduce and Batch are orthogonal: they describe *how* nodes execute (in parallel over a list) rather than *who* chooses the next step, and they appear as building blocks inside Workflow, Agent, and RAG flows. The Batch Translation cookbook shows the pattern in its minimal form: a single `TranslateTextNode` whose `prep()` returns a list of language targets and whose `exec()` is invoked once per item in parallel. Source: [cookbook/pocketflow-batch/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-batch/README.md).

## See Also

- [Core Abstractions: Node, Flow, and Shared State](core-abstractions.md)
- [Node Lifecycle: prep, exec, post, and exec_fallback](node-lifecycle.md)
- [Batch and Map-Reduce Patterns](batch-mapreduce.md)
- [Building Agents with Tool Use](agents-and-tools.md)

---

<a id='page-3'></a>

## Utility Functions: LLM, Embeddings, Vector, TTS, Web Search, and Visualization

### Related Pages

Related topics: [Core Framework Architecture: Node, Flow, and Graph Abstraction](#page-1), [Design Patterns: Agent, Workflow, RAG, and Multi-Agent](#page-2), [Cookbook Examples, Human-in-the-Loop, and Deployment](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [docs/utility_function/llm.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/utility_function/llm.md)
- [docs/utility_function/embedding.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/utility_function/embedding.md)
- [docs/utility_function/vector.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/utility_function/vector.md)
- [docs/utility_function/text_to_speech.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/utility_function/text_to_speech.md)
- [docs/utility_function/websearch.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/utility_function/websearch.md)
- [docs/utility_function/chunking.md](https://github.com/The-Pocket/PocketFlow/blob/main/docs/utility_function/chunking.md)
- [cookbook/pocketflow-rag/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-rag/README.md)
- [cookbook/pocketflow-notebook-lm/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-notebook-lm/README.md)
- [cookbook/pocketflow-tool-search/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-tool-search/README.md)
- [cookbook/pocketflow-self-healing-mermaid/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-self-healing-mermaid/README.md)
- [cookbook/pocketflow-newsletter/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-newsletter/README.md)
- [cookbook/pocketflow-deep-research/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-deep-research/README.md)
- [README.md](https://github.com/The-Pocket/PocketFlow/blob/main/README.md)
</details>

# Utility Functions: LLM, Embeddings, Vector, TTS, Web Search, and Visualization

## Overview and Purpose

PocketFlow is positioned as a "100-line LLM framework" whose core abstraction is a `Node`–`Flow` graph. The framework itself stays intentionally tiny (the `BaseNode` / `Flow` machinery is defined in [`pocketflow/__init__.pyi`](https://github.com/The-Pocket/PocketFlow/blob/main/pocketflow/__init__.pyi)), so everything else that an LLM application needs — calling a model, embedding text, searching the web, generating audio, indexing vectors, or visualizing a graph — is delivered as a **utility function** documented separately from the core runtime.

This separation is a deliberate design choice. The community issue [Turn SharedData into generic for improved code intelligence / type checking (#106)](https://github.com/The-Pocket/PocketFlow/issues/106) explicitly notes that the runtime is intentionally minimal so that users can keep their own data layer typed (`TypedDict`) while the framework stays generic. Utility functions follow the same philosophy: they are thin, swappable adapters that a `Node.exec()` can call without inheriting any framework concepts.

The main project README links to these utility pages from the cookbook tables, e.g. `[Web Search](https://the-pocket.github.io/PocketFlow/utility_function/websearch.html)` is the canonical reference used by the *Cold Opener Generator* tutorial and by `cookbook/pocketflow-tool-search`. Source: [README.md](https://github.com/The-Pocket/PocketFlow/blob/main/README.md)

## The Six Utility Modules

### LLM and Embeddings

`docs/utility_function/llm.md` is the canonical "how do I call a model" page. Every cookbook that touches an LLM imports the same wrapper rather than calling OpenAI/Anthropic SDKs directly. For example, the article workflow uses `utils/call_llm.py` for outline generation, content writing, and style application. Source: [cookbook/pocketflow-workflow/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-workflow/README.md)

`docs/utility_function/embedding.md` is the matching page for vector embedding calls. The RAG cookbook wires it into a dedicated `EmbedDocumentsNode` and `EmbedQueryNode` so that the same call site can be used for both the offline indexing flow and the online query flow. Source: [cookbook/pocketflow-rag/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-rag/README.md)

A typical pattern, taken from the RAG cookbook's two-phase pipeline, looks like this:

```mermaid
graph TD
    subgraph OfflineFlow[Offline Document Indexing]
        ChunkDocs[ChunkDocumentsNode] --> EmbedDocs[EmbedDocumentsNode] --> CreateIndex[CreateIndexNode]
    end
    subgraph OnlineFlow[Online Processing]
        EmbedQuery[EmbedQueryNode] --> RetrieveDoc[RetrieveDocumentNode] --> GenerateAnswer[GenerateAnswerNode]
    end
```

### Vector and Chunking

Vector storage and chunking are documented in `docs/utility_function/vector.md` and `docs/utility_function/chunking.md`. In the RAG example they are used to (1) split long documents into manageable pieces, (2) embed each piece, and (3) load the resulting vectors into a FAISS index that supports similarity search at query time. Source: [cookbook/pocketflow-rag/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-rag/README.md)

Chunking matters because the same `ChunkDocumentsNode` output is also consumed by the **Map-Reduce** design pattern (referenced from the README for the *Youtube Summarizer* tutorial) and by **Deep Research**, where the `ResearcherNode` is implemented as a `BatchNode` that runs web search + fact extraction per chunk/query. Source: [cookbook/pocketflow-deep-research/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-deep-research/README.md)

### Web Search and Text-to-Speech

`docs/utility_function/websearch.md` is referenced from the README table and is implemented in cookbooks using either SerpAPI (for Google results) or DuckDuckGo (for the newsletter/deep-research examples). The pattern is always the same: a search node returns a list of `{title, snippet, link}` results into the shared store, and a downstream parser node uses the LLM to extract structured information. Source: [cookbook/pocketflow-tool-search/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-tool-search/README.md) and [cookbook/pocketflow-newsletter/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-newsletter/README.md)

`docs/utility_function/text_to_speech.md` is exercised by the NotebookLM-style podcast generator. The `TextToSpeech` node takes a two-host script and produces one MP3 by mapping each host to a distinct OpenAI TTS voice (Alex → `alloy`, Jamie → `echo`) and concatenating the audio segments. Source: [cookbook/pocketflow-notebook-lm/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-notebook-lm/README.md)

## Visualization

Visualization is the odd one out: it is not a callable utility, but a **development-time helper** that turns a `Flow` definition into a Mermaid diagram. The community has asked for richer output here:

- Issue [#66 "Visualization with Mermaid, Add label for link condition would be nice"](https://github.com/The-Pocket/PocketFlow/issues/66) proposes adding a `label` argument to the link helper so that conditional edges (e.g. `router - "yes" >> task1`) render as `A --|label| B` instead of `A --> B` in the generated Mermaid.
- Issue [#136 "Incomplete visualization tool"](https://github.com/The-Pocket/PocketFlow/issues/136) reports that a router node that fans out to multiple terminal nodes is not rendered correctly.

Despite these gaps, the *Self-Healing Mermaid* cookbook demonstrates an end-to-end usage: an LLM writes Mermaid syntax, `mermaid-cli` (`mmdc`) compiles it, and on a compile failure the error is fed back to the LLM for up to 3 retries. Source: [cookbook/pocketflow-self-healing-mermaid/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-self-healing-mermaid/README.md)

## Usage Patterns and Failure Modes

Across all cookbooks, utility functions are consumed in the same idiomatic way: a node's `prep()` reads inputs from the shared store, `exec()` calls the utility, and `post()` writes the result back. Errors are handled by the standard PocketFlow retry mechanism — the *Node* example configures `max_retries=3` and provides an `exec_fallback()` for graceful degradation. Source: [cookbook/pocketflow-node/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-node/README.md)

The most common failure mode is missing API keys; almost every cookbook ships a `python utils.py` smoke test that the README explicitly recommends running before the main entry point, e.g. "Quick check to make sure your API key works". Source: [cookbook/pocketflow-rag/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-rag/README.md) and [cookbook/pocketflow-newsletter/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-newsletter/README.md)

## See Also

- [Design Patterns: Workflow, Agent, RAG, Map-Reduce](https://the-pocket.github.io/PocketFlow/) (linked from the main [README.md](https://github.com/The-Pocket/PocketFlow/blob/main/README.md))
- Cookbook examples: [pocketflow-rag](https://github.com/The-Pocket/PocketFlow/tree/main/cookbook/pocketflow-rag), [pocketflow-tool-search](https://github.com/The-Pocket/PocketFlow/tree/main/cookbook/pocketflow-tool-search), [pocketflow-notebook-lm](https://github.com/The-Pocket/PocketFlow/tree/main/cookbook/pocketflow-notebook-lm), [pocketflow-deep-research](https://github.com/The-Pocket/PocketFlow/tree/main/cookbook/pocketflow-deep-research), [pocketflow-self-healing-mermaid](https://github.com/The-Pocket/PocketFlow/tree/main/cookbook/pocketflow-self-healing-mermaid)
- Open issues driving utility improvements: [#66](https://github.com/The-Pocket/PocketFlow/issues/66), [#136](https://github.com/The-Pocket/PocketFlow/issues/136), [#106](https://github.com/The-Pocket/PocketFlow/issues/106)

---

<a id='page-4'></a>

## Cookbook Examples, Human-in-the-Loop, and Deployment

### Related Pages

Related topics: [Core Framework Architecture: Node, Flow, and Graph Abstraction](#page-1), [Design Patterns: Agent, Workflow, RAG, and Multi-Agent](#page-2), [Utility Functions: LLM, Embeddings, Vector, TTS, Web Search, and Visualization](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/The-Pocket/PocketFlow/blob/main/README.md)
- [cookbook/pocketflow-workflow/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-workflow/README.md)
- [cookbook/pocketflow-node/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-node/README.md)
- [cookbook/pocketflow-batch/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-batch/README.md)
- [cookbook/pocketflow-rag/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-rag/README.md)
- [cookbook/pocketflow-newsletter/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-newsletter/README.md)
- [cookbook/pocketflow-fastapi-hitl/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-fastapi-hitl/README.md)
- [cookbook/pocketflow-fastapi-background/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-fastapi-background/README.md)
- [cookbook/pocketflow-self-healing-mermaid/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-self-healing-mermaid/README.md)
- [cookbook/pocketflow-coding-agent/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-coding-agent/README.md)
- [cookbook/pocketflow-agent-skills/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-agent-skills/README.md)
</details>

# Cookbook Examples, Human-in-the-Loop, and Deployment

PocketFlow is promoted as a "100-line LLM framework" that favors *agentic coding* — humans design the graph, agents write the boilerplate. The `cookbook/` directory is where that philosophy becomes tangible: every example is a minimal, end-to-end project that demonstrates one concrete pattern using `Node`, `BatchNode`, and `Flow`. Beyond the canonical LLM pipelines, the cookbook also serves as the reference for two practical concerns raised repeatedly by the community: building **human-in-the-loop (HITL)** flows and **deploying** PocketFlow graphs behind real web services. Source: [README.md](https://github.com/The-Pocket/PocketFlow/blob/main/README.md)

## Cookbook Architecture and Tiering

The top-level `README.md` organizes examples by difficulty so newcomers can ramp up incrementally. Source: [README.md](https://github.com/The-Pocket/PocketFlow/blob/main/README.md)

| Tier | Marker | Examples |
| --- | --- | --- |
| Dummy | ☆☆☆ | RAG, Batch, Streaming, Chat Guardrail, Majority Vote, Map-Reduce, CLI HITL, Multi-Agent |
| Beginner | ★☆☆ | Agent Skills, A2A, Streamlit FSM, FastAPI WebSocket, FastAPI Background, Voice Chat, Judge |
| Intermediate | ★★☆ | Deep Research (recursive map-reduce) |
| Advanced | ★★★ | Coding Agent (6 tools, memory, patch subflow) |

Each example follows a consistent four-file layout: `main.py` (CLI entry), `flow.py` (graph wiring), `nodes.py` (node classes), and a `utils/` helper for LLM calls. For instance, `cookbook/pocketflow-workflow/README.md` documents a three-node article writer (`Generate Outline` → `Write Content` → `Apply Style`) wired linearly in `flow.py` and executed from `main.py`. Source: [cookbook/pocketflow-workflow/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-workflow/README.md)

This tiering means a developer can start with a Dummy example (e.g., a single-node summarizer) and progress to the Coding Agent without ever leaving the repo.

## Human-in-the-Loop Patterns

HITL is one of the most-requested topics in the issue tracker (see #30, #104). The cookbook answers it with three complementary recipes that share a single insight: pause the flow at a node, write a status flag to the shared store, and let an external UI (or stdin) resolve it.

**Web HITL with FastAPI and SSE.** `cookbook/pocketflow-fastapi-hitl/README.md` describes a minimal service where users submit text, observe real-time status, and click Approve/Reject buttons. The flow moves `process → review → result`, looping back to `process` on rejection. Server-Sent Events stream status updates to the browser so the client does not need to poll. Source: [cookbook/pocketflow-fastapi-hitl/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-fastapi-hitl/README.md)

**CLI HITL.** Listed in the top-level table, the CLI HITL "dummy" example shows the same approve/reject mechanic on stdin — useful for batch scripts and quick local testing. Source: [README.md](https://github.com/The-Pocket/PocketFlow/blob/main/README.md)

**Streamlit FSM.** The Streamlit FSM beginner example pairs PocketFlow with a finite state machine UI for HITL image generation, showing that the pause/resolve pattern is UI-agnostic. Source: [README.md](https://github.com/The-Pocket/PocketFlow/blob/main/README.md)

The common contract is simple: any node can return a string action label; the runtime consults the shared store for human input before deciding which successor to invoke. Issue #30 (a finance-approval scenario) maps directly onto this pattern — auto-approve below a threshold, suspend and resume on supervisor approval.

## Deployment Recipes

Deploying a PocketFlow graph typically means wrapping it in a web framework and exposing either streaming or background-job semantics. The cookbook ships three production-shaped templates.

**FastAPI WebSocket (Beginner).** A real-time chat interface where the LLM response is streamed token-by-token over a WebSocket, and the client can interrupt mid-generation. This is the recipe to copy when latency matters more than persistence. Source: [README.md](https://github.com/The-Pocket/PocketFlow/blob/main/README.md)

**FastAPI Background with SSE (Beginner).** `cookbook/pocketflow-fastapi-background/README.md` covers a longer-running article generation flow. The `/start-job` endpoint enqueues work via `BackgroundTasks` and returns a job ID; the `/progress/{job_id}` endpoint streams progress events (33% → 66% → 100%) over SSE. Each node pushes step updates into a job-scoped `sse_queue` during `exec()`. Source: [cookbook/pocketflow-fastapi-background/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-fastapi-background/README.md)

**Supervisor / Self-Healing Loops.** Two intermediate patterns show how a Flow can wrap another Flow. `pocketflow-supervisor` re-invokes an inner research agent until it produces a quality answer (Source: [cookbook/pocketflow-supervisor/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-supervisor/README.md)), while `pocketflow-self-healing-mermaid` feeds Mermaid compile errors back to the LLM and retries up to three times. Source: [cookbook/pocketflow-self-healing-mermaid/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-self-healing-mermaid/README.md)

```mermaid
flowchart LR
    Client[Browser/CLI] -->|submit| API[FastAPI Endpoint]
    API -->|enqueue| BG[BackgroundTasks]
    BG --> Flow[PocketFlow Graph]
    Flow -->|progress events| SSE[SSE Stream]
    SSE -->|update| Client
    Flow -.->|await human| HITL[HITL Pause/Resume]
    HITL -.->|resume| Flow
```

## Advanced End-to-End Examples

Two cookbooks showcase the upper bound of what PocketFlow can express with its tiny core. `pocketflow-coding-agent` implements a production coding agent with six tools (`list_files`, `grep_search`, `read_file`, `patch_file`, `run_command`, `done`), persistent `.memory.md`, project-specific skill loading from `AGENTS.md`, and a `patch_file` operation implemented as a Flow-IS-Node subflow (Read → Validate → Apply). Source: [cookbook/pocketflow-coding-agent/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-coding-agent/README.md) `pocketflow-agent-skills` demonstrates a lightweight router that selects a local markdown skill file and injects it into the final LLM prompt — exactly the Agent Skills integration proposed in issue #128. Source: [cookbook/pocketflow-agent-skills/README.md](https://github.com/The-Pocket/PocketFlow/blob/main/cookbook/pocketflow-agent-skills/README.md)

## See Also

- Core concepts: `Node`, `Flow`, `BatchNode`, shared store
- [Issue #30 — Human-in-the-loop with FastAPI/SSE](https://github.com/The-Pocket/PocketFlow/issues/30)
- [Issue #104 — Claude-Code-style subagent cookbook](https://github.com/The-Pocket/PocketFlow/issues/104)
- [Issue #128 — Agent Skills usage proposal](https://github.com/The-Pocket/PocketFlow/issues/128)
- [Issue #136 — Visualization tool completeness](https://github.com/The-Pocket/PocketFlow/issues/136)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: The-Pocket/PocketFlow

Summary: Found 16 structured pitfall item(s), including 5 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/The-Pocket/PocketFlow/issues/110

## 2. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/The-Pocket/PocketFlow/issues/132

## 3. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/The-Pocket/PocketFlow/issues/30

## 4. Maintenance risk - Maintenance risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/The-Pocket/PocketFlow/issues/106

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/The-Pocket/PocketFlow/issues/119

## 6. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/The-Pocket/PocketFlow/issues/128

## 7. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/The-Pocket/PocketFlow/issues/139

## 8. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/The-Pocket/PocketFlow

## 9. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a capability evidence risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/The-Pocket/PocketFlow/issues/136

## 10. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/The-Pocket/PocketFlow

## 11. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/The-Pocket/PocketFlow

## 12. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/The-Pocket/PocketFlow

## 13. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/The-Pocket/PocketFlow

## 14. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/The-Pocket/PocketFlow/issues/135

## 15. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/The-Pocket/PocketFlow

## 16. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/The-Pocket/PocketFlow

<!-- canonical_name: The-Pocket/PocketFlow; human_manual_source: deepwiki_human_wiki -->