feat: add new examples from pocketflow-academy

cookbook/pocketflow-tool-embeddings/README.md

@@ -0,0 +1,86 @@
+# OpenAI Embeddings with PocketFlow
+
+This example demonstrates how to properly integrate OpenAI's text embeddings API with PocketFlow, focusing on:
+
+1. Clean code organization with separation of concerns:
+   - Tools layer for API interactions (`tools/embeddings.py`)
+   - Node implementation for PocketFlow integration (`nodes.py`)
+   - Flow configuration (`flow.py`)
+   - Centralized environment configuration (`utils/call_llm.py`)
+
+2. Best practices for API key management:
+   - Using environment variables
+   - Supporting both `.env` files and system environment variables
+   - Secure configuration handling
+
+3. Proper project structure:
+   - Modular code organization
+   - Clear separation between tools and PocketFlow components
+   - Reusable OpenAI client configuration
+
+## Project Structure
+
+```
+pocketflow-tool-embeddings/
+├── tools/
+│   └── embeddings.py     # OpenAI embeddings API wrapper
+├── utils/
+│   └── call_llm.py      # Centralized OpenAI client configuration
+├── nodes.py             # PocketFlow node implementation
+├── flow.py             # Flow configuration
+└── main.py             # Example usage
+```
+
+## Setup
+
+1. Create a virtual environment:
+```bash
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+2. Install dependencies:
+```bash
+pip install -r requirements.txt
+```
+
+3. Set up your OpenAI API key in one of two ways:
+   
+   a. Using a `.env` file:
+   ```bash
+   OPENAI_API_KEY=your_api_key_here
+   ```
+   
+   b. Or as a system environment variable:
+   ```bash
+   export OPENAI_API_KEY=your_api_key_here
+   ```
+
+## Usage
+
+Run the example:
+```bash
+python main.py
+```
+
+This will:
+1. Load the OpenAI API key from environment
+2. Create a PocketFlow node to handle embedding generation
+3. Process a sample text and generate its embedding
+4. Display the embedding dimension and first few values
+
+## Key Concepts Demonstrated
+
+1. **Environment Configuration**
+   - Secure API key handling
+   - Flexible configuration options
+
+2. **Code Organization**
+   - Clear separation between tools and PocketFlow components
+   - Reusable OpenAI client configuration
+   - Modular project structure
+
+3. **PocketFlow Integration**
+   - Node implementation with prep->exec->post lifecycle
+   - Flow configuration
+   - Shared store usage for data passing 

cookbook/pocketflow-tool-embeddings/flow.py

@@ -0,0 +1,10 @@
+from pocketflow import Flow
+from nodes import EmbeddingNode
+
+def create_embedding_flow():
+    """Create a flow for text embedding"""
+    # Create embedding node
+    embedding = EmbeddingNode()
+    
+    # Create and return flow
+    return Flow(start=embedding) 

cookbook/pocketflow-tool-embeddings/main.py

@@ -0,0 +1,22 @@
+from flow import create_embedding_flow
+
+def main():
+    # Create the flow
+    flow = create_embedding_flow()
+    
+    # Example text
+    text = "What's the meaning of life?"
+    
+    # Prepare shared data
+    shared = {"text": text}
+    
+    # Run the flow
+    flow.run(shared)
+    
+    # Print results
+    print("Text:", text)
+    print("Embedding dimension:", len(shared["embedding"]))
+    print("First 5 values:", shared["embedding"][:5])
+
+if __name__ == "__main__":
+    main()

cookbook/pocketflow-tool-embeddings/nodes.py

@@ -0,0 +1,18 @@
+from pocketflow import Node
+from tools.embeddings import get_embedding
+
+class EmbeddingNode(Node):
+    """Node for getting embeddings from OpenAI API"""
+    
+    def prep(self, shared):
+        # Get text from shared store
+        return shared.get("text", "")
+        
+    def exec(self, text):
+        # Get embedding using tool function
+        return get_embedding(text)
+        
+    def post(self, shared, prep_res, exec_res):
+        # Store embedding in shared store
+        shared["embedding"] = exec_res
+        return "default" 

cookbook/pocketflow-tool-embeddings/requirements.txt

@@ -0,0 +1,5 @@
+openai>=1.0.0
+numpy>=1.24.0
+faiss-cpu>=1.7.0
+python-dotenv>=1.0.0
+pocketflow>=0.1.0 

cookbook/pocketflow-tool-embeddings/tools/embeddings.py

@@ -0,0 +1,8 @@
+from utils.call_llm import client
+
+def get_embedding(text):
+    response = client.embeddings.create(
+        model="text-embedding-ada-002",
+        input=text
+    )
+    return response.data[0].embedding

cookbook/pocketflow-tool-embeddings/utils/call_llm.py

@@ -0,0 +1,16 @@
+import os
+from openai import OpenAI
+
+# No need for dotenv if using system environment variables
+client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
+
+def call_llm(prompt):    
+    r = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "user", "content": prompt}]
+    )
+    return r.choices[0].message.content
+    
+if __name__ == "__main__":
+    prompt = "What is the meaning of life?"
+    print(call_llm(prompt))