Merge pull request #22 from The-Pocket/feat/cursorrule

Feat/cursorrule

Author: ZebraRoy

.cursorrule

@@ -112,6 +112,18 @@ Note: To publish to npm, maintainers need to configure the `NPM_TOKEN` secret in
    - Link any related issues
    - Answer any questions or feedback during review
 
+### Creating a CursorRule
+
+To create a CursorRule to make AI agents work more effectively on the codebase:
+
+1. Visit [gitingest.com](https://gitingest.com/)
+2. Paste the link to the docs folder (e.g., https://github.com/The-Pocket/PocketFlow-Typescript/tree/main/docs) to generate content
+3. Remove the following from the generated result:
+   - All utility function files except for llm
+   - The design_pattern/multi_agent.md file
+   - All \_config.yaml and index.md files, except for docs/index.md
+4. Save the result as a CursorRule to help AI agents understand the codebase structure better
+
 ### Development Setup
 
 ```bash

README.md

@@ -23,15 +23,14 @@ A **BatchNode** extends `Node` but changes `prep()` and `exec()`:
 ### Example: Summarize a Large File
 
 ```typescript
-// Define shared storage type
 type SharedStorage = {
   data: string;
   summary?: string;
 };
 
 class MapSummaries extends BatchNode<SharedStorage> {
   async prep(shared: SharedStorage): Promise<string[]> {
-    // Suppose we have a big file; chunk it
+    // Chunk content into manageable pieces
     const content = shared.data;
     const chunks: string[] = [];
     const chunkSize = 10000;
@@ -44,27 +43,22 @@ class MapSummaries extends BatchNode<SharedStorage> {
   }
 
   async exec(chunk: string): Promise<string> {
-    // Process each chunk with LLM
     const prompt = `Summarize this chunk in 10 words: ${chunk}`;
-    const summary = await callLlm(prompt);
-    return summary;
+    return await callLlm(prompt);
   }
 
   async post(
     shared: SharedStorage,
-    prepRes: string[],
-    execRes: string[]
-  ): Promise<string | undefined> {
-    // Combine summaries
-    const combined = execRes.join("\n");
-    shared.summary = combined;
+    _: string[],
+    summaries: string[]
+  ): Promise<string> {
+    shared.summary = summaries.join("\n");
     return "default";
   }
 }
 
 // Usage
-const mapSummaries = new MapSummaries();
-const flow = new Flow(mapSummaries);
+const flow = new Flow(new MapSummaries());
 await flow.run({ data: "very long text content..." });
 ```
 
@@ -77,7 +71,6 @@ A **BatchFlow** runs a **Flow** multiple times, each time with different `params
 ### Example: Summarize Many Files
 
 ```typescript
-// Define shared storage and parameter types
 type SharedStorage = {
   files: string[];
 };
@@ -92,39 +85,28 @@ class SummarizeAllFiles extends BatchFlow<SharedStorage> {
   }
 }
 
-// Suppose we have a per-file Flow (e.g., load_file >> summarize >> reduce):
-const summarizeFile = new SummarizeFile(loadFile);
-
-// Wrap that flow into a BatchFlow:
+// Create a per-file summarization flow
+const summarizeFile = new SummarizeFile();
 const summarizeAllFiles = new SummarizeAllFiles(summarizeFile);
-await summarizeAllFiles.run(shared);
+
+await summarizeAllFiles.run({ files: ["file1.txt", "file2.txt"] });
 ```
 
 ### Under the Hood
 
-1. `prep(shared)` returns a list of param dicts—e.g., `[{filename: "file1.txt"}, {filename: "file2.txt"}, ...]`.
-2. The **BatchFlow** loops through each dict. For each one:
-   - It merges the dict with the BatchFlow's own `params`.
-   - It calls `flow.run(shared)` using the merged result.
-3. This means the sub-Flow is run **repeatedly**, once for every param dict.
+1. `prep(shared)` returns a list of param objects—e.g., `[{filename: "file1.txt"}, {filename: "file2.txt"}, ...]`.
+2. The **BatchFlow** loops through each object and:
+   - Merges it with the BatchFlow's own `params`
+   - Calls `flow.run(shared)` using the merged result
+3. This means the sub-Flow runs **repeatedly**, once for every param object.
 
 ---
 
-## 3. Nested or Multi-Level Batches
-
-You can nest a **BatchFlow** in another **BatchFlow**. For instance:
-
-- **Outer** batch: returns a list of directory param dicts (e.g., `{"directory": "/pathA"}`, `{"directory": "/pathB"}`, ...).
-- **Inner** batch: returning a list of per-file param dicts.
+## 3. Nested Batches
 
-At each level, **BatchFlow** merges its own param dict with the parent's. By the time you reach the **innermost** node, the final `params` is the merged result of **all** parents in the chain. This way, a nested structure can keep track of the entire context (e.g., directory + file name) at once.
+You can nest BatchFlows to handle hierarchical data processing:
 
 ```typescript
-// Define shared storage and parameter types
-type SharedStorage = {
-  [key: string]: any;
-};
-
 type DirectoryParams = {
   directory: string;
 };
@@ -136,30 +118,28 @@ type FileParams = DirectoryParams & {
 class FileBatchFlow extends BatchFlow<SharedStorage> {
   async prep(shared: SharedStorage): Promise<FileParams[]> {
     const directory = this._params.directory;
-    // Get files from the directory
     const files = await getFilesInDirectory(directory).filter((f) =>
       f.endsWith(".txt")
     );
 
     return files.map((filename) => ({
-      directory, // Pass on the directory from parent
-      filename, // Add the filename for this batch item
+      directory, // Pass on directory from parent
+      filename, // Add filename for this batch item
     }));
   }
 }
 
 class DirectoryBatchFlow extends BatchFlow<SharedStorage> {
   async prep(shared: SharedStorage): Promise<DirectoryParams[]> {
-    const directories = ["/path/to/dirA", "/path/to/dirB"];
-    return directories.map((directory) => ({
+    return ["/path/to/dirA", "/path/to/dirB"].map((directory) => ({
       directory,
     }));
   }
 }
 
-// MapSummaries will have params like {"directory": "/path/to/dirA", "filename": "file1.txt"}
-const mapSummaries = new MapSummaries();
-const innerFlow = new FileBatchFlow(mapSummaries);
-const outerFlow = new DirectoryBatchFlow(innerFlow);
-await outerFlow.run({});
+// Process all files in all directories
+const processingNode = new ProcessingNode();
+const fileFlow = new FileBatchFlow(processingNode);
+const dirFlow = new DirectoryBatchFlow(fileFlow);
+await dirFlow.run({});
 ```

docs/core_abstraction/batch.md

@@ -56,62 +56,53 @@ When an exception occurs in `exec()`, the Node automatically retries until:
 
 You can get the current retry times (0-based) from `this.currentRetry`.
 
-```typescript
-class RetryNode extends Node {
-  exec(prepRes: unknown): unknown {
-    console.log(`Retry ${this.currentRetry} times`);
-    throw new Error("Failed");
-  }
-}
-```
-
 ### Graceful Fallback
 
 To **gracefully handle** the exception (after all retries) rather than raising it, override:
 
 ```typescript
 execFallback(prepRes: unknown, error: Error): unknown {
-    throw error;
+  return "There was an error processing your request.";
 }
 ```
 
-By default, it just re-raises exception. But you can return a fallback result instead, which becomes the `execRes` passed to `post()`.
+By default, it just re-raises the exception.
 
 ### Example: Summarize file
 
 ```typescript
-class SummarizeFile extends Node {
-  prep(shared: unknown): string {
-    return shared["data"];
+type SharedStore = {
+  data: string;
+  summary?: string;
+};
+
+class SummarizeFile extends Node<SharedStore> {
+  prep(shared: SharedStore): string {
+    return shared.data;
   }
 
-  exec(prepRes: string): string {
-    if (!prepRes) {
-      return "Empty file content";
-    }
-    const prompt = `Summarize this text in 10 words: ${prepRes}`;
-    const summary = callLlm(prompt); // might fail
-    return summary;
+  exec(content: string): string {
+    if (!content) return "Empty file content";
+
+    const prompt = `Summarize this text in 10 words: ${content}`;
+    return callLlm(prompt);
   }
 
-  execFallback(prepRes: string, error: Error): string {
-    // Provide a simple fallback instead of crashing
+  execFallback(_: string, error: Error): string {
     return "There was an error processing your request.";
   }
 
-  post(shared: unknown, prepRes: string, execRes: string): Action | undefined {
-    shared["summary"] = execRes;
-    // Return "default" by not returning anything
-    return undefined;
+  post(shared: SharedStore, _: string, summary: string): string | undefined {
+    shared.summary = summary;
+    return undefined; // "default" action
   }
 }
 
-const summarizeNode = new SummarizeFile(3); // maxRetries = 3
-
-// node.run() calls prep->exec->post
-// If exec() fails, it retries up to 3 times before calling execFallback()
-const actionResult = summarizeNode.run(shared);
+// Example usage
+const node = new SummarizeFile(3); // maxRetries = 3
+const shared: SharedStore = { data: "Long text to summarize..." };
+const action = node.run(shared);
 
-console.log("Action returned:", actionResult); // undefined
-console.log("Summary stored:", shared["summary"]);
+console.log("Action:", action);
+console.log("Summary:", shared.summary);
 ```