diff --git a/.cursorrules b/.cursorrules index c9642d5..13b5dd4 100644 --- a/.cursorrules +++ b/.cursorrules @@ -1,6 +1,3 @@ -================================================ -File: docs/guide.md -================================================ --- layout: default title: "Agentic Coding" @@ -25,22 +22,37 @@ Agentic Coding should be a collaboration between Human System Design and Agent I | 6. Optimization | ★★☆ Medium | ★★☆ Medium | Humans evaluate the results, and the AI helps optimize. | | 7. Reliability | ★☆☆ Low | ★★★ High | The AI writes test cases and addresses corner cases. | -1. **Requirements**: Clarify the requirements for your project, and evaluate whether an AI system is a good fit. AI systems are: - - suitable for routine tasks that require common sense (e.g., filling out forms, replying to emails). - - suitable for creative tasks where all inputs are provided (e.g., building slides, writing SQL). - - **NOT** suitable for tasks that are highly ambiguous and require complex info (e.g., building a startup). - - > **If Humans can’t specify it, AI Agents can’t automate it!** Before building an LLM system, thoroughly understand the problem by manually solving example inputs to develop intuition. - {: .best-practice } - +1. **Requirements**: Clarify the requirements for your project, and evaluate whether an AI system is a good fit. + - Understand AI systems' strengths and limitations: + - **Good for**: Routine tasks requiring common sense (filling forms, replying to emails) + - **Good for**: Creative tasks with well-defined inputs (building slides, writing SQL) + - **Not good for**: Ambiguous problems requiring complex decision-making (business strategy, startup planning) + - **Keep It User-Centric:** Explain the "problem" from the user's perspective rather than just listing features. + - **Balance complexity vs. impact**: Aim to deliver the highest value features with minimal complexity early. 2. **Flow Design**: Outline at a high level, describe how your AI system orchestrates nodes. - Identify applicable design patterns (e.g., [Map Reduce](./design_pattern/mapreduce.md), [Agent](./design_pattern/agent.md), [RAG](./design_pattern/rag.md)). + - For each node in the flow, start with a high-level one-line description of what it does. + - If using **Map Reduce**, specify how to map (what to split) and how to reduce (how to combine). + - If using **Agent**, specify what are the inputs (context) and what are the possible actions. + - If using **RAG**, specify what to embed, noting that there's usually both offline (indexing) and online (retrieval) workflows. - Outline the flow and draw it in a mermaid diagram. For example: ```mermaid flowchart LR - firstNode[First Node] --> secondNode[Second Node] - secondNode --> thirdNode[Third Node] + start[Start] --> batch[Batch] + batch --> check[Check] + check -->|OK| process + check -->|Error| fix[Fix] + fix --> check + + subgraph process[Process] + step1[Step 1] --> step2[Step 2] + end + + process --> endNode[End] ``` + - > **If Humans can't specify the flow, AI Agents can't automate it!** Before building an LLM system, thoroughly understand the problem and potential solution by manually solving example inputs to develop intuition. + {: .best-practice } 3. **Utilities**: Based on the Flow Design, identify and implement necessary utility functions. - Think of your AI system as the brain. It needs a body—these *external utility functions*—to interact with the real world: @@ -60,10 +72,23 @@ Agentic Coding should be a collaboration between Human System Design and Agent I {: .best-practice } 4. **Node Design**: Plan how each node will read and write data, and use utility functions. - - Start with the shared data design + - One core design principle for PocketFlow is to use a shared store, so start with a shared store design: - For simple systems, use an in-memory dictionary. - For more complex systems or when persistence is required, use a database. - - **Don't Repeat Yourself"**: Use in-memory references or foreign keys. + - **Don't Repeat Yourself**: Use in-memory references or foreign keys. + - Example shared store design: + ```python + shared = { + "user": { + "id": "user123", + "context": { # Another nested dict + "weather": {"temp": 72, "condition": "sunny"}, + "location": "San Francisco" + } + }, + "results": {} # Empty dict to store outputs + } + ``` - For each node, describe its type, how it reads and writes data, and which utility function it uses. Keep it specific but high-level without codes. For example: - `type`: Regular (or Batch, or Async) - `prep`: Read "text" from the shared store @@ -71,8 +96,8 @@ Agentic Coding should be a collaboration between Human System Design and Agent I - `post`: Write "embedding" to the shared store 5. **Implementation**: Implement the initial nodes and flows based on the design. - - 🎉 If you’ve reached this step, humans have finished the design. Now *Agentic Coding* begins! - - **“Keep it simple, stupid!”** Avoid complex features and full-scale type checking. + - 🎉 If you've reached this step, humans have finished the design. Now *Agentic Coding* begins! + - **"Keep it simple, stupid!"** Avoid complex features and full-scale type checking. - **FAIL FAST**! Avoid `try` logic so you can quickly identify any weak points in the system. - Add logging throughout the code to facilitate debugging. @@ -83,7 +108,7 @@ Agentic Coding should be a collaboration between Human System Design and Agent I - **Prompt Engineering**: Use clear, specific instructions with examples to reduce ambiguity. - **In-Context Learning**: Provide robust examples for tasks that are difficult to specify with instructions alone. - - > **You’ll likely iterate a lot!** Expect to repeat Steps 3–6 hundreds of times. + - > **You'll likely iterate a lot!** Expect to repeat Steps 3–6 hundreds of times. > >
{: .best-practice } @@ -110,10 +135,10 @@ my_project/ - **`docs/design.md`**: Contains project documentation for each step above. This should be high-level and no-code. - **`utils/`**: Contains all utility functions. - - It’s recommended to dedicate one Python file to each API call, for example `call_llm.py` or `search_web.py`. + - It's recommended to dedicate one Python file to each API call, for example `call_llm.py` or `search_web.py`. - Each file should also include a `main()` function to try that API call - **`flow.py`**: Implements the system's flow, starting with node definitions followed by the overall structure. -- **`main.py`**: Serves as the project’s entry point. +- **`main.py`**: Serves as the project's entry point. ================================================ File: docs/index.md @@ -136,7 +161,6 @@ A [100-line](https://github.com/the-pocket/PocketFlow/blob/main/pocketflow/__ini - ## Core Abstraction We model the LLM workflow as a **Graph + Shared Store**: @@ -304,7 +328,6 @@ flow.run(shared) A **BatchFlow** runs a **Flow** multiple times, each time with different `params`. Think of it as a loop that replays the Flow for each parameter set. - ### Example: Summarize Many Files ```python @@ -358,7 +381,6 @@ inner_flow = FileBatchFlow(start=MapSummaries()) outer_flow = DirectoryBatchFlow(start=inner_flow) ``` - ================================================ File: docs/core_abstraction/communication.md ================================================ @@ -1069,7 +1091,6 @@ print("Individual Summaries:", shared["file_summaries"]) print("\nFinal Summary:\n", shared["all_files_summary"]) ``` - ================================================ File: docs/design_pattern/multi_agent.md ================================================ @@ -1543,7 +1564,6 @@ dialogue: | - No need to escape interior quotes—just place the entire text under a block literal (`|`). - Newlines are naturally preserved without needing `\n`. - ================================================ File: docs/design_pattern/workflow.md ================================================ @@ -1601,7 +1621,6 @@ writing_flow.run(shared) For *dynamic cases*, consider using [Agents](./agent.md). - ================================================ File: docs/utility_function/chunking.md ================================================ @@ -1660,7 +1679,6 @@ However, might not handle very long sentences or paragraphs well. - **Semantic**: Use embeddings or topic modeling to chunk by semantic boundaries. - **Agentic**: Use an LLM to decide chunk boundaries based on context or meaning. - ================================================ File: docs/utility_function/embedding.md ================================================ @@ -2300,7 +2318,6 @@ def build_mermaid(start): ``` {% endraw %} - For example, suppose we have a complex Flow for data science: ```python @@ -2396,7 +2413,6 @@ data_science_flow.run({}) The output would be: `Call stack: ['EvaluateModelNode', 'ModelFlow', 'DataScienceFlow']` - ================================================ File: docs/utility_function/websearch.md ================================================ @@ -2563,4 +2579,4 @@ callouts: nav: - Home: index.md # Link to your main docs index - GitHub: "https://github.com/the-pocket/PocketFlow" - - Discord: "https://discord.gg/hUHHE9Sa6T" + - Discord: "https://discord.gg/hUHHE9Sa6T" \ No newline at end of file diff --git a/docs/guide.md b/docs/guide.md index 04dabc7..ea14bbf 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -22,22 +22,37 @@ Agentic Coding should be a collaboration between Human System Design and Agent I | 6. Optimization | ★★☆ Medium | ★★☆ Medium | Humans evaluate the results, and the AI helps optimize. | | 7. Reliability | ★☆☆ Low | ★★★ High | The AI writes test cases and addresses corner cases. | -1. **Requirements**: Clarify the requirements for your project, and evaluate whether an AI system is a good fit. AI systems are: - - suitable for routine tasks that require common sense (e.g., filling out forms, replying to emails). - - suitable for creative tasks where all inputs are provided (e.g., building slides, writing SQL). - - **NOT** suitable for tasks that are highly ambiguous and require complex info (e.g., building a startup). - - > **If Humans can’t specify it, AI Agents can’t automate it!** Before building an LLM system, thoroughly understand the problem by manually solving example inputs to develop intuition. - {: .best-practice } - +1. **Requirements**: Clarify the requirements for your project, and evaluate whether an AI system is a good fit. + - Understand AI systems' strengths and limitations: + - **Good for**: Routine tasks requiring common sense (filling forms, replying to emails) + - **Good for**: Creative tasks with well-defined inputs (building slides, writing SQL) + - **Not good for**: Ambiguous problems requiring complex decision-making (business strategy, startup planning) + - **Keep It User-Centric:** Explain the "problem" from the user's perspective rather than just listing features. + - **Balance complexity vs. impact**: Aim to deliver the highest value features with minimal complexity early. 2. **Flow Design**: Outline at a high level, describe how your AI system orchestrates nodes. - Identify applicable design patterns (e.g., [Map Reduce](./design_pattern/mapreduce.md), [Agent](./design_pattern/agent.md), [RAG](./design_pattern/rag.md)). + - For each node in the flow, start with a high-level one-line description of what it does. + - If using **Map Reduce**, specify how to map (what to split) and how to reduce (how to combine). + - If using **Agent**, specify what are the inputs (context) and what are the possible actions. + - If using **RAG**, specify what to embed, noting that there's usually both offline (indexing) and online (retrieval) workflows. - Outline the flow and draw it in a mermaid diagram. For example: ```mermaid flowchart LR - firstNode[First Node] --> secondNode[Second Node] - secondNode --> thirdNode[Third Node] + start[Start] --> batch[Batch] + batch --> check[Check] + check -->|OK| process + check -->|Error| fix[Fix] + fix --> check + + subgraph process[Process] + step1[Step 1] --> step2[Step 2] + end + + process --> endNode[End] ``` + - > **If Humans can't specify the flow, AI Agents can't automate it!** Before building an LLM system, thoroughly understand the problem and potential solution by manually solving example inputs to develop intuition. + {: .best-practice } 3. **Utilities**: Based on the Flow Design, identify and implement necessary utility functions. - Think of your AI system as the brain. It needs a body—these *external utility functions*—to interact with the real world: @@ -57,10 +72,23 @@ Agentic Coding should be a collaboration between Human System Design and Agent I {: .best-practice } 4. **Node Design**: Plan how each node will read and write data, and use utility functions. - - Start with the shared data design + - One core design principle for PocketFlow is to use a shared store, so start with a shared store design: - For simple systems, use an in-memory dictionary. - For more complex systems or when persistence is required, use a database. - - **Don't Repeat Yourself"**: Use in-memory references or foreign keys. + - **Don't Repeat Yourself**: Use in-memory references or foreign keys. + - Example shared store design: + ```python + shared = { + "user": { + "id": "user123", + "context": { # Another nested dict + "weather": {"temp": 72, "condition": "sunny"}, + "location": "San Francisco" + } + }, + "results": {} # Empty dict to store outputs + } + ``` - For each node, describe its type, how it reads and writes data, and which utility function it uses. Keep it specific but high-level without codes. For example: - `type`: Regular (or Batch, or Async) - `prep`: Read "text" from the shared store @@ -68,8 +96,8 @@ Agentic Coding should be a collaboration between Human System Design and Agent I - `post`: Write "embedding" to the shared store 5. **Implementation**: Implement the initial nodes and flows based on the design. - - 🎉 If you’ve reached this step, humans have finished the design. Now *Agentic Coding* begins! - - **“Keep it simple, stupid!”** Avoid complex features and full-scale type checking. + - 🎉 If you've reached this step, humans have finished the design. Now *Agentic Coding* begins! + - **"Keep it simple, stupid!"** Avoid complex features and full-scale type checking. - **FAIL FAST**! Avoid `try` logic so you can quickly identify any weak points in the system. - Add logging throughout the code to facilitate debugging. @@ -80,7 +108,7 @@ Agentic Coding should be a collaboration between Human System Design and Agent I - **Prompt Engineering**: Use clear, specific instructions with examples to reduce ambiguity. - **In-Context Learning**: Provide robust examples for tasks that are difficult to specify with instructions alone. - - > **You’ll likely iterate a lot!** Expect to repeat Steps 3–6 hundreds of times. + - > **You'll likely iterate a lot!** Expect to repeat Steps 3–6 hundreds of times. > >
{: .best-practice } @@ -107,7 +135,7 @@ my_project/ - **`docs/design.md`**: Contains project documentation for each step above. This should be high-level and no-code. - **`utils/`**: Contains all utility functions. - - It’s recommended to dedicate one Python file to each API call, for example `call_llm.py` or `search_web.py`. + - It's recommended to dedicate one Python file to each API call, for example `call_llm.py` or `search_web.py`. - Each file should also include a `main()` function to try that API call - **`flow.py`**: Implements the system's flow, starting with node definitions followed by the overall structure. -- **`main.py`**: Serves as the project’s entry point. +- **`main.py`**: Serves as the project's entry point.