Pocket Flow Python Project Template

When building an agentic workflow in this template, you should follow a structured design process involving three main layers:

1. Flow Design: Define the high-level workflow and applicable design patterns (e.g., Map-Reduce, RAG, Agentic workflows). Use Mermaid diagrams to visualize the sequence of nodes.
2. Utility Functions: Identify or define reusable functions (like LLM calls or embeddings) that nodes will consume.
3. Node Design: Define individual nodes, specifying their purpose, execution type (Regular, Batch, or Async), and their interaction with the Shared Store.

Each node follows a lifecycle of prep (reading from the shared store), exec (performing the core logic/utility call), and post (writing results back to the shared store).

When designing a node, you must choose the appropriate execution type based on the workload:

• Regular: Standard sequential execution.
• Batch: For processing multiple items at once.
• Async: For non-blocking or concurrent operations.

The shared store is a centralized dictionary used to pass data between nodes in a flow. To minimize redundancy, nodes should read necessary inputs during their prep step and write their outputs during their post step.

Example structure:

shared = {
    "key": "value"
}

The template includes specialized rule files to optimize the performance of different AI coding assistants. To use these, ensure the corresponding file exists in your project root so the assistant can follow the project-specific instructions:

• Cursor AI: Uses .cursorrules
• Cline: Uses .clinerules
• Windsurf: Uses .windsurfrules
• Goose: Uses .goosehints
• Claude Code: Uses CLAUDE.md
• Gemini: Uses GEMINI.md
• GitHub Copilot: Uses configuration located in the .github directory.

To build a QA application, use create_qa_flow() to instantiate a flow and then call .run(shared) passing a dictionary containing the input state. The shared dictionary acts as the state container that is mutated by the flow during execution. For a QA flow, the dictionary should include a question key (string) and an answer key (initialized to None).

from flow import create_qa_flow

# Define the shared state
shared = {
    "question": "In one sentence, what's the end of universe?",
    "answer": None
}

# Initialize and execute the flow
qa_flow = create_qa_flow()
qa_flow.run(shared)

# Access the mutated state
print("Question:", shared["question"])
print("Answer:", shared["answer"])