From c994440ba98c373ccdc193ded77d4b28e92cab5a Mon Sep 17 00:00:00 2001
From: Vighnesh Ise <137636878+vighnesh-xi@users.noreply.github.com>
Date: Thu, 6 Aug 2026 02:42:23 +0530
Subject: [PATCH] updated README

---
 cookbook/pocketflow-rag/README.md | 127 +++++++++++++++++++-----------
 1 file changed, 83 insertions(+), 44 deletions(-)

diff --git a/cookbook/pocketflow-rag/README.md b/cookbook/pocketflow-rag/README.md
index a0182b82..1e32fc12 100644
--- a/cookbook/pocketflow-rag/README.md
+++ b/cookbook/pocketflow-rag/README.md
@@ -1,66 +1,100 @@
 # Retrieval Augmented Generation (RAG)
 
-This project demonstrates a simplified RAG system that retrieves relevant documents based on user queries and generates answers using an LLM. This implementation is based directly on the tutorial: [Retrieval Augmented Generation (RAG) from Scratch — Tutorial For Dummies](https://zacharyhuang.substack.com/p/retrieval-augmented-generation-rag).
+This tutorial shows how to build a simple RAG system with PocketFlow. It takes a set of documents, splits them into chunks, creates embeddings, stores them in a FAISS index, and then answers user questions by retrieving the most relevant chunks first.
 
+This tutorial is based on: [Retrieval Augmented Generation (RAG) from Scratch — Tutorial For Dummies](https://zacharyhuang.substack.com/p/retrieval-augmented-generation-rag).
 
-## Features
+## What you will learn
 
-- Document chunking for processing long texts
-- FAISS-powered vector-based document retrieval
-- LLM-powered answer generation
+- How to split long documents into smaller chunks.
+- How to embed document chunks and user queries.
+- How to build a FAISS index for fast retrieval.
+- How PocketFlow separates indexing from question answering.
 
-## How to Run
+## How to run
 
-1. Set your API key:
-   ```bash
-   export OPENAI_API_KEY="your-api-key-here"
-   ```
-   Or update it directly in `utils.py`
+### 1) Set your API key
 
-   Let's do a quick check to make sure your API key is working properly:
+Set your OpenAI API key in the terminal:
 
-   ```bash
-   python utils.py
-   ```
+```bash
+export OPENAI_API_KEY="your-api-key-here"
+```
+
+If you prefer, you can update it directly in `utils.py`.
+
+To verify that your API key works, run:
+
+```bash
+python utils.py
+```
+
+### 2) Install dependencies
+
+Install the dependencies required by this tutorial:
+
+```bash
+pip install -r requirements.txt
+```
+
+### 3) Run the app
+
+Run the default example:
+
+```bash
+python main.py
+```
+
+### 4) Ask your own question
+
+After the app starts, try a question like:
 
-2. Install and run with the default query:
-   ```bash
-   pip install -r requirements.txt
-   python main.py
-   ```
+> How does the Q-Mesh protocol achieve high transaction speeds?
 
-3. Run the application with a sample query:
+If your version of `main.py` supports passing a query from the command line, use the format defined in the code. Otherwise, edit the query input in the script and run it again.
 
-   ```bash
-   python main.py --"How does the Q-Mesh protocol achieve high transaction speeds?"
-   ```
+## How it works
 
-## How It Works
+This tutorial has **two separate stages**:
 
-The magic happens through a two-phase pipeline implemented with PocketFlow:
+### Offline stage: build the index
+
+This stage runs before any question is asked.
 
 ```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
+    ChunkDocs[ChunkDocumentsNode] --> EmbedDocs[EmbedDocumentsNode] --> CreateIndex[CreateIndexNode]
 ```
 
-Here's what each part does:
-1. **ChunkDocumentsNode**: Breaks documents into smaller chunks for better retrieval
-2. **EmbedDocumentsNode**: Converts document chunks into vector representations
-3. **CreateIndexNode**: Creates a searchable FAISS index from embeddings
-4. **EmbedQueryNode**: Converts user query into the same vector space
-5. **RetrieveDocumentNode**: Finds the most similar document using vector search
-6. **GenerateAnswerNode**: Uses an LLM to generate an answer based on the retrieved content
+- **ChunkDocumentsNode**: breaks documents into smaller pieces so they are easier to search.
+- **EmbedDocumentsNode**: converts each chunk into a vector embedding.
+- **CreateIndexNode**: stores the embeddings in a FAISS index for fast similarity search.
+
+### Online stage: answer questions
 
-## Example Output
+This stage runs every time a user asks a question.
 
+```mermaid
+graph TD
+    EmbedQuery[EmbedQueryNode] --> RetrieveDoc[RetrieveDocumentNode] --> GenerateAnswer[GenerateAnswerNode]
 ```
+
+- **EmbedQueryNode**: converts the user’s question into the same vector space as the documents.
+- **RetrieveDocumentNode**: finds the most relevant chunk using vector similarity search.
+- **GenerateAnswerNode**: uses the retrieved chunk and the user’s question to generate the final answer.
+
+## Why PocketFlow helps
+
+PocketFlow keeps the tutorial simple by splitting the workflow into small nodes. That makes the RAG process easier to understand, debug, and extend.
+
+It also makes the flow structure very clear:
+
+- The **offline stage** prepares knowledge.
+- The **online stage** uses that knowledge to answer questions.
+
+## Example output
+
+```text
 ✅ Created 5 chunks from 5 documents
 ✅ Created 5 document embeddings
 🔍 Creating search index...
@@ -72,8 +106,13 @@ Here's what each part does:
         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!
-        To install, pip install pocketflow or just copy the source code (only 100 lines)."
-
+        To install, pip install pocketflow or simply copy the source code."
 🤖 Generated Answer:
-To install PocketFlow, use the command `pip install pocketflow` or simply copy its 100 lines of source code.
+To install PocketFlow, use `pip install pocketflow` or copy the source code.
 ```
+
+## Notes
+
+- Rebuild the index if the document set changes.
+- The offline stage only needs to run when your source documents change.
+- The online stage runs each time a user asks a new question.