# neilblaze/pocketflow architecture

> Architecture diagram of the GitHub repository neilblaze/pocketflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/neilblaze/pocketflow
- Repository: https://github.com/neilblaze/pocketflow

## Overview

##### Project type and purpose
- This is a Python-based, minimalist LLM framework (Pocket Flow) packaged as a library plus an extensive “cookbook” of example applications.
- Purpose: provide a 100-line core Graph abstraction for composing LLM-powered flows (agents, workflows, RAG, map-reduce, etc.), accompanied by tutorials, tests, and documentation.

##### File structure
- Top level:
- pocketflow/               ← core library (100-line Graph abstraction)
- setup.py                  ← install entrypoint
- cookbook/                 ← dozens of “demo” sub-projects, each with flow.py, main.py, nodes.py, utils.py, requirements.txt
- docs/                     ← static documentation site (MkDocs / Jekyll)
- tests/                    ← pytest suite exercising core flows, nodes, fallbacks
- README.md, LICENSE, .gitignore
- Patterns:
- Core Graph engine in pocketflow/__init__.py
- Example flows import pocketflow.* and define their own Flow, Node classes
- Utilities folder per demo for LLM calls, embeddings, vector indexes, PDF parsing, database tools, etc.
- docs/core_abstraction, docs/design_pattern, docs/utility_function show high-level patterns
- Tests import sample flows and assert behavior end-to-end

##### README for additional insights
- Emphasis on:
- Zero dependencies beyond Python stdlib
- Core abstraction = Graph
- Implements multi-agent, workflow, RAG, map-reduce, streaming, memory, supervisor, parallel patterns
- Links to images illustrating abstraction → a node graph that describes directed data flows

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Library"
        GraphEngine["Graph Engine"]:::core
        FlowRunner["Flow Runner"]:::core
        NodeInterface["Node Interface"]:::core
    end

    subgraph "Install"
        Setup["setup.py"]:::core
    end

    subgraph "Cookbook Examples"
        FlowDef["Flow Definitions"]:::examples
        NodeImpl["Node Implementations"]:::examples
        EntryPoint["Entrypoint Script"]:::examples
        UtilsFile["Single-file Utils"]:::utils
        UtilsPkg["Package-style Utils"]:::utils
    end

    subgraph "External Services"
        LLM["LLM Providers"]:::external
        Vector["Vector Stores"]:::external
        OtherTools["Other Tools"]:::external
    end

    Docs["Documentation Site"]:::docs
    Tests["Test Suite"]:::tests

    FlowDef -->|imports| GraphEngine
    FlowDef -->|imports| NodeInterface
    EntryPoint -->|runs| FlowRunner
    FlowRunner -->|executes| NodeInterface
    NodeInterface -->|uses| UtilsFile
    NodeInterface -->|uses| UtilsPkg
    UtilsFile -->|calls| LLM
    UtilsFile -->|calls| Vector
    UtilsFile -->|calls| OtherTools
    Docs -.->|references| GraphEngine
    Docs -.->|references| FlowRunner
    Docs -.->|references| NodeInterface
    Tests -->|imports| FlowDef
    Tests -->|runs| FlowRunner

    click GraphEngine "https://github.com/neilblaze/pocketflow/blob/main/pocketflow/__init__.py"
    click Setup "https://github.com/neilblaze/pocketflow/blob/main/setup.py"
    click FlowDef "https://github.com/neilblaze/pocketflow/blob/main/cookbook/*/flow.py"
    click NodeImpl "https://github.com/neilblaze/pocketflow/blob/main/cookbook/*/nodes.py"
    click EntryPoint "https://github.com/neilblaze/pocketflow/blob/main/cookbook/*/main.py"
    click UtilsFile "https://github.com/neilblaze/pocketflow/blob/main/cookbook/*/utils.py"
    click UtilsPkg "https://github.com/neilblaze/pocketflow/blob/main/cookbook/*/utils/__init__.py"
    click Docs "https://github.com/neilblaze/pocketflow/tree/main/docs/"
    click Tests "https://github.com/neilblaze/pocketflow/tree/main/tests/"

    classDef core fill:#D0E6FF,stroke:#0044CC,color:#0044CC
    classDef examples fill:#E6FFE6,stroke:#00CC00,color:#00AA00
    classDef utils fill:#FFF7CC,stroke:#CCA300,color:#CCA300
    classDef external fill:#FFE6CC,stroke:#CC6600,color:#CC6600
    classDef docs fill:#F0F0F0,stroke:#888,color:#888
    classDef tests fill:#F0F0F0,stroke:#888,color:#888
```
