Merge branch 'main' of https://github.com/zachary62/miniLLMFlow

docs/core_abstraction/communication.md

@@ -7,13 +7,16 @@ nav_order: 3
 
 # Communication
 
-Nodes and Flows **communicate** in two ways:
+Nodes and Flows **communicate** in 2 ways:
 
-1. **Shared Store (recommended)** 
+1. **Shared Store (for almost all the cases)** 
 
-   - A global data structure (often an in-mem dict) that all nodes can read and write by `prep()` and `post()`.  
+   - A global data structure (often an in-mem dict) that all nodes can read ( `prep()`) and write (`post()`).  
    - Great for data results, large content, or anything multiple nodes need.
    - You shall design the data structure and populate it ahead.
+     
+   - > **Separation of Concerns:** Use `Shared Store` for almost all cases to separate *Data Schema* from *Compute Logic*!  This approach is both flexible and easy to manage, resulting in more maintainable code. `Params` is more a syntax sugar for [Batch](./batch.md).
+     {: .best-practice }
 
 2. **Params (only for [Batch](./batch.md))** 
    - Each node has a local, ephemeral `params` dict passed in by the **parent Flow**, used as an identifier for tasks. Parameter keys and values shall be **immutable**.
@@ -21,9 +24,6 @@ Nodes and Flows **communicate** in two ways:
 
 If you know memory management, think of the **Shared Store** like a **heap** (shared by all function calls), and **Params** like a **stack** (assigned by the caller).
 
-> Use `Shared Store` for almost all cases. It's flexible and easy to manage. It separates *Data Schema* from *Compute Logic*, making the code easier to maintain. `Params` is more a syntax sugar for [Batch](./batch.md).
-{: .best-practice }
-
 ---
 
 ## 1. Shared Store
@@ -123,4 +123,4 @@ flow = Flow(start=node)
 # 5) Set Flow params (overwrites node params)
 flow.set_params({"filename": "doc2.txt"})
 flow.run(shared)  # The node summarizes doc2, not doc1
-```
+```

docs/guide.md

@@ -26,7 +26,7 @@ Agentic Coding should be a collaboration between Human System Design and Agent I
     - 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 a human can’t solve it, an LLM can’t automate it!** Before building an LLM system, thoroughly understand the problem by manually solving example inputs to develop intuition.  
+    - > **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 }
 
 
@@ -68,11 +68,12 @@ Agentic Coding should be a collaboration between Human System Design and Agent I
 
 
 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.
    - **FAIL FAST**! Avoid `try` logic so you can quickly identify any weak points in the system.
    - Add logging throughout the code to facilitate debugging.
 
-6. **Optimization**:
+7. **Optimization**:
    - **Use Intuition**: For a quick initial evaluation, human intuition is often a good start.
    - **Redesign Flow (Back to Step 3)**: Consider breaking down tasks further, introducing agentic decisions, or better managing input contexts.
    - If your flow design is already solid, move on to micro-optimizations:
@@ -84,7 +85,7 @@ Agentic Coding should be a collaboration between Human System Design and Agent I
      > <div align="center"><img src="https://github.com/the-pocket/PocketFlow/raw/main/assets/success.png?raw=true" width="400"/></div>
      {: .best-practice }
 
-7. **Reliability**  
+8. **Reliability**  
    - **Node Retries**: Add checks in the node `exec` to ensure outputs meet requirements, and consider increasing `max_retries` and `wait` times.
    - **Logging and Visualization**: Maintain logs of all attempts and visualize node results for easier debugging.
    - **Self-Evaluation**: Add a separate node (powered by an LLM) to review outputs when results are uncertain.
@@ -109,4 +110,4 @@ my_project/
   - 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.