phowell
/
pocketflow
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update rule

This commit is contained in:
zachary62 2025-03-20 00:10:24 -04:00
parent a06d697537
commit 2509b42dd8
2 changed files with 89 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
.cursorrules
View File

@ -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.
>
> <div align="center"><img src="https://github.com/the-pocket/PocketFlow/raw/main/assets/success.png?raw=true" width="400"/></div>
{: .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
<img src="https://github.com/the-pocket/PocketFlow/raw/main/assets/meme.jpg?raw=true" width="400"/>
</div>
## 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"

60
docs/guide.md
View File

@ -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.
>
> <div align="center"><img src="https://github.com/the-pocket/PocketFlow/raw/main/assets/success.png?raw=true" width="400"/></div>
{: .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.