<<<<<<< HEAD

Search-Answer System

A 3-node AI system built with PocketFlow that intelligently decides whether to search for information or answer questions directly.

System Overview

The system consists of three main nodes:

1. DecideNode: Analyzes the user's question and decides whether to search for more information or answer directly
2. SearchNode: Performs web searches using DuckDuckGo when more information is needed
3. AnswerNode: Provides the final answer based on the question and any search results

Flow Diagram

flowchart TD
    A[DecideNode] -->|search| B[SearchNode]
    A -->|answer| C[AnswerNode]
    B -->|decide| A
    C -->|complete| D[End]

Loading

Setup

1. Create Virtual Environment

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install Dependencies

pip install -r requirements.txt

3. Set Environment Variables

You need to set your OpenAI API key:

export OPENAI_API_KEY="your-openai-api-key-here"

4. Run the System

Interactive Mode

source venv/bin/activate  # Ensure virtual environment is activated
python main.py

Command Line Mode

source venv/bin/activate  # Ensure virtual environment is activated
python main.py "What is the weather like in New York today?"

Example Usage

Example 1: Current Information (Will Search)

python main.py "Who won the Nobel Prize in Physics 2024?"

The system will:

1. Decide to search for current information
2. Search for Nobel Prize 2024 information
3. Provide an answer based on search results

Example 2: General Knowledge (May Answer Directly)

python main.py "What is the capital of France?"

The system may:

1. Decide it has enough knowledge to answer directly
2. Provide the answer without searching

System Architecture

Utility Functions

• utils/call_llm.py: OpenAI GPT API wrapper
• utils/search_web.py: DuckDuckGo search functionality

Nodes

• DecideNode: Uses LLM to decide whether to search or answer
• SearchNode: Performs web searches and stores results
• AnswerNode: Generates final answers using LLM

Flow Control

The system uses action-based transitions:

• "search": DecideNode → SearchNode
• "answer": DecideNode → AnswerNode
• "decide": SearchNode → DecideNode (for re-evaluation)

Key Features

• Intelligent Decision Making: The system analyzes questions to determine if current information is needed
• Search Loop: Can perform multiple searches if initial results are insufficient
• Context Preservation: Maintains search history for better decision making
• Error Handling: Includes retries and fallback mechanisms
• Structured Output: Uses YAML for reliable LLM response parsing

Customization

You can modify the behavior by:

1. Adjusting Node Parameters: Change max_retries and wait times in flow.py
2. Modifying Search Results: Change max_results in utils/search_web.py
3. Updating Prompts: Modify the decision logic in DecideNode.exec()
4. Changing Models: Update the model in utils/call_llm.py

Troubleshooting

Common Issues

1. Missing API Key: Ensure OPENAI_API_KEY is set
2. Rate Limits: The system includes retry logic with waits
3. Network Issues: DuckDuckGo search has error handling
4. Parsing Errors: YAML parsing includes fallback mechanisms

Debug Mode

To see detailed flow execution, you can add logging or print statements to the nodes.

Project Structure

.
├── utils/
│   ├── __init__.py
│   ├── call_llm.py          # OpenAI API wrapper
│   └── search_web.py        # DuckDuckGo search
├── nodes.py                 # Node definitions
├── flow.py                  # Flow creation
├── main.py                  # Main entry point
├── requirements.txt         # Dependencies
└── README.md               # This file

Contributing

This system follows the PocketFlow framework guidelines for agentic coding. When making changes:

1. Keep utility functions simple and testable
2. Maintain clear separation between data (shared store) and compute (nodes)
3. Use structured outputs for reliable LLM interactions
4. Include error handling and retries for robust operation

=======

upstream/main

English | 中文 | Español | 日本語 | Deutsch | Русский | Português | Français | 한국어

Pocket Flow is a 100-line minimalist LLM framework

• Lightweight: Just 100 lines. Zero bloat, zero dependencies, zero vendor lock-in.

• Expressive: Everything you love—(Multi-)Agents, Workflow, RAG, and more.

• Agentic Coding: Let AI Agents (e.g., Cursor AI) build Agents—10x productivity boost!

Get started with Pocket Flow:

• To install, pip install pocketflowor just copy the source code (only 100 lines).
• To learn more, check out the documentation. To learn the motivation, read the story.
• Have questions? Check out this AI Assistant, or create an issue!
• 🎉 Join our Discord to connect with other developers building with Pocket Flow!
• 🎉 Pocket Flow is initially Python, but we now have Typescript, Java, C++ and Go versions!

Why Pocket Flow?

Current LLM frameworks are bloated... You only need 100 lines for LLM Framework!

	Abstraction	App-Specific Wrappers	Vendor-Specific Wrappers	Lines	Size
LangChain	Agent, Chain	Many (e.g., QA, Summarization)	Many (e.g., OpenAI, Pinecone, etc.)	405K	+166MB
CrewAI	Agent, Chain	Many (e.g., FileReadTool, SerperDevTool)	Many (e.g., OpenAI, Anthropic, Pinecone, etc.)	18K	+173MB
SmolAgent	Agent	Some (e.g., CodeAgent, VisitWebTool)	Some (e.g., DuckDuckGo, Hugging Face, etc.)	8K	+198MB
LangGraph	Agent, Graph	Some (e.g., Semantic Search)	Some (e.g., PostgresStore, SqliteSaver, etc.)	37K	+51MB
AutoGen	Agent	Some (e.g., Tool Agent, Chat Agent)	Many [Optional] (e.g., OpenAI, Pinecone, etc.)	7K (core-only)	+26MB (core-only)
PocketFlow	Graph	None	None	100	+56KB

How does Pocket Flow work?

The 100 lines capture the core abstraction of LLM frameworks: Graph!

From there, it's easy to implement popular design patterns like (Multi-)Agents, Workflow, RAG, etc.

✨ Below are basic tutorials:

Name	Difficulty	Description
Chat	☆☆☆ Dummy	A basic chat bot with conversation history
Structured Output	☆☆☆ Dummy	Extracting structured data from resumes by prompting
Workflow	☆☆☆ Dummy	A writing workflow that outlines, writes content, and applies styling
Agent	☆☆☆ Dummy	A research agent that can search the web and answer questions
RAG	☆☆☆ Dummy	A simple Retrieval-augmented Generation process
Batch	☆☆☆ Dummy	A batch processor that translates markdown into multiple languages
Streaming	☆☆☆ Dummy	A real-time LLM streaming demo with user interrupt capability
Chat Guardrail	☆☆☆ Dummy	A travel advisor chatbot that only processes travel-related queries
Majority Vote	☆☆☆ Dummy	Improve reasoning accuracy by aggregating multiple solution attempts
Map-Reduce	☆☆☆ Dummy	Batch resume qualification using map-reduce pattern
CLI HITL	☆☆☆ Dummy	A command-line joke generator with human-in-the-loop feedback
Multi-Agent	★☆☆ Beginner	A Taboo word game for async communication between 2 agents
Supervisor	★☆☆ Beginner	Research agent is getting unreliable... Let's build a supervision process
Parallel	★☆☆ Beginner	A parallel execution demo that shows 3x speedup
Parallel Flow	★☆☆ Beginner	A parallel image processing showing 8x speedup
Thinking	★☆☆ Beginner	Solve complex reasoning problems through Chain-of-Thought
Memory	★☆☆ Beginner	A chat bot with short-term and long-term memory
Text2SQL	★☆☆ Beginner	Convert natural language to SQL queries with an auto-debug loop
Code Generator	★☆☆ Beginner	Generate test cases, implement solutions, and iteratively improve code
MCP	★☆☆ Beginner	Agent using Model Context Protocol for numerical operations
A2A	★☆☆ Beginner	Agent wrapped with A2A protocol for inter-agent communication
Streamlit FSM	★☆☆ Beginner	Streamlit app with finite state machine for HITL image generation
FastAPI WebSocket	★☆☆ Beginner	Real-time chat interface with streaming LLM responses via WebSocket
FastAPI Background	★☆☆ Beginner	FastAPI app with background jobs and real-time progress via SSE
Voice Chat	★☆☆ Beginner	An interactive voice chat application with VAD, STT, LLM, and TTS.

👀 Want to see other tutorials for dummies? Create an issue!

How to Use Pocket Flow?

🚀 Through Agentic Coding—the fastest LLM App development paradigm-where humans design and agents code!

✨ Below are examples of more complex LLM Apps:

App Name	Difficulty	Topics	Human Design	Agent Code
Website Chatbot Turn your website into a 24/7 customer support genius	★★☆ Medium	Agent RAG	Design Doc	Flow Code
Danganronpa Simulator Forget the Turing test. Danganronpa, the ultimate AI experiment!	★★★ Advanced	Workflow Agent	Design Doc	Flow Code
Codebase Knowledge Builder Life's too short to stare at others' code in confusion	★★☆ Medium	Workflow	Design Doc	Flow Code
Build Cursor with Cursor We'll reach the singularity soon ...	★★★ Advanced	Agent	Design Doc	Flow Code
Ask AI Paul Graham Ask AI Paul Graham, in case you don't get in	★★☆ Medium	RAG Map Reduce TTS	Design Doc	Flow Code
Youtube Summarizer Explain YouTube Videos to you like you're 5	★☆☆ Beginner	Map Reduce	Design Doc	Flow Code
Cold Opener Generator Instant icebreakers that turn cold leads hot	★☆☆ Beginner	Map Reduce Web Search	Design Doc	Flow Code

• Want to learn Agentic Coding?

  • Check out my YouTube for video tutorial on how some apps above are made!

  • Want to build your own LLM App? Read this post! Start with this template!