Pocketflow Framework

100 lines of code. That's the entire framework.

Most LLM frameworks ship thousands of lines of abstraction — classes, adapters, vendor wrappers, plugin systems — and yet the underlying idea is always the same: chain some LLM calls together, pass state between them, and handle failures.

Pocketflow strips all of that away. The core engine is a single TypeScript file that models LLM workflows as a Nested Directed Graph: nodes do work, actions route between them, flows orchestrate the graph, and shared state ties it all together.

This is the original core abstraction behind the Pocketflow Platform, where non-developers create custom AI workflows in natural language.

Table of Contents

• Why This Exists
• Architecture
• How It Works
• Quick Start
• Usage Guide
  • Nodes
  • Flows
  • Branching & Cycles
  • RetryNode
  • Nested Flows
  • BatchFlow
• Design Patterns
• CLI
• Project Structure
• Whitepaper
• Contributing
• License

Why This Exists

Every LLM framework eventually converges on the same pattern:

1. Break a task into steps
2. Let each step read/write shared context
3. Decide what happens next based on the result
4. Handle failures gracefully

The difference is how much ceremony surrounds that pattern. Pocketflow's answer: almost none. The entire runtime is ~100 lines. There are no vendor lock-ins, no mandatory adapters, no configuration files. You bring your own LLM client, your own database, your own whatever — and the framework just orchestrates the graph.

Key properties:

• Vendor-agnostic — Call OpenAI, Anthropic, local models, or a REST API. The framework doesn't care.
• Tiny surface area — One file, four classes. You can read and understand the entire codebase in 10 minutes.
• Nested composition — Flows can contain other flows. Build complex systems from simple, tested pieces.
• Parallel execution — BatchFlow runs multiple flow instances concurrently with automatic fan-out.
• Built-in retry — RetryNode wraps any node with configurable retry + backoff.

Architecture

The framework models every workflow as a Nested Directed Graph:

How It Works

Every node runs the same three-step lifecycle:

The execWrapper sits between prep and exec — it's where RetryNode adds its retry loop, and where you can add your own middleware (rate limiting, caching, logging, etc.).

Quick Start

git clone https://github.com/Osly-AI/Pocket-Flow-Framework.git
cd Pocket-Flow-Framework
npm install

Run the test suite:

npm test

Build:

npm run build

Usage Guide

Nodes

Every node extends BaseNode and implements three methods:

import { BaseNode, DEFAULT_ACTION } from "pocketflow";

class SummarizeNode extends BaseNode {
  async prep(sharedState: any) {
    // Read from shared state
    return { text: sharedState.document };
  }

  async execCore(prepResult: any) {
    // Call your LLM (bring your own client)
    const response = await openai.chat.completions.create({
      model: "gpt-4",
      messages: [{ role: "user", content: `Summarize: ${prepResult.text}` }]
    });
    return { summary: response.choices[0].message.content };
  }

  async post(prepResult: any, execResult: any, sharedState: any) {
    // Write back to shared state
    sharedState.summary = execResult.summary;
    return DEFAULT_ACTION;
  }

  _clone() { return new SummarizeNode(); }
}

Flows

Connect nodes with addSuccessor, then wrap them in a Flow:

import { Flow, DEFAULT_ACTION } from "pocketflow";

const summarize = new SummarizeNode();
const review = new ReviewNode();
const publish = new PublishNode();

// Linear chain: summarize → review → publish
summarize.addSuccessor(review, DEFAULT_ACTION);
review.addSuccessor(publish, DEFAULT_ACTION);

const pipeline = new Flow(summarize);
await pipeline.run({ document: "..." });

Branching & Cycles

Nodes can return different action strings to route execution:

class QualityCheckNode extends BaseNode {
  async post(prepResult: any, execResult: any, sharedState: any) {
    if (execResult.score >= 0.8) return "approved";
    if (sharedState.retryCount < 3) return "retry";
    return "reject";
  }
  // ...
}

const check = new QualityCheckNode();
const publish = new PublishNode();
const revise = new ReviseNode();
const reject = new RejectNode();

check.addSuccessor(publish, "approved");
check.addSuccessor(revise, "retry");
check.addSuccessor(reject, "reject");

// Create a cycle: revise feeds back into check
revise.addSuccessor(check, DEFAULT_ACTION);

RetryNode

Wrap any node with automatic retry and configurable backoff:

import { RetryNode } from "pocketflow";

class ResilientLLMNode extends RetryNode {
  constructor() {
    super(3, 2000); // 3 attempts, 2 seconds between retries
  }

  async prep(sharedState: any) { /* ... */ }
  async execCore(prepResult: any) {
    // If this throws, RetryNode catches it and retries
    return await callUnreliableAPI(prepResult);
  }
  async post(prep: any, exec: any, sharedState: any) { /* ... */ }
  _clone() { return new ResilientLLMNode(); }
}

Nested Flows

Flows are nodes — so you can nest them arbitrarily:

// Inner flow: extract → summarize
const extract = new ExtractNode();
const summarize = new SummarizeNode();
extract.addSuccessor(summarize, DEFAULT_ACTION);
const extractAndSummarize = new Flow(extract);

// Outer flow: extractAndSummarize → publish
const publish = new PublishNode();
extractAndSummarize.addSuccessor(publish, DEFAULT_ACTION);
const fullPipeline = new Flow(extractAndSummarize);

await fullPipeline.run(sharedState);

This is the key design insight: because Flow extends BaseNode, you can compose arbitrarily complex systems from small, individually testable flows.

BatchFlow

Process multiple items concurrently. Override prep() to return an array — each element spawns a parallel flow execution:

import { BatchFlow } from "pocketflow";

class ProcessDocuments extends BatchFlow {
  async prep(sharedState: any) {
    // Return one config per document — each runs the flow in parallel
    return sharedState.documents.map((doc: string) => ({ document: doc }));
  }
}

// The inner flow runs once per document, concurrently
const summarize = new SummarizeNode();
const batch = new ProcessDocuments(summarize);

await batch.run({
  documents: ["paper1.pdf", "paper2.pdf", "paper3.pdf", /* ...100 more */]
});

Design Patterns

All common LLM patterns are just different graph topologies:

You don't need different APIs for these. They're all the same Node + Flow + addSuccessor primitives, wired differently.

Core Abstractions

CLI

Scaffold new components quickly:

npx pocket new node MyProcessor    # Creates src/nodes/MyProcessor.node.ts
npx pocket new flow MyPipeline     # Creates src/flows/MyPipeline.flow.ts

Generated files include typed interfaces, lifecycle stubs, and inline documentation.

Project Structure

├── src/
│   └── pocket.ts          # The entire framework (~100 lines)
├── tests/
│   ├── pocket.test.ts     # 14 tests, ~99% coverage
│   └── testNodes.ts       # Test helper nodes
├── cli/                   # Code generation CLI
│   ├── src/               # CLI logic
│   └── templates/         # Node and Flow templates
├── examples/
│   └── mcp-addition-ts/   # MCP server example
├── docs/                  # Full documentation site (MkDocs)
├── WHITEPAPER.md           # Technical whitepaper
└── CONTRIBUTING.md         # Contribution guidelines

Whitepaper

For a deeper technical discussion of the design philosophy, architecture decisions, and comparisons with other frameworks, see WHITEPAPER.md.

Contributing

We welcome contributions! See CONTRIBUTING.md for setup instructions and guidelines.

License

MIT