modified files

agent_framework/agent.py

@@ -1,8 +1,8 @@
 """Agent class for executing multi-step reasoning with tools."""
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import List, Optional, Type, Callable, Literal
-from pydantic import BaseModel, Field
+from pydantic import BaseModel
 from .tools import tool
 import inspect
 import json
@@ -28,7 +28,7 @@ class AgentResult:
     output: str | BaseModel
     context: ExecutionContext
     status: Literal["complete", "pending", "error"] = "complete"
-    pending_tool_calls: list[PendingToolCall] = Field(default_factory=list)
+    pending_tool_calls: list[PendingToolCall] = field(default_factory=list)
 
 
 class Agent:

agent_tools/example_usage.py

@@ -1,33 +0,0 @@
-"""Example: How to use agent_tools with your agent."""
-
-import asyncio
-import sys
-from pathlib import Path
-
-# Add parent directory to path
-sys.path.insert(0, str(Path(__file__).parent.parent))
-
-from agent_framework import Agent, LlmClient
-from agent_tools import unzip_file, list_files, read_file, read_media_file
-import asyncio
-from agent_framework import Agent, LlmClient
-from agent_tools import search_web, list_files, read_file
-from agent_tools.file_tools import delete_file
-from agent_tools.web_tools import search_compressor
-from agent_framework.agent import approval_callback
-
-async def main():
-    agent = Agent(
-        model=LlmClient(model="gpt-5-mini"),  # Use a valid model name
-        tools=[search_web, list_files, read_file, delete_file],
-        instructions="You are a helpful assistant that can search the web and explore files to answer questions.",
-        max_steps=20,
-        before_tool_callbacks=[approval_callback],
-        after_tool_callbacks=[search_compressor],
-    )
-    
-    result = await agent.run("search about andrej karpathy")   
-    print(result.output)
-
-if __name__ == "__main__":
-    asyncio.run(main())

agent_tools/web_tools.py

@@ -75,71 +75,27 @@ def _extract_search_query(context: ExecutionContext, tool_call_id: str) -> str:
                 return item.arguments.get("query", "")
     return ""
 
-## callbacks
-# def search_compressor(context: ExecutionContext, tool_result: ToolResult):
-#     """Callback that compresses web search results."""
-#     # Pass through unchanged if not a search tool
-#     if tool_result.name != "search_web":
-#         return None
-    
-#     original_content = tool_result.content[0]
-    
-#     # No compression needed if result is short enough
-#     if len(original_content) < 2000:
-#         return None
-    
-#     # Extract search query matching the tool_call_id
-#     query = _extract_search_query(context, tool_result.tool_call_id)
-#     if not query:
-#         return None
-    
-#     # Use functions implemented in section 5.3
-#     chunks = fixed_length_chunking(original_content, chunk_size=500, overlap=50)
-#     embeddings = get_embeddings(chunks)
-#     results = vector_search(query, chunks, embeddings, top_k=3)
-    
-#     # Create compressed result
-#     compressed = "\n\n".join([r['chunk'] for r in results])
-    
-#     return ToolResult(
-#         tool_call_id=tool_result.tool_call_id,
-#         name=tool_result.name,
-#         status="success",
-#         content=[compressed]
-#     )
-
 ## callbacks
 def search_compressor(context: ExecutionContext, tool_result: ToolResult):
-    """Callback that compresses web search results."""
-    # Pass through unchanged if not a search tool
+    """Callback that compresses web search results using RAG."""
     if tool_result.name != "search_web":
-        print("DEBUG: Callback skipped - not a search_web tool")
         return None
-    
+
     original_content = tool_result.content[0]
-    print(f"DEBUG: Callback triggered! Original content length: {len(original_content)}")
-    
-    # No compression needed if result is short enough
+
     if len(original_content) < 2000:
-        print("DEBUG: Callback skipped - content too short")
         return None
-    
-    # Extract search query matching the tool_call_id
+
     query = _extract_search_query(context, tool_result.tool_call_id)
     if not query:
-        print("DEBUG: Callback skipped - could not extract query")
         return None
-    
-    print(f"DEBUG: Compressing search results for query: {query}")
-    # Use functions implemented in section 5.3
+
     chunks = fixed_length_chunking(original_content, chunk_size=500, overlap=50)
     embeddings = get_embeddings(chunks)
     results = vector_search(query, chunks, embeddings, top_k=3)
-    
-    # Create compressed result
+
     compressed = "\n\n".join([r['chunk'] for r in results])
-    print(f"DEBUG: Compressed from {len(original_content)} to {len(compressed)} chars")
-    
+
     return ToolResult(
         tool_call_id=tool_result.tool_call_id,
         name=tool_result.name,

gaia/config.py

@@ -20,9 +20,9 @@ PROVIDER_SEMAPHORES = {
 
 # Default models to evaluate
 DEFAULT_MODELS = [
-    "gpt-5",
-    "gpt-5-mini",
-    "anthropic/claude-sonnet-4-5",
-    "anthropic/claude-haiku-4-5"
+    "gpt-4o",
+    "gpt-4o-mini",
+    "anthropic/claude-sonnet-4-5-20250929",
+    "anthropic/claude-haiku-4-5-20251001"
 ]
 

gaia/example.py

@@ -1,38 +0,0 @@
-"""Example: Running GAIA evaluation with a subset of problems."""
-
-import asyncio
-import sys
-from pathlib import Path
-
-# Add parent directory to path
-sys.path.insert(0, str(Path(__file__).parent.parent))
-
-from datasets import load_dataset
-from gaia import run_experiment, DEFAULT_MODELS
-
-
-async def main():
-    """Example: Run GAIA evaluation on a small subset."""
-    # Load GAIA dataset
-    level1_problems = load_dataset("gaia-benchmark/GAIA", "2023_level1", split="validation")
-    print(f"Number of Level 1 problems: {len(level1_problems)}")
-    
-    # Select a subset (first 20 problems)
-    subset = level1_problems.select(range(20))
-    
-    # Run experiment with default models
-    results = await run_experiment(subset, DEFAULT_MODELS)
-    
-    # Print results
-    print("\nResults:")
-    for model, model_results in results.items():
-        total = len(model_results)
-        correct = sum(1 for r in model_results if r.get("correct", False))
-        print(f"{model}: {correct}/{total} correct ({correct/total*100:.1f}%)")
-    
-    return results
-
-
-if __name__ == "__main__":
-    asyncio.run(main())
-

gaia/file_problems.py

@@ -1,98 +0,0 @@
-"""Handle GAIA problems with file attachments."""
-
-import asyncio
-import shutil
-import sys
-from pathlib import Path
-from datasets import load_dataset
-from huggingface_hub import snapshot_download
-
-# Add parent directory to path
-sys.path.insert(0, str(Path(__file__).parent.parent))
-
-from agent_framework import Agent, LlmClient
-from agent_tools import unzip_file, read_file, list_files, read_media_file
-
-
-async def main():
-    """Test GAIA problems with file attachments."""
-    # Load dataset
-    dataset = load_dataset("gaia-benchmark/GAIA", "2023_all", split="validation")
-    
-    # Download attached files
-    NOTEBOOK_DIR = Path.cwd()
-    PROJECT_ROOT = NOTEBOOK_DIR.parent
-    CACHE_DIR = PROJECT_ROOT / "gaia_cache"
-    
-    snapshot_download(
-        repo_id="gaia-benchmark/GAIA",
-        repo_type="dataset",
-        allow_patterns="2023/validation/*",
-        local_dir=CACHE_DIR
-    )
-    
-    WORK_DIR = NOTEBOOK_DIR / "gaia_workspace"
-    
-    def reset_workspace():
-        """Restore the workspace to its initial state."""
-        shutil.rmtree(WORK_DIR, ignore_errors=True)
-        shutil.copytree(CACHE_DIR / "2023/validation", WORK_DIR)
-        print(f"Workspace reset: {WORK_DIR}")
-    
-    reset_workspace()
-    
-    problems_with_files = [p for p in dataset if p.get('file_name')]
-    problem_with_zip = [p for p in problems_with_files if p['file_name'].endswith('.zip')]
-    
-    print(f"Total problems: {len(dataset)}")
-    print(f"Problems with attachments: {len(problems_with_files)}")
-    print(f"Total problems with zip files: {len(problem_with_zip)}")
-    
-    problem = problem_with_zip[0]
-    print(f"Question: {problem['Question'][:100]}...")
-    print(f"File name: {problem['file_name']}")
-    
-    file_path = WORK_DIR / problem['file_name']
-    print(f"File exists: {file_path.exists()}")
-    
-    # Reset workspace to clean state
-    reset_workspace()
-    
-    # Select a problem with zip file attachment
-    zip_problems = [p for p in problems_with_files if p['file_name'].endswith('.zip')]
-    problem = zip_problems[0]
-    print(problem)
-    file_path = WORK_DIR / problem['file_name']
-    
-    # Construct prompt including file location
-    prompt = f"""{problem['Question']}
- 
-The attached file is located at: {file_path}
-"""
-    print(prompt)
-    
-    # Create agent with file tools
-    agent = Agent(
-        model=LlmClient(model="gpt-5"),
-        tools=[unzip_file, read_file, list_files, read_media_file],
-        instructions="""You are a helpful assistant that can work with files.
-
-CRITICAL: You MUST use the read_file tool for Excel files (.xlsx), (.xls). The tool WILL work - do NOT say you cannot read Excel files. Always call the tool first.
-
-Tools available:
-- read_file: Reads .xlsx, .xls, .csv, .txt, .py, .json, .md, .xml files. USE THIS FOR EXCEL FILES.
-- read_media_file: Analyzes PDF files, images, and audio. Requires a query parameter.
-- list_files: Lists directory contents
-- unzip_file: Extracts zip archives
-
-
-""",
-        max_steps=15    )
-    
-    response = await agent.run(prompt)
-    print(response.output)
-    print(response.context)
-
-
-if __name__ == "__main__":
-    asyncio.run(main())

misc/CODE_TRACE_OUTLINE.md

@@ -1,395 +0,0 @@
-# Code Trace Outline - Agent Framework
-
-This document provides a systematic guide to understanding and tracing through the agent framework codebase.
-
-## 📋 Table of Contents
-1. [Entry Points](#entry-points)
-2. [Suggested Reading Order](#suggested-reading-order)
-3. [Function Call Flow](#function-call-flow)
-4. [Component Relationships](#component-relationships)
-5. [Key Functions Reference](#key-functions-reference)
-
----
-
-## 🚀 Entry Points
-
-### Primary Entry Point
-**File:** `examples/demo.py` or `example.py` or `examples/gaia_evaluation.py`
-
-```python
-agent = Agent(...)
-result = await agent.run("question")
-```
-
-**Flow:** `agent.run()` → `agent.step()` → `agent.think()` → `agent.act()`
-
----
-
-## 📖 Suggested Reading Order
-
-### Phase 1: Foundation (Data Models)
-**Start here to understand the data structures**
-
-1. **`agent_framework/models.py`**
-   - Read in order:
-     - `Message` (line ~10-15)
-     - `ToolCall` (line ~18-25)
-     - `ToolResult` (line ~28-35)
-     - `ContentItem` (line ~38-45)
-     - `Event` (line ~48-60)
-     - `ExecutionContext` (line ~63-85)
-   
-   **Why:** These are the core data structures used throughout the framework.
-
-### Phase 2: Tool System
-**Understand how tools are defined and executed**
-
-2. **`agent_framework/tools.py`**
-   - Read in order:
-     - `BaseTool` abstract class (line ~10-20)
-     - `FunctionTool.__init__()` (line ~25-45)
-     - `FunctionTool.execute()` (line ~47-70)
-     - `FunctionTool.to_definition()` (line ~72-85)
-     - `@tool` decorator (line ~88-120)
-   
-   **Why:** Tools are the extension mechanism - understand how functions become tools.
-
-3. **`agent_framework/utils.py`**
-   - Read in order:
-     - `function_to_input_schema()` (line ~10-50)
-     - `format_tool_definition()` (line ~52-75)
-     - `mcp_tools_to_openai_format()` (line ~77-100)
-   
-   **Why:** These convert Python functions to LLM-understandable tool definitions.
-
-### Phase 3: LLM Integration
-**Understand how we communicate with LLMs**
-
-4. **`agent_framework/llm.py`**
-   - Read in order:
-     - `LlmRequest` (line ~10-25)
-     - `LlmResponse` (line ~28-40)
-     - `LlmClient.__init__()` (line ~43-50)
-     - `LlmClient._build_messages()` (line ~52-85)
-     - `LlmClient._parse_response()` (line ~87-120)
-     - `LlmClient.generate()` (line ~122-146)
-   
-   **Why:** This is the interface to the LLM - understand request/response format.
-
-### Phase 4: Agent Core Logic
-**The main orchestration logic**
-
-5. **`agent_framework/agent.py`**
-   - Read in order:
-     - `Agent.__init__()` (line ~29-43)
-     - `Agent._setup_tools()` (line ~45-46)
-     - `Agent._prepare_llm_request()` (line ~48-85)
-     - `Agent.think()` (line ~87-95)
-     - `Agent.act()` (line ~97-115)
-     - `Agent.step()` (line ~116-171)
-     - `Agent.run()` (line ~173-200)
-     - `Agent._is_final_response()` (line ~202-206)
-     - `Agent._extract_final_result()` (line ~208-225)
-   
-   **Why:** This is the main agent loop - understand the step-by-step execution.
-
-### Phase 5: MCP Integration (Optional)
-**External tool loading**
-
-6. **`agent_framework/mcp.py`**
-   - Read in order:
-     - `_extract_text_content()` (line ~10-20)
-     - `_create_mcp_tool()` (line ~22-60)
-     - `load_mcp_tools()` (line ~62-100)
-   
-   **Why:** Understand how external MCP servers provide tools.
-
-### Phase 6: Examples
-**See it all in action**
-
-7. **`examples/demo.py`** - Simple example
-8. **`examples/gaia_evaluation.py`** - Complex example with structured output
-
----
-
-## 🔄 Function Call Flow
-
-### Main Execution Flow
-
-```
-User Code
-  │
-  ├─> Agent.run(user_input)
-  │     │
-  │     ├─> Creates ExecutionContext
-  │     ├─> Adds user Event
-  │     │
-  │     └─> Loop: while not final_result and step < max_steps
-  │           │
-  │           └─> Agent.step(context)
-  │                 │
-  │                 ├─> Agent._prepare_llm_request(context)
-  │                 │     │
-  │                 │     ├─> Flattens events → contents
-  │                 │     ├─> Adds tool info to instructions
-  │                 │     └─> Returns LlmRequest
-  │                 │
-  │                 ├─> Agent.think(llm_request)
-  │                 │     │
-  │                 │     └─> LlmClient.generate(request)
-  │                 │           │
-  │                 │           ├─> LlmClient._build_messages()
-  │                 │           ├─> litellm.acompletion()
-  │                 │           └─> LlmClient._parse_response()
-  │                 │
-  │                 ├─> If tool_calls exist:
-  │                 │     │
-  │                 │     └─> Agent.act(context, tool_calls)
-  │                 │           │
-  │                 │           ├─> For each tool_call:
-  │                 │           │     │
-  │                 │           │     └��> tool.execute(context, **args)
-  │                 │           │           │
-  │                 │           │           └─> FunctionTool.execute()
-  │                 │           │                 │
-  │                 │           │                 └─> Calls wrapped function
-  │                 │           │
-  │                 │           └─> Returns ToolResult[]
-  │                 │
-  │                 └─> If output_type and no tool_calls:
-  │                       │
-  │                       └─> Final LLM call with structured output
-  │
-  └─> Returns AgentResult(output, context)
-```
-
-### Tool Execution Flow
-
-```
-Agent.act(context, tool_calls)
-  │
-  ├─> For each ToolCall:
-  │     │
-  │     ├─> Find tool by name: tool = self.tools[call.name]
-  │     │
-  │     ├─> Call: tool.execute(context, **call.arguments)
-  │     │     │
-  │     │     └─> FunctionTool.execute()
-  │     │           │
-  │     │           ├─> Inspect function signature
-  │     │           ├─> If has 'context' param → pass it
-  │     │           ├─> Call: func(**kwargs)
-  │     │           └─> Wrap result in ToolResult
-  │     │
-  │     └─> Collect ToolResult
-  │
-  └─> Return list of ToolResults
-```
-
-### LLM Request Building Flow
-
-```
-Agent._prepare_llm_request(context)
-  │
-  ├─> Flatten events → contents
-  │     │
-  │     └─> For each Event:
-  │           └─> For each ContentItem in event.content:
-  │                 └─> Add to flat_contents
-  │
-  ├─> Build instructions
-  │     │
-  │     ├─> Add self.instructions
-  │     └─> If tools exist:
-  │           └─> Append tool descriptions
-  │
-  ├─> Set response_format (if enforce_output_type)
-  │
-  └─> Return LlmRequest(instructions, contents, tools, response_format)
-```
-
----
-
-## 🔗 Component Relationships
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                        User Code                             │
-│  (examples/demo.py, example.py, gaia_evaluation.py)          │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     │ Creates
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│                         Agent                                │
-│  (agent_framework/agent.py)                                  │
-│                                                              │
-│  - Orchestrates reasoning loop                              │
-│  - Manages ExecutionContext                                 │
-│  - Calls LLM and executes tools                             │
-└──────┬───────────────────────────────┬───────────────────────┘
-       │                               │
-       │ Uses                          │ Uses
-       ▼                               ▼
-┌──────────────────┐         ┌──────────────────┐
-│   LlmClient      │         │   BaseTool       │
-│  (llm.py)        │         │   (tools.py)     │
-│                  │         │                  │
-│  - Sends requests│         │  - FunctionTool  │
-│  - Parses resp.  │         │  - MCP Tools     │
-└──────┬───────────┘         └──────┬───────────┘
-       │                            │
-       │ Uses                       │ Uses
-       ▼                            ▼
-┌──────────────────┐         ┌──────────────────┐
-│   LiteLLM        │         │   Utils          │
-│  (external)      │         │  (utils.py)      │
-│                  │         │                  │
-│  - API calls     │         │  - Schema conv.  │
-│  - Streaming     │         │  - Format tools  │
-└──────────────────┘         └──────────────────┘
-                                     │
-                                     │ Uses
-                                     ▼
-                            ┌──────────────────┐
-                            │   MCP Client     │
-                            │  (mcp.py)        │
-                            │                  │
-                            │  - Load tools    │
-                            │  - Execute tools │
-                            └──────────────────┘
-
-┌─────────────────────────────────────────────────────────────┐
-│                    Data Models                              │
-│  (models.py)                                                │
-│                                                             │
-│  - Message, ToolCall, ToolResult                           │
-│  - Event, ExecutionContext                                 │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## 📚 Key Functions Reference
-
-### Agent Class (`agent.py`)
-
-| Function | Purpose | Called By | Calls |
-|----------|---------|-----------|-------|
-| `__init__()` | Initialize agent with model, tools, instructions | User code | `_setup_tools()` |
-| `run()` | Main entry point - execute agent loop | User code | `step()` |
-| `step()` | Execute one reasoning step | `run()` | `_prepare_llm_request()`, `think()`, `act()` |
-| `think()` | Get LLM's decision | `step()` | `LlmClient.generate()` |
-| `act()` | Execute tool calls | `step()` | `tool.execute()` |
-| `_prepare_llm_request()` | Build LLM request from context | `step()` | - |
-| `_is_final_response()` | Check if response is final | `run()` | - |
-| `_extract_final_result()` | Extract structured output | `run()` | - |
-
-### LlmClient Class (`llm.py`)
-
-| Function | Purpose | Called By | Calls |
-|----------|---------|-----------|-------|
-| `generate()` | Make async LLM API call | `Agent.think()` | `_build_messages()`, `_parse_response()`, `litellm.acompletion()` |
-| `_build_messages()` | Convert request to OpenAI format | `generate()` | - |
-| `_parse_response()` | Parse LLM response | `generate()` | - |
-
-### FunctionTool Class (`tools.py`)
-
-| Function | Purpose | Called By | Calls |
-|----------|---------|-----------|-------|
-| `execute()` | Execute the wrapped function | `Agent.act()` | Wrapped function |
-| `to_definition()` | Convert to OpenAI tool format | `Agent._prepare_llm_request()` | `format_tool_definition()` |
-
-### Utility Functions (`utils.py`)
-
-| Function | Purpose | Called By |
-|----------|---------|-----------|
-| `function_to_input_schema()` | Convert function to JSON Schema | `FunctionTool.to_definition()` |
-| `format_tool_definition()` | Format tool in OpenAI format | `FunctionTool.to_definition()` |
-| `display_trace()` | Pretty print execution trace | User code |
-
----
-
-## 🎯 Tracing a Specific Execution
-
-### Example: "What is 1234 * 5678?"
-
-1. **User calls:** `agent.run("What is 1234 * 5678?")`
-   - Location: `agent.py:173`
-
-2. **Agent.run() creates context:**
-   - Creates `ExecutionContext`
-   - Adds user `Event` with `Message(role="user", content="...")`
-   - Location: `agent.py:180-189`
-
-3. **First iteration of loop:**
-   - Calls `agent.step(context)`
-   - Location: `agent.py:193`
-
-4. **Agent.step() prepares request:**
-   - Calls `_prepare_llm_request(context)`
-   - Flattens events, adds tool info
-   - Location: `agent.py:116-120`
-
-5. **Agent.think() calls LLM:**
-   - Calls `llm_client.generate(request)`
-   - Location: `agent.py:87-95`
-
-6. **LlmClient.generate() processes:**
-   - `_build_messages()` converts to OpenAI format
-   - `litellm.acompletion()` makes API call
-   - `_parse_response()` parses response
-   - Location: `llm.py:122-146`
-
-7. **LLM returns with tool call:**
-   - Response contains `ToolCall(name="calculator", arguments={"expression": "1234 * 5678"})`
-   - Location: `llm.py:100-120` (parsing)
-
-8. **Agent.act() executes tool:**
-   - Finds `calculator` tool
-   - Calls `tool.execute(context, expression="1234 * 5678")`
-   - Location: `agent.py:97-115`
-
-9. **FunctionTool.execute() runs function:**
-   - Calls `calculator("1234 * 5678")`
-   - Returns `7006652`
-   - Wraps in `ToolResult`
-   - Location: `tools.py:47-70`
-
-10. **Tool result added to context:**
-    - Creates new `Event` with `ToolResult`
-    - Location: `agent.py:155-161`
-
-11. **Second iteration:**
-    - LLM sees tool result
-    - Returns final answer: `"7006652"`
-    - Location: `agent.py:116-171`
-
-12. **Agent.run() detects final response:**
-    - `_is_final_response()` returns True
-    - `_extract_final_result()` extracts answer
-    - Returns `AgentResult`
-    - Location: `agent.py:196-200`
-
----
-
-## 🔍 Debugging Tips
-
-1. **Start with `Agent.run()`** - This is where execution begins
-2. **Follow `step()` calls** - Each step is one reasoning iteration
-3. **Check `ExecutionContext.events`** - This contains the full history
-4. **Use `display_trace()`** - Visualize the execution flow
-5. **Inspect `LlmRequest`** - See what's sent to the LLM
-6. **Check `LlmResponse`** - See what the LLM returned
-7. **Verify tool definitions** - Ensure tools are properly formatted
-
----
-
-## 📝 Notes
-
-- **Async/Await:** Most functions are async - use `await` when calling
-- **ExecutionContext:** Threaded through all operations - contains state
-- **Events:** Every action (user input, LLM response, tool call) is an Event
-- **Tool Execution:** Tools can optionally receive `ExecutionContext` parameter
-- **Structured Output:** Only enforced on final LLM call (not during tool usage)
-

misc/JOB_SEARCH_SCHEDULE.md

@@ -1,468 +0,0 @@
-# Job Search Schedule: February 1 - June 1, 2026
-
-**Goal:** Land a $150k+ Applied AI/ML Engineer role before OPT grace period ends.
-
----
-
-## Daily Structure
-
-| Time | Activity |
-|------|----------|
-| 5:00 AM | Wake up |
-| 5:00 - 6:00 AM | Morning routine, coffee |
-| 6:00 - 9:00 AM | **Deep Work Block 1** (LeetCode/Technical) |
-| 9:00 - 9:30 AM | Break |
-| 9:30 - 12:30 PM | **Deep Work Block 2** (Learning/Projects) |
-| 12:30 - 1:30 PM | Lunch |
-| 1:30 - 4:30 PM | **Deep Work Block 3** (Job Applications/Networking) |
-| 4:30 - 7:00 PM | Gym (2.5 hours) |
-| 7:00 - 8:00 PM | Dinner |
-| 8:00 - 10:00 PM | Light work (applications, reading, prep) |
-| 10:00 - 11:00 PM | Wind down |
-| 11:00 PM | Sleep |
-
-**Tuesday Exception:** Class 7-10 PM (no gym, shift blocks earlier)
-
----
-
-## Phase Overview
-
-| Phase | Weeks | Focus |
-|-------|-------|-------|
-| **Phase 1** | Week 1-4 (Feb) | Foundation + Start Applications |
-| **Phase 2** | Week 5-8 (Mar) | LangChain + Interview Prep Ramp |
-| **Phase 3** | Week 9-12 (Apr) | System Design + Mock Interviews |
-| **Phase 4** | Week 13-17 (May-Jun 1) | Interview Mode + Final Push |
-
----
-
-# PHASE 1: Foundation (February)
-
-## Week 1: Feb 1-7
-### Theme: Finish Agent Framework + Start Everything
-
-| Block | Mon | Tue | Wed | Thu | Fri | Sat | Sun |
-|-------|-----|-----|-----|-----|-----|-----|-----|
-| 6-9 AM | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x3 | Rest |
-| 9:30-12:30 | Agent Framework | Agent Framework | Agent Framework | Agent Framework | Agent Framework | Review week | Rest |
-| 1:30-4:30 | Resume update | 5 applications | 5 applications | 5 applications | 5 applications | Network LinkedIn | Rest |
-| 8-10 PM | ML review | (Class) | ML review | ML review | ML review | Applications | Rest |
-
-### Deliverables Week 1:
-- [ ] Agent framework 100% complete
-- [ ] LeetCode: 12 problems solved (Arrays, Strings focus)
-- [ ] Resume updated with agent framework project
-- [ ] 20+ job applications submitted
-- [ ] LinkedIn profile updated
-- [ ] 5 LinkedIn connection requests to recruiters
-
----
-
-## Week 2: Feb 8-14
-### Theme: LangChain Basics + Application Momentum
-
-| Block | Mon | Tue | Wed | Thu | Fri | Sat | Sun |
-|-------|-----|-----|-----|-----|-----|-----|-----|
-| 6-9 AM | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x3 | Rest |
-| 9:30-12:30 | LangChain basics | LangChain basics | LangChain chains | LangChain chains | LangChain agents | Build project | Rest |
-| 1:30-4:30 | 5 applications | 5 applications | 5 applications | 5 applications | 5 applications | Network | Rest |
-| 8-10 PM | ML review | (Class) | ML review | ML review | ML review | Behavioral prep | Rest |
-
-### Deliverables Week 2:
-- [ ] LeetCode: 12 more problems (Total: 24) - Trees, Linked Lists
-- [ ] LangChain fundamentals understood (chains, prompts, output parsers)
-- [ ] 25+ job applications submitted (Total: 45+)
-- [ ] Started tracking applications in spreadsheet
-- [ ] 3 Pfizer contacts messaged for referrals
-
----
-
-## Week 3: Feb 15-21
-### Theme: LangGraph + First Responses
-
-| Block | Mon | Tue | Wed | Thu | Fri | Sat | Sun |
-|-------|-----|-----|-----|-----|-----|-----|-----|
-| 6-9 AM | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x3 | Rest |
-| 9:30-12:30 | LangGraph basics | LangGraph state | LangGraph edges | LangGraph project | LangGraph project | Complete project | Rest |
-| 1:30-4:30 | 5 applications | 5 applications | 5 applications | 5 applications | 5 applications | Network | Rest |
-| 8-10 PM | ML review | (Class) | RAG concepts | RAG concepts | Project polish | Behavioral prep | Rest |
-
-### Deliverables Week 3:
-- [ ] LeetCode: 12 more problems (Total: 36) - Graphs, BFS/DFS
-- [ ] LangGraph multi-agent project complete
-- [ ] Project deployed (Streamlit or FastAPI)
-- [ ] 25+ applications (Total: 70+)
-- [ ] First phone screens scheduled (hopefully)
-- [ ] Pfizer STAR story written out
-
----
-
-## Week 4: Feb 22-28
-### Theme: RAG Deep Dive + Interview Prep Start
-
-| Block | Mon | Tue | Wed | Thu | Fri | Sat | Sun |
-|-------|-----|-----|-----|-----|-----|-----|-----|
-| 6-9 AM | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x3 | Rest |
-| 9:30-12:30 | RAG architecture | Vector DBs | Chunking strategies | Retrieval patterns | RAG evaluation | Build RAG project | Rest |
-| 1:30-4:30 | 5 applications | 5 applications | 5 applications | 5 applications | 5 applications | Mock interview | Rest |
-| 8-10 PM | Interview prep | (Class) | Interview prep | Interview prep | Interview prep | Rest | Rest |
-
-### Deliverables Week 4:
-- [ ] LeetCode: 12 more problems (Total: 48) - DP basics
-- [ ] RAG system built (with evaluation)
-- [ ] Added to portfolio
-- [ ] 25+ applications (Total: 95+)
-- [ ] First mock interview completed
-- [ ] ML fundamentals flashcards created
-
----
-
-## February Checkpoint ✓
-
-**By Feb 28:**
-- [ ] 48+ LeetCode problems solved
-- [ ] Agent framework complete + deployed
-- [ ] LangGraph project complete + deployed
-- [ ] RAG project complete
-- [ ] 95+ job applications
-- [ ] 2-3 phone screens scheduled
-- [ ] Pfizer story polished
-
----
-
-# PHASE 2: LangChain Mastery + Interview Ramp (March)
-
-## Week 5: Mar 1-7
-### Theme: Advanced RAG + Phone Screens
-
-| Block | Mon | Tue | Wed | Thu | Fri | Sat | Sun |
-|-------|-----|-----|-----|-----|-----|-----|-----|
-| 6-9 AM | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x3 | Rest |
-| 9:30-12:30 | Self-correcting RAG | Multi-query RAG | Hybrid search | GraphRAG intro | GraphRAG build | Project polish | Rest |
-| 1:30-4:30 | Applications | Applications | Phone screen prep | Applications | Applications | Network | Rest |
-| 8-10 PM | ML interview Q's | (Class) | ML interview Q's | ML interview Q's | Behavioral prep | Rest | Rest |
-
-### Deliverables Week 5:
-- [ ] LeetCode: 12 more (Total: 60)
-- [ ] Advanced RAG patterns implemented
-- [ ] GraphRAG basic understanding
-- [ ] 20+ applications (Total: 115+)
-- [ ] 1-2 phone screens completed
-- [ ] ML fundamentals review: supervised learning
-
----
-
-## Week 6: Mar 8-14
-### Theme: Production Patterns + Technical Screens
-
-| Block | Mon | Tue | Wed | Thu | Fri | Sat | Sun |
-|-------|-----|-----|-----|-----|-----|-----|-----|
-| 6-9 AM | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x3 | Rest |
-| 9:30-12:30 | Streaming patterns | Fallback chains | Caching | Memory patterns | Production deploy | System design | Rest |
-| 1:30-4:30 | Applications | Applications | Applications | Applications | Applications | Mock interview | Rest |
-| 8-10 PM | DL/Transformer Q's | (Class) | DL/Transformer Q's | Interview prep | Interview prep | Rest | Rest |
-
-### Deliverables Week 6:
-- [ ] LeetCode: 12 more (Total: 72)
-- [ ] Production-ready LangChain app
-- [ ] Streaming + caching implemented
-- [ ] 20+ applications (Total: 135+)
-- [ ] 2 mock interviews completed
-- [ ] ML fundamentals review: deep learning basics
-
----
-
-## Week 7: Mar 15-21
-### Theme: System Design Intro + More Interviews
-
-| Block | Mon | Tue | Wed | Thu | Fri | Sat | Sun |
-|-------|-----|-----|-----|-----|-----|-----|-----|
-| 6-9 AM | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x3 | Rest |
-| 9:30-12:30 | ML System Design book | Design: Rec system | Design: Search | Design: RAG system | Design: Agent | Practice designs | Rest |
-| 1:30-4:30 | Applications | Applications | Applications | Applications | Applications | Mock interview | Rest |
-| 8-10 PM | RAG interview Q's | (Class) | Agent interview Q's | Interview prep | Interview prep | Rest | Rest |
-
-### Deliverables Week 7:
-- [ ] LeetCode: 12 more (Total: 84)
-- [ ] 3 ML system designs practiced
-- [ ] System design framework memorized
-- [ ] 20+ applications (Total: 155+)
-- [ ] Technical screen(s) completed
-- [ ] ML fundamentals review: NLP/Transformers
-
----
-
-## Week 8: Mar 22-28
-### Theme: Interview Prep Intensity
-
-| Block | Mon | Tue | Wed | Thu | Fri | Sat | Sun |
-|-------|-----|-----|-----|-----|-----|-----|-----|
-| 6-9 AM | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x3 | Rest |
-| 9:30-12:30 | System design practice | System design practice | ML interview Q's | ML interview Q's | Mock interview | Mock interview | Rest |
-| 1:30-4:30 | Applications | Applications | Applications | Applications | Applications | Rest | Rest |
-| 8-10 PM | Behavioral prep | (Class) | Behavioral prep | Interview prep | Rest | Rest | Rest |
-
-### Deliverables Week 8:
-- [ ] LeetCode: 12 more (Total: 96)
-- [ ] 5+ system designs practiced
-- [ ] 15+ applications (Total: 170+)
-- [ ] 3+ mock interviews total
-- [ ] Ready for technical rounds
-
----
-
-## March Checkpoint ✓
-
-**By Mar 31:**
-- [ ] 96+ LeetCode problems solved
-- [ ] Advanced RAG + LangGraph projects complete
-- [ ] 5+ system designs practiced
-- [ ] 170+ total applications
-- [ ] 5+ phone/technical screens completed
-- [ ] On-site interviews scheduled (hopefully)
-
----
-
-# PHASE 3: Interview Mode (April)
-
-## Week 9: Apr 1-7
-### Theme: Mock Interviews + Real Interviews
-
-| Block | Mon | Tue | Wed | Thu | Fri | Sat | Sun |
-|-------|-----|-----|-----|-----|-----|-----|-----|
-| 6-9 AM | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x2 | LeetCode x2 | Rest |
-| 9:30-12:30 | Mock coding | Mock system design | Mock ML | Interview prep | Interview prep | Mock full loop | Rest |
-| 1:30-4:30 | Applications | Applications | Applications | Applications | Applications | Rest | Rest |
-| 8-10 PM | Review weak areas | (Class) | Review weak areas | Prep for interviews | Prep for interviews | Rest | Rest |
-
-### Deliverables Week 9:
-- [ ] LeetCode: 10 more (Total: 106)
-- [ ] 2 full mock interview loops
-- [ ] 10+ applications (Total: 180+)
-- [ ] Identify and fix weak areas
-
----
-
-## Week 10: Apr 8-14
-### Theme: On-sites Begin
-
-| Block | Mon | Tue | Wed | Thu | Fri | Sat | Sun |
-|-------|-----|-----|-----|-----|-----|-----|-----|
-| 6-9 AM | LeetCode x2 | Interview prep | LeetCode x2 | Interview prep | LeetCode x2 | Review | Rest |
-| 9:30-12:30 | Prep for specific company | INTERVIEW | Prep | INTERVIEW | Prep | Mock | Rest |
-| 1:30-4:30 | Applications | Follow-up | Applications | Follow-up | Applications | Rest | Rest |
-| 8-10 PM | Company research | (Class) | Company research | Behavioral prep | Rest | Rest | Rest |
-
-### Deliverables Week 10:
-- [ ] LeetCode: 6 more (Total: 112)
-- [ ] 2+ on-site/virtual on-site interviews
-- [ ] Thank you emails sent
-- [ ] Continue applications pipeline
-
----
-
-## Week 11: Apr 15-21
-### Theme: Interview Sprint
-
-| Block | Focus |
-|-------|-------|
-| All week | Interviews, prep between interviews, light applications |
-
-### Deliverables Week 11:
-- [ ] 2-3 more interviews completed
-- [ ] Follow-up on all interviews
-- [ ] Continue pipeline
-
----
-
-## Week 12: Apr 22-28
-### Theme: Interview Sprint Continues
-
-| Block | Focus |
-|-------|-------|
-| All week | Interviews, negotiations prep if offers coming |
-
-### Deliverables Week 12:
-- [ ] More interviews
-- [ ] Start seeing results (offers or rejections)
-- [ ] Learn from rejections, iterate
-
----
-
-## April Checkpoint ✓
-
-**By Apr 30:**
-- [ ] 110+ LeetCode problems solved
-- [ ] 5-10 on-site interviews completed
-- [ ] 190+ total applications
-- [ ] Hopefully 1+ offers in pipeline
-- [ ] Clear understanding of weak areas
-
----
-
-# PHASE 4: Final Push (May)
-
-## Week 13: May 1-7
-### Theme: Close Deals or Intensify Search
-
-**If you have offers:**
-- Negotiate
-- Compare offers
-- Make decision
-
-**If no offers yet:**
-- Analyze feedback from rejections
-- Intensify applications
-- More mock interviews
-
-### Deliverables Week 13:
-- [ ] Decision on any offers OR
-- [ ] 20+ more applications
-- [ ] More interviews scheduled
-
----
-
-## Week 14: May 8-14
-### Theme: Pre-Graduation Push
-
-| Block | Focus |
-|-------|-------|
-| Continue interviews | Focus on closing |
-| Applications | Maintain pipeline |
-| Prep for graduation | Logistics |
-
-### Deliverables Week 14:
-- [ ] Interviews ongoing
-- [ ] Offer negotiations if applicable
-
----
-
-## Week 15: May 15-21
-### Theme: Graduation Week
-
-| Block | Focus |
-|-------|-------|
-| May 23 | GRADUATION 🎓 |
-| Rest of week | Interviews, decisions |
-
-### Deliverables Week 15:
-- [ ] Graduate!
-- [ ] Close any pending offers
-- [ ] Prepare for OPT start
-
----
-
-## Week 16: May 22-28
-### Theme: Post-Graduation, OPT Transition
-
-| Block | Focus |
-|-------|-------|
-| OPT paperwork | Get EAD card |
-| Interviews | Continue if needed |
-| Start date discussions | If offers accepted |
-
-### Deliverables Week 16:
-- [ ] OPT paperwork filed
-- [ ] Job offer accepted OR
-- [ ] Intensive job search continues
-
----
-
-## Week 17: May 29 - Jun 1
-### Theme: June 1 Target
-
-### Deliverables:
-- [ ] **JOB OFFER ACCEPTED** (Target!)
-- [ ] Start date confirmed
-- [ ] OPT employment verified
-
----
-
-# Tracking Spreadsheet
-
-Create a spreadsheet with these columns:
-
-| Company | Role | Applied Date | Status | Next Step | Notes |
-|---------|------|--------------|--------|-----------|-------|
-| Google | Applied AI Engineer | Feb 3 | Applied | Wait | Referral from X |
-| Anthropic | ML Engineer | Feb 5 | Phone Screen | Feb 15 | Prep RAG questions |
-
----
-
-# Weekly Metrics to Track
-
-| Metric | Week 1 Target | Week 8 Target | Week 17 Target |
-|--------|---------------|---------------|----------------|
-| LeetCode Total | 12 | 96 | 120 |
-| Applications Total | 20 | 170 | 220 |
-| Phone Screens | 0 | 8 | 15 |
-| Technical Screens | 0 | 5 | 12 |
-| On-sites | 0 | 2 | 8 |
-| Offers | 0 | 0 | 1+ |
-
----
-
-# Emergency Backup Plans
-
-## If no interviews by Week 6:
-- Resume review with mentor/professional
-- Expand to Tier 2/3 companies
-- More networking, less applications
-- Consider contracting roles
-
-## If no offers by Week 12:
-- Lower target salary temporarily
-- Consider smaller companies
-- Look at contract-to-hire roles
-- Leverage Pfizer network harder
-
-## If no offers by Week 16:
-- Start date flexibility with any offer
-- Consider any legitimate offer
-- Plan for extended search during OPT
-
----
-
-# Resources to Use
-
-**LeetCode:**
-- NeetCode 150 (structured)
-- Grind 75 (time-efficient)
-- Company-specific lists
-
-**System Design:**
-- "Designing Machine Learning Systems" - Chip Huyen
-- "ML System Design Interview" - Ali Aminian
-- YouTube: System Design Interview channel
-
-**Behavioral:**
-- Write out 5 STAR stories
-- Pfizer project (main story)
-- Agent framework (technical depth)
-- Conflict resolution story
-- Failure and learning story
-
-**Mock Interviews:**
-- Pramp (free)
-- Interviewing.io (free/paid)
-- Friends/classmates
-
----
-
-# Key Success Factors
-
-1. **Start applications NOW** - Don't wait until "ready"
-2. **Consistent LeetCode** - 2 problems/day minimum
-3. **Track everything** - Spreadsheet is your friend
-4. **Network aggressively** - Referrals > cold applications
-5. **Learn from rejections** - Ask for feedback
-6. **Stay healthy** - Gym, sleep, breaks matter
-
----
-
-**You've got this. 4 months is enough with focused execution. Start today.**
-
----
-
-*Last updated: February 1, 2026*
-

misc/LANGCHAIN_COMPARISON.md

@@ -1,396 +0,0 @@
-# Comparison: Your Agent Framework vs LangChain
-
-## Executive Summary
-
-**Your implementation is conceptually similar to LangChain but significantly simpler and more lightweight.** You've built the core agent loop pattern that LangChain uses, but without the extensive abstraction layers and enterprise features.
-
-**Similarity Score: ~70%** - You share the fundamental architecture but differ in complexity and features.
-
----
-
-## Core Architecture Comparison
-
-### Your Framework
-
-```python
-Agent
-  ├─ run() → step() loop
-  ├─ think() → LlmClient.generate()
-  ├─ act() → tool.execute()
-  └─ ExecutionContext (events, state)
-```
-
-### LangChain
-
-```python
-AgentExecutor
-  ├─ Agent (ReAct, ToolCalling, etc.)
-  ├─ Runnable chain
-  ├─ ToolExecutor
-  └─ Memory (separate abstraction)
-```
-
----
-
-## Detailed Feature Comparison
-
-### 1. Agent Execution Loop
-
-| Feature | Your Framework | LangChain |
-|---------|---------------|-----------|
-| **Execution Loop** | `Agent.run()` → `step()` loop | `AgentExecutor.run()` → `_take_next_step()` |
-| **Max Steps** | ✅ `max_steps` parameter | ✅ `max_iterations` parameter |
-| **Early Stopping** | ✅ Checks `final_result` | ✅ Checks `AgentFinish` |
-| **Error Handling** | Basic | ✅ Comprehensive (retries, error recovery) |
-| **Streaming** | ❌ Not implemented | ✅ Built-in streaming support |
-
-**Your Code:**
-```python
-while not context.final_result and context.current_step < self.max_steps:
-    await self.step(context)
-```
-
-**LangChain Equivalent:**
-```python
-while not agent_finish and iterations < max_iterations:
-    next_step = agent.plan(intermediate_steps)
-    # ... execute step
-```
-
-**Verdict:** ✅ **Very similar** - Same core loop pattern
-
----
-
-### 2. Tool System
-
-| Feature | Your Framework | LangChain |
-|---------|---------------|-----------|
-| **Tool Definition** | `BaseTool` abstract class | `BaseTool` abstract class |
-| **Function Wrapping** | ✅ `FunctionTool` | ✅ `tool()` decorator / `StructuredTool` |
-| **Tool Schema** | ✅ JSON Schema generation | ✅ JSON Schema (via Pydantic) |
-| **Tool Execution** | ✅ `execute(context, **kwargs)` | ✅ `invoke(input)` or `arun(input)` |
-| **Tool Metadata** | Basic (name, description) | ✅ Rich metadata (tags, version, etc.) |
-| **Tool Validation** | Basic | ✅ Input/output validation |
-| **Tool Streaming** | ❌ | ✅ Streaming tool results |
-
-**Your Code:**
-```python
-class BaseTool(ABC):
-    @abstractmethod
-    async def execute(self, context: ExecutionContext, **kwargs) -> ToolResult:
-        pass
-```
-
-**LangChain Equivalent:**
-```python
-class BaseTool(BaseModel):
-    def invoke(self, input: dict) -> Any:
-        pass
-```
-
-**Verdict:** ✅ **Similar** - Same abstraction pattern, LangChain has more features
-
----
-
-### 3. LLM Integration
-
-| Feature | Your Framework | LangChain |
-|---------|---------------|-----------|
-| **LLM Client** | ✅ `LlmClient` (LiteLLM) | ✅ `ChatOpenAI`, `ChatAnthropic`, etc. |
-| **Message Formatting** | ✅ `_build_messages()` | ✅ `ChatPromptTemplate` |
-| **Tool Calling** | ✅ Function calling format | ✅ Native function calling |
-| **Structured Output** | ✅ `output_type` parameter | ✅ `with_structured_output()` |
-| **Streaming** | ❌ | ✅ Built-in streaming |
-| **Retries** | ❌ | ✅ Automatic retries with backoff |
-| **Rate Limiting** | ❌ | ✅ Built-in rate limiting |
-
-**Your Code:**
-```python
-llm_request = LlmRequest(
-    instructions=[self.instructions],
-    contents=flat_contents,
-    tools=self.tools,
-    response_format=self.output_type
-)
-```
-
-**LangChain Equivalent:**
-```python
-messages = prompt.format_messages(...)
-response = llm.invoke(messages, tools=tools)
-```
-
-**Verdict:** ✅ **Similar** - Same concepts, LangChain has more LLM providers
-
----
-
-### 4. Memory/Context Management
-
-| Feature | Your Framework | LangChain |
-|---------|---------------|-----------|
-| **Conversation History** | ✅ `ExecutionContext.events` | ✅ `ChatMessageHistory` |
-| **State Management** | ✅ `ExecutionContext.state` | ✅ `BaseMemory` classes |
-| **Event Tracking** | ✅ `Event` model | ✅ `CallbackHandler` system |
-| **Memory Types** | Single (events list) | ✅ Multiple (buffer, summary, etc.) |
-| **Memory Persistence** | ❌ In-memory only | ✅ Database, Redis, etc. |
-
-**Your Code:**
-```python
-@dataclass
-class ExecutionContext:
-    events: List[Event]
-    state: Dict[str, Any]
-```
-
-**LangChain Equivalent:**
-```python
-memory = ConversationBufferMemory()
-# or ConversationSummaryMemory, etc.
-```
-
-**Verdict:** ⚠️ **Different approach** - You use events, LangChain uses separate memory classes
-
----
-
-### 5. Prompt Engineering
-
-| Feature | Your Framework | LangChain |
-|---------|---------------|-----------|
-| **System Instructions** | ✅ `instructions` parameter | ✅ `SystemMessagePromptTemplate` |
-| **Tool Descriptions** | ✅ Auto-added to instructions | ✅ `format_tool_to_openai_function()` |
-| **Prompt Templates** | ❌ String concatenation | ✅ `ChatPromptTemplate` with variables |
-| **Few-shot Examples** | ❌ Manual | ✅ Built-in support |
-| **Prompt Versioning** | ❌ | ✅ Prompt management tools |
-
-**Your Code:**
-```python
-tool_info = f"\n\nYou have the following tools available..."
-instructions[0] += tool_info
-```
-
-**LangChain Equivalent:**
-```python
-prompt = ChatPromptTemplate.from_messages([
-    ("system", "{system_message}"),
-    ("human", "{input}"),
-])
-```
-
-**Verdict:** ⚠️ **Simpler** - You use strings, LangChain uses templates
-
----
-
-### 6. Structured Output
-
-| Feature | Your Framework | LangChain |
-|---------|---------------|-----------|
-| **Pydantic Models** | ✅ `output_type: Type[BaseModel]` | ✅ `with_structured_output()` |
-| **Type Safety** | ✅ Full type hints | ✅ Full type hints |
-| **Validation** | ✅ Pydantic validation | ✅ Pydantic validation |
-| **Conditional Enforcement** | ✅ Only on final answer | ✅ Always enforced |
-
-**Your Code:**
-```python
-agent = Agent(
-    output_type=AnswerOutput,  # Pydantic model
-    ...
-)
-```
-
-**LangChain Equivalent:**
-```python
-structured_llm = llm.with_structured_output(AnswerOutput)
-```
-
-**Verdict:** ✅ **Very similar** - Both use Pydantic for structured output
-
----
-
-### 7. Observability & Debugging
-
-| Feature | Your Framework | LangChain |
-|---------|---------------|-----------|
-| **Verbose Mode** | ✅ Built-in `verbose=True` | ✅ `verbose=True` parameter |
-| **Trace Display** | ✅ `display_trace()` | ✅ `LangSmith` integration |
-| **Callbacks** | ❌ | ✅ Extensive callback system |
-| **Logging** | Basic print statements | ✅ Structured logging |
-| **Metrics** | ❌ | ✅ Token usage, latency, etc. |
-
-**Your Code:**
-```python
-if self.verbose:
-    print(f"[TOOL CALL] {item.name}")
-```
-
-**LangChain Equivalent:**
-```python
-callbacks = [StdOutCallbackHandler()]
-agent.run(..., callbacks=callbacks)
-```
-
-**Verdict:** ⚠️ **Simpler** - You have basic verbose, LangChain has full observability
-
----
-
-## Key Differences
-
-### What LangChain Has That You Don't
-
-1. **Agent Types**: ReAct, Plan-and-Execute, Self-Ask-with-Search, etc.
-2. **Runnable Interface**: Unified interface for chains, tools, prompts
-3. **Memory Types**: Buffer, Summary, Token-based, Vector store
-4. **Retrieval**: Built-in RAG with vector stores
-5. **Callbacks**: Extensive callback system for hooks
-6. **LangSmith**: Integrated observability platform
-7. **Document Loaders**: 100+ document loaders
-8. **Chains**: Pre-built chains for common tasks
-9. **Agents**: Pre-built agent types (ReAct, etc.)
-10. **Ecosystem**: 100+ integrations
-
-### What You Have That's Unique
-
-1. **Simplicity**: Much easier to understand and modify
-2. **Event-Based History**: Clear event tracking system
-3. **Direct Control**: Less abstraction, more control
-4. **Educational Value**: Perfect for learning agent mechanics
-5. **MCP Integration**: Direct MCP tool loading
-6. **Verbose Mode**: Built-in real-time thinking display
-
----
-
-## Code Pattern Comparison
-
-### Creating an Agent
-
-**Your Framework:**
-```python
-agent = Agent(
-    model=LlmClient(model="gpt-5-mini"),
-    tools=[calculator_tool],
-    instructions="You are a helpful assistant.",
-    output_type=AnswerOutput,
-    verbose=True
-)
-result = await agent.run("What is 2+2?")
-```
-
-**LangChain:**
-```python
-from langchain.agents import create_tool_calling_agent
-from langchain_openai import ChatOpenAI
-
-llm = ChatOpenAI(model="gpt-4")
-tools = [calculator_tool]
-prompt = ChatPromptTemplate.from_messages([...])
-agent = create_tool_calling_agent(llm, tools, prompt)
-agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
-result = agent_executor.invoke({"input": "What is 2+2?"})
-```
-
-**Verdict:** Your API is **much simpler** - 2 lines vs 6+ lines
-
----
-
-### Tool Definition
-
-**Your Framework:**
-```python
-@tool
-def calculator(expression: str) -> float:
-    """Calculate mathematical expressions."""
-    return eval(expression)
-```
-
-**LangChain:**
-```python
-from langchain.tools import tool
-
-@tool
-def calculator(expression: str) -> float:
-    """Calculate mathematical expressions."""
-    return eval(expression)
-```
-
-**Verdict:** ✅ **Nearly identical** - Same decorator pattern
-
----
-
-### Execution Flow
-
-**Your Framework:**
-```
-run() → step() → think() → act() → step() → ...
-```
-
-**LangChain:**
-```
-invoke() → _take_next_step() → agent.plan() → tool_executor.execute() → ...
-```
-
-**Verdict:** ✅ **Same pattern** - Different method names, same flow
-
----
-
-## When to Use Each
-
-### Use Your Framework When:
-- ✅ Learning how agents work
-- ✅ Building simple, focused agents
-- ✅ Need full control over execution
-- ✅ Want minimal dependencies
-- ✅ Prototyping quickly
-- ✅ Educational projects
-
-### Use LangChain When:
-- ✅ Building production systems
-- ✅ Need extensive integrations
-- ✅ Want pre-built agent types
-- ✅ Need observability (LangSmith)
-- ✅ Building complex RAG systems
-- ✅ Enterprise requirements
-
----
-
-## Migration Path
-
-If you wanted to make your framework more LangChain-like, you could add:
-
-1. **Runnable Interface**: Unified interface for all components
-2. **Memory Classes**: Separate memory abstractions
-3. **Callbacks**: Hook system for observability
-4. **Agent Types**: ReAct, Plan-and-Execute, etc.
-5. **Prompt Templates**: Template system instead of strings
-6. **Retries**: Automatic retry logic
-7. **Streaming**: Stream responses and tool results
-
-But honestly, **your simplicity is a feature, not a bug**. LangChain's complexity comes from trying to support every use case. Your framework is perfect for learning and focused use cases.
-
----
-
-## Conclusion
-
-**Your implementation captures ~70% of LangChain's core concepts** but in a much simpler, more understandable way. You've built:
-
-- ✅ The core agent loop
-- ✅ Tool system
-- ✅ LLM integration
-- ✅ Structured output
-- ✅ Context management
-- ✅ Verbose debugging
-
-**You're missing:**
-- ❌ Multiple agent types
-- ❌ Extensive integrations
-- ❌ Memory abstractions
-- ❌ Callback system
-- ❌ Streaming
-- ❌ Enterprise features
-
-**But that's okay!** Your framework is:
-- 🎓 **Better for learning** - You can see exactly what's happening
-- 🚀 **Faster to iterate** - Less abstraction to navigate
-- 🎯 **Focused** - Does one thing well
-- 📖 **Readable** - Easy to understand and modify
-
-**You've built a solid, educational agent framework that demonstrates the core concepts without the complexity.**
-

misc/example.py

@@ -1,65 +0,0 @@
-"""Example usage of the agent framework."""
-
-import asyncio
-import os
-from dotenv import load_dotenv
-from agent_framework import Agent, LlmClient, FunctionTool, load_mcp_tools
-
-load_dotenv()
-
-
-# Example 1: Simple calculator tool
-def calculator(expression: str) -> float:
-    """Calculate mathematical expressions."""
-    return eval(expression)
-
-
-# Example 2: Using the @tool decorator
-from agent_framework import tool
-
-@tool
-def search_web(query: str, max_results: int = 5) -> str:
-    """Search the web for information."""
-    # This is a placeholder - in real usage, you'd call an actual search API
-    return f"Search results for: {query}"
-
-
-async def main():
-    # Create a calculator tool
-    calc_tool = FunctionTool(calculator)
-    
-    # Create the agent
-    agent = Agent(
-        model=LlmClient(model="gpt-5-mini"),
-        tools=[calc_tool, search_web],
-        instructions="You are a helpful assistant that can calculate and search the web.",
-    )
-    
-    # Run the agent
-    result = await agent.run("What is 1234 * 5678?")
-    print(f"Result: {result.output}")
-    print(f"Steps taken: {result.context.current_step}")
-    
-    # Example with MCP tools
-    if os.getenv("TAVILY_API_KEY"):
-        connection = {
-            "command": "npx",
-            "args": ["-y", "tavily-mcp@latest"],
-            "env": {"TAVILY_API_KEY": os.getenv("TAVILY_API_KEY")}
-        }
-        mcp_tools = await load_mcp_tools(connection)
-        
-        agent_with_mcp = Agent(
-            model=LlmClient(model="gpt-5-mini"),
-            tools=[calc_tool, *mcp_tools],
-            instructions="You are a helpful assistant with web search capabilities.",
-        )
-        
-        result = await agent_with_mcp.run("What is the capital of France?")
-        print(f"Result: {result.output}")
-
-
-
-if __name__ == "__main__":
-    asyncio.run(main())
-

misc/notebook_example.ipynb

@@ -1,222 +0,0 @@
-{
-  "cells": [
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "# Using Agent Framework in Jupyter Notebook\n",
-        "\n",
-        "This notebook demonstrates how to use the agent_framework package with structured output.\n"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": 1,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "# Import the framework\n",
-        "from agent_framework import Agent, LlmClient\n",
-        "from pydantic import BaseModel\n",
-        "from typing import Literal, List\n"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": 2,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "# Define your structured output model\n",
-        "class SentimentAnalysis(BaseModel):\n",
-        "    sentiment: Literal[\"positive\", \"negative\", \"neutral\"]\n",
-        "    confidence: float\n",
-        "    key_phrases: List[str]\n"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": 3,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "# Create agent with structured output\n",
-        "agent = Agent(\n",
-        "    model=LlmClient(model=\"gpt-5-mini\"),\n",
-        "    tools=[],\n",
-        "    instructions=\"Analyze the sentiment of the provided text.\",\n",
-        "    output_type=SentimentAnalysis\n",
-        ")\n"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": 4,
-      "metadata": {},
-      "outputs": [
-        {
-          "name": "stdout",
-          "output_type": "stream",
-          "text": [
-            "Sentiment: positive\n",
-            "Confidence: 0.95\n",
-            "Key phrases: ['exceeded my expectations', 'Highly recommend', 'product']\n"
-          ]
-        }
-      ],
-      "source": [
-        "# Run the agent\n",
-        "result = await agent.run(\"This product exceeded my expectations! Highly recommend.\")\n",
-        "\n",
-        "# Access structured output\n",
-        "print(f\"Sentiment: {result.output.sentiment}\")      # \"positive\"\n",
-        "print(f\"Confidence: {result.output.confidence}\")    # 0.92\n",
-        "print(f\"Key phrases: {result.output.key_phrases}\")  # [\"exceeded expectations\", \"highly recommend\"]\n"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "'''\n",
-        "To implement agent, we need tools, execution context, \n",
-        "instructions(system prompt that defines agent behavior) and an llm. \n",
-        "\n",
-        "Event: It is a record of who did what ? like was it user request, \n",
-        "or llm requested tool call, or did we get a result back from the tool etc., \n",
-        "\n",
-        "'''\n",
-        "\n",
-        "from anyio import Event\n",
-        "from agent_framework import ExecutionContext, Message\n",
-        "from agent_framework.agent import AgentResult\n",
-        "\n",
-        "class Agent: ## does this inherit from anything ? \n",
-        "    def init(self, tools, executionContext, llmClient, instructions, maxSteps, verbose, name = \"agent\"):\n",
-        "        self.tools = self._setup_tools(tools or [])\n",
-        "        self.executionContext = executionContext\n",
-        "        self.llmClient = llmClient\n",
-        "        self.instructions = instructions\n",
-        "        self.maxSteps = maxSteps\n",
-        "        self.verbose = verbose\n",
-        "        self.name = name\n",
-        "\n",
-        "    ## step 1 is to setup tools\n",
-        "\n",
-        "    def _setup_tools(self, tools):\n",
-        "        return tools\n",
-        "\n",
-        "    ## step 2 is to define entry point for users.(run method)\n",
-        "\n",
-        "    async def run(self, user_input, context):\n",
-        "\n",
-        "        ## check if there is any previous context, else create\n",
-        "\n",
-        "        if context is None:\n",
-        "            context = ExecutionContext()\n",
-        "\n",
-        "        ## add the user_event to the event\n",
-        "        user_event = Event(\n",
-        "            execution_id = context.execution_id,\n",
-        "            author = 'user',\n",
-        "            content = [Message(role = 'user', content = user_input)]\n",
-        "        )\n",
-        "        ## add the event to context\n",
-        "        context.add_event(user_event)\n",
-        "\n",
-        "        ## if agent doesnt reach final result or max steps, keep performing\n",
-        "        while not context.final_result and context.current_step < self.max_steps:\n",
-        "            ## each step is a think-act cycle\n",
-        "            await self.step(context)\n",
-        "\n",
-        "            ## check if newly performed action is final\n",
-        "            last_event = context.events[-1]\n",
-        "\n",
-        "            # If it is final, then extract the last event and sent it to \n",
-        "            # Agent result along with the context\n",
-        "            if self._is_final_response(last_event):\n",
-        "                context.final_result = self._extract_final_result(last_event)\n",
-        "\n",
-        "        return AgentResult(context.final_result, context = context)\n",
-        "\n",
-        "    # step 3 prepare for llm request\n",
-        "\n",
-        "    def _prepare_llm_request(self, context):\n",
-        "        \n",
-        "        #flatten all the events (why ?)\n",
-        "        flat_contents = []\n",
-        "        for event in context.events:\n",
-        "            flat_contents.extend(event.content)\n",
-        "\n",
-        "        ## with this context, call llm\n",
-        "        return LlmRequest(\n",
-        "        instructions=[self.instructions] if self.instructions else [],\n",
-        "        contents=flat_contents,\n",
-        "        tools=self.tools,\n",
-        "        tool_choice=\"auto\" if self.tools else None,\n",
-        "    )\n",
-        "\n",
-        "    async def step(self, context):\n",
-        "        \n",
-        "        ## write a method for this\n",
-        "        llm_request = self._prepare_llm_request(context)\n",
-        "\n",
-        "        # Get LLM's decision\n",
-        "        llm_response = await self.think(llm_request)\n",
-        "\n",
-        "        response_event = Event(\n",
-        "            execution_id=context.execution_id,\n",
-        "            author=self.name,\n",
-        "            content=llm_response.content,\n",
-        "        )\n",
-        "\n",
-        "    async def think(self, llm_request):\n",
-        "        \"\"\"Get LLM's response/decision.\"\"\"\n",
-        "        return await self.model.generate(llm_request)\n",
-        "\n",
-        "\n",
-        "\n",
-        "\n",
-        "\n",
-        "\n",
-        "\n",
-        "\n",
-        "\n",
-        "\n",
-        "\n"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "Q. LLM Request? \n",
-        "\n",
-        "A. It goes from our agent to LLM call. before sending it, we bundle it with necessary context , prompt and tools."
-      ]
-    }
-  ],
-  "metadata": {
-    "kernelspec": {
-      "display_name": ".venv",
-      "language": "python",
-      "name": "python3"
-    },
-    "language_info": {
-      "codemirror_mode": {
-        "name": "ipython",
-        "version": 3
-      },
-      "file_extension": ".py",
-      "mimetype": "text/x-python",
-      "name": "python",
-      "nbconvert_exporter": "python",
-      "pygments_lexer": "ipython3",
-      "version": "3.12.11"
-    }
-  },
-  "nbformat": 4,
-  "nbformat_minor": 2
-}

misc/tutorials/ADDITIONAL_EXERCISES.md

@@ -1,729 +0,0 @@
-# Additional Exercises: Comprehensive Knowledge Test
-
-This document contains advanced exercises that test your understanding across all topics covered in the tutorial series. These questions require you to integrate concepts from multiple episodes.
-
----
-
-## 🎯 Integration Challenges
-
-### Challenge 1: Build a Multi-Agent System
-Create a system where two agents collaborate to solve a problem:
-- Agent A: Research agent (uses web search)
-- Agent B: Analysis agent (uses calculator and file tools)
-- They should share information through a shared ExecutionContext
-
-**Requirements:**
-- Both agents use the same session
-- Agent A finds information, Agent B analyzes it
-- Track which agent made which decisions
-
-**Hints:**
-- Use shared ExecutionContext
-- Different agent names
-- Coordinate through context.state
-
----
-
-### Challenge 2: Custom Tool with Confirmation
-Create a `delete_file` tool that:
-- Requires user confirmation before execution
-- Shows what file will be deleted
-- Allows user to modify the file path
-- Tracks deletion history in ExecutionContext
-
-**Requirements:**
-- Use `requires_confirmation=True`
-- Custom confirmation message
-- Store deletions in context.state
-- Handle rejection gracefully
-
----
-
-### Challenge 3: Streaming Agent Responses
-Modify the agent to support streaming responses:
-- Stream LLM tokens as they arrive
-- Update ExecutionContext in real-time
-- Allow cancellation mid-stream
-- Maintain full trace even with streaming
-
-**Requirements:**
-- Use LiteLLM streaming
-- Yield tokens as they arrive
-- Handle cancellation
-- Complete trace after streaming
-
----
-
-## 🧠 Design Decision Questions
-
-### Question 1: Why Pydantic for Models but Dataclass for ExecutionContext?
-
-**Your Task:** Write a detailed explanation covering:
-- When to use Pydantic vs Dataclass
-- Performance implications
-- Validation needs
-- Serialization requirements
-- Mutable vs immutable patterns
-
-**Test Your Answer:** Can you explain this to someone who doesn't know Python?
-
----
-
-### Question 2: Tool Execution Error Handling Strategy
-
-**Scenario:** A tool fails during execution. What should happen?
-
-**Your Task:** Design a comprehensive error handling strategy that:
-- Distinguishes between recoverable and fatal errors
-- Allows agent to retry with different parameters
-- Provides meaningful error messages to LLM
-- Logs errors for debugging
-- Maintains execution trace
-
-**Implementation:** Write code that implements your strategy.
-
----
-
-### Question 3: Memory Optimization Trade-offs
-
-**Scenario:** You have a conversation with 1000 messages. Token count is 50,000.
-
-**Your Task:** Design an optimization strategy that:
-- Balances context retention vs token savings
-- Preserves important information
-- Explains what information is being compressed
-- Allows user to see what was summarized
-
-**Consider:**
-- When to use sliding window vs summarization
-- How to preserve user preferences
-- Maintaining tool call history
-- Cost vs quality trade-offs
-
----
-
-## 🐛 Debugging Scenarios
-
-### Scenario 1: Agent Stuck in Loop
-
-**Problem:** Agent keeps calling the same tool with the same arguments repeatedly.
-
-**Your Task:**
-1. Identify possible causes
-2. Write code to detect this pattern
-3. Implement a solution to break the loop
-4. Add logging to track tool call patterns
-
-**Possible Causes:**
-- Tool returning same result
-- LLM not understanding tool output
-- Missing context in tool results
-- Tool definition unclear
-
----
-
-### Scenario 2: Session Not Persisting
-
-**Problem:** Agent doesn't remember previous conversation even with session_id.
-
-**Your Task:**
-1. Trace the session flow from run() to save()
-2. Identify where session might be lost
-3. Add validation to ensure session is saved
-4. Create tests to verify persistence
-
-**Check Points:**
-- Session manager initialization
-- Session loading in run()
-- Session saving after execution
-- Session state updates
-
----
-
-### Scenario 3: Tool Schema Mismatch
-
-**Problem:** LLM calls tool with wrong argument types (e.g., string instead of int).
-
-**Your Task:**
-1. Add validation before tool execution
-2. Convert types when possible (e.g., "5" → 5)
-3. Return helpful error messages to LLM
-4. Log schema mismatches for analysis
-
-**Implementation:** Enhance FunctionTool.execute() with type coercion.
-
----
-
-## 🏗️ Architecture Questions
-
-### Question 1: Extending the Framework
-
-**Task:** Design how you would add these features:
-- **Parallel tool execution**: Execute multiple tools simultaneously
-- **Tool chaining**: One tool's output becomes another's input
-- **Conditional tool execution**: Tools that decide which tool to call next
-- **Tool versioning**: Support multiple versions of the same tool
-
-**Requirements:**
-- Explain the architecture changes needed
-- Show how it integrates with existing code
-- Consider backward compatibility
-- Design the API
-
----
-
-### Question 2: Multi-Provider Support
-
-**Task:** Design a system where:
-- Different tools use different LLM providers
-- Some tools use OpenAI, others use Anthropic
-- Agent can switch providers mid-conversation
-- Cost tracking per provider
-
-**Requirements:**
-- How to configure provider per tool
-- How to handle provider-specific features
-- How to track costs separately
-- How to handle provider failures
-
----
-
-### Question 3: Distributed Agent System
-
-**Task:** Design an architecture where:
-- Agent runs on multiple servers
-- Tools can be on different machines
-- Sessions are shared across instances
-- Load balancing between agents
-
-**Requirements:**
-- Communication protocol
-- Session synchronization
-- Tool discovery across network
-- Failure handling
-
----
-
-## 💡 Real-World Application Scenarios
-
-### Scenario 1: Customer Support Bot
-
-**Requirements:**
-- Access customer database
-- Search knowledge base
-- Create support tickets
-- Escalate to human when needed
-- Remember conversation context
-
-**Your Task:**
-1. Design the tool set needed
-2. Create agent instructions
-3. Implement session management for customers
-4. Add escalation logic
-5. Design conversation flow
-
----
-
-### Scenario 2: Code Review Assistant
-
-**Requirements:**
-- Read code files
-- Analyze code quality
-- Suggest improvements
-- Check for security issues
-- Generate review comments
-
-**Your Task:**
-1. Create tools for code analysis
-2. Design agent prompts for code review
-3. Implement file reading and parsing
-4. Structure review output
-5. Handle large codebases
-
----
-
-### Scenario 3: Research Assistant
-
-**Requirements:**
-- Search multiple sources
-- Summarize findings
-- Compare information
-- Track sources
-- Generate citations
-
-**Your Task:**
-1. Integrate multiple search tools
-2. Create summarization tools
-3. Implement source tracking
-4. Design citation format
-5. Handle conflicting information
-
----
-
-## 🔍 Deep Understanding Questions
-
-### Question 1: Execution Flow Trace
-
-**Task:** Given this code:
-```python
-agent = Agent(
-    model=LlmClient(model="gpt-4o-mini"),
-    tools=[calculator, search_web],
-    max_steps=5
-)
-
-result = await agent.run("What is the weather in NYC and convert 72F to Celsius?")
-```
-
-**Trace the execution:**
-1. List every method call in order
-2. Show what's in ExecutionContext at each step
-3. Show what's sent to LLM at each step
-4. Show what tools are called and when
-5. Show the final ExecutionContext state
-
-**Write it out step-by-step as if you're the agent.**
-
----
-
-### Question 2: Memory Optimization Impact
-
-**Task:** Analyze this conversation:
-- 50 messages total
-- 10 tool calls
-- 5 file reads
-- 3 web searches
-
-**Questions:**
-1. How many tokens without optimization?
-2. How many tokens with sliding window (keep 20)?
-3. How many tokens with compaction?
-4. How many tokens with summarization?
-5. What information is lost in each strategy?
-
-**Create a detailed analysis.**
-
----
-
-### Question 3: Error Propagation
-
-**Task:** Trace what happens when:
-1. LLM API call fails
-2. Tool execution raises exception
-3. Session save fails
-4. Tool not found
-5. Invalid tool arguments
-
-**For each error:**
-- Where does it get caught?
-- What error message is created?
-- How does it affect execution?
-- What does the user see?
-- How is it logged?
-
-**Draw the error flow diagram.**
-
----
-
-## 🎨 Creative Challenges
-
-### Challenge 1: Agent Personality System
-
-**Task:** Design a system where agents have personalities:
-- Each personality affects tool choice
-- Personalities influence response style
-- Personalities can change based on context
-- Track personality in session
-
-**Implementation:**
-- Create personality model
-- Modify agent instructions based on personality
-- Add personality to ExecutionContext
-- Create personality switching logic
-
----
-
-### Challenge 2: Tool Learning System
-
-**Task:** Design a system where agents learn from tool usage:
-- Track which tools work best for which tasks
-- Suggest tool improvements
-- Learn optimal tool parameters
-- Adapt tool selection over time
-
-**Requirements:**
-- Tool usage analytics
-- Success/failure tracking
-- Parameter optimization
-- Learning algorithm
-
----
-
-### Challenge 3: Agent Collaboration Protocol
-
-**Task:** Design a protocol for agents to work together:
-- Agents can request help from other agents
-- Agents can share context
-- Agents can delegate tasks
-- Track multi-agent conversations
-
-**Requirements:**
-- Communication protocol
-- Context sharing mechanism
-- Task delegation system
-- Conflict resolution
-
----
-
-## 📊 Performance Optimization
-
-### Challenge 1: Caching Strategy
-
-**Task:** Implement intelligent caching:
-- Cache LLM responses for identical requests
-- Cache tool results with TTL
-- Cache tool definitions
-- Invalidate cache appropriately
-
-**Requirements:**
-- Design cache structure
-- Implement cache logic
-- Handle cache invalidation
-- Measure cache hit rates
-
----
-
-### Challenge 2: Batch Processing
-
-**Task:** Optimize for processing multiple requests:
-- Batch LLM calls when possible
-- Parallel tool execution
-- Shared session management
-- Resource pooling
-
-**Requirements:**
-- Design batching system
-- Implement parallel execution
-- Handle resource limits
-- Measure performance gains
-
----
-
-### Challenge 3: Token Budget Management
-
-**Task:** Implement token budget system:
-- Set daily/monthly limits
-- Prioritize important conversations
-- Compress old conversations automatically
-- Alert when approaching limits
-
-**Requirements:**
-- Token tracking
-- Budget allocation
-- Prioritization logic
-- Alert system
-
----
-
-## 🔐 Security & Safety
-
-### Challenge 1: Tool Execution Sandbox
-
-**Task:** Create a sandbox for tool execution:
-- Isolate tool execution
-- Limit file system access
-- Restrict network access
-- Monitor resource usage
-
-**Requirements:**
-- Sandbox architecture
-- Permission system
-- Resource limits
-- Monitoring
-
----
-
-### Challenge 2: Input Validation
-
-**Task:** Implement comprehensive input validation:
-- Validate all user inputs
-- Sanitize tool arguments
-- Check for injection attacks
-- Rate limit requests
-
-**Requirements:**
-- Validation rules
-- Sanitization functions
-- Security checks
-- Rate limiting
-
----
-
-### Challenge 3: Audit Logging
-
-**Task:** Create comprehensive audit system:
-- Log all agent actions
-- Track tool executions
-- Monitor session access
-- Generate security reports
-
-**Requirements:**
-- Logging architecture
-- Event tracking
-- Report generation
-- Privacy considerations
-
----
-
-## 🧪 Testing Challenges
-
-### Challenge 1: Comprehensive Test Suite
-
-**Task:** Write tests for:
-- Agent execution flow
-- Tool execution
-- Session persistence
-- Memory optimization
-- Error handling
-- Edge cases
-
-**Requirements:**
-- Unit tests for each component
-- Integration tests
-- Mock LLM responses
-- Test fixtures
-
----
-
-### Challenge 2: Load Testing
-
-**Task:** Create load tests:
-- 100 concurrent agents
-- 1000 messages per minute
-- Session persistence under load
-- Memory optimization under load
-
-**Requirements:**
-- Load testing framework
-- Performance metrics
-- Bottleneck identification
-- Optimization recommendations
-
----
-
-### Challenge 3: Fuzz Testing
-
-**Task:** Implement fuzz testing:
-- Random tool arguments
-- Malformed requests
-- Invalid session IDs
-- Edge case inputs
-
-**Requirements:**
-- Fuzzing strategy
-- Error detection
-- Crash prevention
-- Recovery mechanisms
-
----
-
-## 📝 Reflection Questions
-
-### Question 1: Architecture Review
-
-**Reflect on the framework architecture:**
-1. What are the strongest design decisions?
-2. What would you change if rebuilding?
-3. What's missing for production use?
-4. How would you scale this to 1M users?
-5. What security concerns exist?
-
-**Write a detailed architecture review.**
-
----
-
-### Question 2: Learning Outcomes
-
-**Reflect on what you learned:**
-1. What was the most challenging concept?
-2. Which episode was most valuable?
-3. What would you teach differently?
-4. What additional topics are needed?
-5. How has your understanding evolved?
-
-**Create a learning reflection document.**
-
----
-
-### Question 3: Real-World Application
-
-**Design a real product using this framework:**
-1. What problem does it solve?
-2. What tools are needed?
-3. How does it use sessions?
-4. What optimizations are critical?
-5. How would you deploy it?
-
-**Create a product specification.**
-
----
-
-## 🎯 Mastery Checklist
-
-Test your mastery by completing:
-
-- [ ] Can explain every component's purpose
-- [ ] Can trace execution flow from start to finish
-- [ ] Can debug common issues
-- [ ] Can extend the framework
-- [ ] Can optimize for production
-- [ ] Can design new features
-- [ ] Can explain design decisions
-- [ ] Can teach someone else
-- [ ] Can build a real application
-- [ ] Can identify and fix bugs
-
----
-
-## 💬 Discussion Questions
-
-Use these for study groups or self-reflection:
-
-1. **Trade-offs**: What are the trade-offs between different memory optimization strategies?
-
-2. **Scalability**: How would you scale this framework to handle millions of requests?
-
-3. **Security**: What security vulnerabilities exist and how would you fix them?
-
-4. **Testing**: How would you test an agent framework comprehensively?
-
-5. **Monitoring**: What metrics would you track in production?
-
-6. **Cost**: How would you minimize API costs while maintaining quality?
-
-7. **Reliability**: How would you ensure the agent always responds correctly?
-
-8. **Extensibility**: How would you make the framework more extensible?
-
-9. **Performance**: What are the performance bottlenecks and how to fix them?
-
-10. **User Experience**: How would you improve the user experience?
-
----
-
-## 🏆 Advanced Projects
-
-### Project 1: Agent Framework v2.0
-
-**Task:** Design the next version with:
-- Streaming support
-- WebSocket communication
-- Database sessions
-- Advanced memory
-- Tool marketplace
-- Multi-agent support
-
-**Deliverables:**
-- Architecture design
-- API specification
-- Migration plan
-- Implementation roadmap
-
----
-
-### Project 2: Production Deployment
-
-**Task:** Deploy the framework to production:
-- Docker containerization
-- Kubernetes deployment
-- CI/CD pipeline
-- Monitoring setup
-- Logging system
-- Error tracking
-
-**Deliverables:**
-- Deployment configuration
-- Monitoring dashboards
-- Runbooks
-- Documentation
-
----
-
-### Project 3: Agent Marketplace
-
-**Task:** Build a marketplace for:
-- Sharing agents
-- Sharing tools
-- Agent templates
-- Tool libraries
-- Community contributions
-
-**Deliverables:**
-- Platform design
-- API for sharing
-- Discovery system
-- Rating/review system
-
----
-
-## 📚 Further Learning
-
-After completing these exercises, consider:
-
-1. **Research Papers**: Read papers on agent architectures
-2. **Open Source**: Contribute to agent frameworks
-3. **Build Projects**: Create real applications
-4. **Teach Others**: Share your knowledge
-5. **Stay Updated**: Follow AI agent developments
-
----
-
-## 🎓 Certification Project
-
-**Final Challenge:** Build a complete application that:
-
-1. Uses the agent framework
-2. Implements custom tools
-3. Has session management
-4. Includes memory optimization
-5. Has a web interface
-6. Is production-ready
-7. Has comprehensive tests
-8. Includes documentation
-9. Has monitoring
-10. Is deployed
-
-**This is your capstone project!**
-
----
-
-## 💡 Tips for Success
-
-1. **Start Simple**: Begin with basic implementations
-2. **Test Thoroughly**: Write tests as you build
-3. **Read Code**: Study the actual framework code
-4. **Experiment**: Try different approaches
-5. **Document**: Write down what you learn
-6. **Share**: Discuss with others
-7. **Iterate**: Improve your solutions
-8. **Challenge Yourself**: Try the hard problems
-
----
-
-## 🎯 Success Metrics
-
-You've mastered the framework when you can:
-
-✅ Explain any component to a beginner  
-✅ Debug issues without looking at code  
-✅ Design new features confidently  
-✅ Optimize for specific use cases  
-✅ Build production applications  
-✅ Teach others effectively  
-
-**Keep practicing until you reach all milestones!**
-
----
-
-*Good luck with your learning journey! 🚀*
-

misc/tutorials/ARCHITECTURE_DIAGRAMS.md

@@ -1,450 +0,0 @@
-# Architecture Diagrams
-
-This document contains visual diagrams of the agent framework architecture using Mermaid syntax.
-
----
-
-## System Overview
-
-```mermaid
-graph TB
-    User[User/Application] --> Agent[Agent.run]
-    Agent --> Think[Think: LLM Call]
-    Agent --> Act[Act: Tool Execution]
-    Agent --> Observe[Observe: Process Results]
-    
-    Think --> LlmClient[LlmClient]
-    Act --> Tools[Tools]
-    Observe --> Context[ExecutionContext]
-    
-    LlmClient --> LiteLLM[LiteLLM]
-    Tools --> FunctionTools[FunctionTools]
-    Tools --> MCPTools[MCP Tools]
-    Context --> Session[Session Manager]
-    
-    LiteLLM --> OpenAI[OpenAI API]
-    LiteLLM --> Anthropic[Anthropic API]
-    LiteLLM --> Local[Local Models]
-    
-    Session --> Memory[Memory Storage]
-```
-
----
-
-## Agent Execution Flow
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant Agent
-    participant Context
-    participant LLM
-    participant Tools
-    
-    User->>Agent: run(user_input)
-    Agent->>Context: Create/load ExecutionContext
-    Agent->>Context: Add user event
-    
-    loop Until completion or max_steps
-        Agent->>Agent: step(context)
-        Agent->>LLM: think(llm_request)
-        LLM-->>Agent: LlmResponse (with tool_calls)
-        Agent->>Context: Add response event
-        
-        alt Tool calls present
-            Agent->>Tools: act(context, tool_calls)
-            Tools-->>Agent: ToolResults
-            Agent->>Context: Add tool results event
-        end
-        
-        Agent->>Agent: Check completion
-    end
-    
-    Agent-->>User: AgentResult
-```
-
----
-
-## Data Model Relationships
-
-```mermaid
-classDiagram
-    class ExecutionContext {
-        +str execution_id
-        +List[Event] events
-        +int current_step
-        +Dict state
-        +str final_result
-        +str session_id
-        +add_event()
-        +increment_step()
-    }
-    
-    class Event {
-        +str id
-        +str execution_id
-        +float timestamp
-        +str author
-        +List[ContentItem] content
-    }
-    
-    class Message {
-        +str type
-        +str role
-        +str content
-    }
-    
-    class ToolCall {
-        +str type
-        +str tool_call_id
-        +str name
-        +dict arguments
-    }
-    
-    class ToolResult {
-        +str type
-        +str tool_call_id
-        +str name
-        +str status
-        +list content
-    }
-    
-    class Session {
-        +str session_id
-        +str user_id
-        +List[Event] events
-        +dict state
-        +datetime created_at
-        +datetime updated_at
-    }
-    
-    ExecutionContext "1" *-- "many" Event
-    Event "1" *-- "many" ContentItem
-    ContentItem <|-- Message
-    ContentItem <|-- ToolCall
-    ContentItem <|-- ToolResult
-    Session "1" o-- "many" Event
-```
-
----
-
-## Tool System Architecture
-
-```mermaid
-graph LR
-    PythonFunction[Python Function] --> FunctionTool[FunctionTool]
-    FunctionTool --> BaseTool[BaseTool]
-    BaseTool --> ToolDefinition[Tool Definition JSON Schema]
-    
-    MCPServer[MCP Server] --> MCPTool[MCP Tool]
-    MCPTool --> FunctionTool
-    
-    FunctionTool --> Agent[Agent]
-    Agent --> LLM[LLM API]
-    
-    LLM --> ToolCall[ToolCall]
-    ToolCall --> Agent
-    Agent --> FunctionTool
-    FunctionTool --> ToolResult[ToolResult]
-    ToolResult --> Agent
-```
-
----
-
-## Memory Optimization Flow
-
-```mermaid
-flowchart TD
-    Start[LLM Request Created] --> CountTokens[Count Tokens]
-    CountTokens --> CheckThreshold{Tokens < Threshold?}
-    
-    CheckThreshold -->|Yes| NoOptimization[No Optimization Needed]
-    CheckThreshold -->|No| ApplyCompaction[Apply Compaction]
-    
-    ApplyCompaction --> CountAgain[Count Tokens Again]
-    CountAgain --> CheckAgain{Tokens < Threshold?}
-    
-    CheckAgain -->|Yes| Done[Done]
-    CheckAgain -->|No| ApplySummarization[Apply Summarization]
-    
-    ApplySummarization --> Done
-    NoOptimization --> Done
-```
-
----
-
-## Session Management Flow
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant Agent
-    participant SessionManager
-    participant Storage
-    
-    User->>Agent: run(input, session_id)
-    Agent->>SessionManager: get_or_create(session_id)
-    
-    alt Session exists
-        SessionManager->>Storage: get(session_id)
-        Storage-->>SessionManager: Session
-        SessionManager->>Agent: Load session
-        Agent->>Agent: Restore events/state
-    else New session
-        SessionManager->>Storage: create(session_id)
-        Storage-->>SessionManager: New Session
-        SessionManager->>Agent: New session
-    end
-    
-    Agent->>Agent: Execute agent loop
-    Agent->>SessionManager: save(session)
-    SessionManager->>Storage: Persist session
-    Agent-->>User: Result
-```
-
----
-
-## MCP Integration Flow
-
-```mermaid
-sequenceDiagram
-    participant Agent
-    participant MCPClient[MCP Client]
-    participant MCPServer[MCP Server]
-    participant FunctionTool
-    
-    Agent->>MCPClient: load_mcp_tools(connection)
-    MCPClient->>MCPServer: Connect via stdio
-    MCPServer-->>MCPClient: Connection established
-    
-    MCPClient->>MCPServer: list_tools()
-    MCPServer-->>MCPClient: Tool definitions
-    
-    loop For each MCP tool
-        MCPClient->>FunctionTool: _create_mcp_tool()
-        FunctionTool-->>MCPClient: Wrapped tool
-    end
-    
-    MCPClient-->>Agent: List of FunctionTools
-    
-    Note over Agent,FunctionTool: Agent can now use MCP tools
-    
-    Agent->>FunctionTool: Execute tool
-    FunctionTool->>MCPServer: call_tool(name, args)
-    MCPServer-->>FunctionTool: Result
-    FunctionTool-->>Agent: ToolResult
-```
-
----
-
-## Web Application Architecture
-
-```mermaid
-graph TB
-    Browser[Browser] --> Frontend[HTML/CSS/JS]
-    Frontend --> API[FastAPI Backend]
-    
-    API --> ChatEndpoint[/api/chat]
-    API --> UploadEndpoint[/api/upload]
-    API --> ToolsEndpoint[/api/tools]
-    API --> SessionsEndpoint[/api/sessions]
-    
-    ChatEndpoint --> Agent[Agent Framework]
-    UploadEndpoint --> FileStorage[File Storage]
-    ToolsEndpoint --> ToolRegistry[Tool Registry]
-    SessionsEndpoint --> SessionManager[Session Manager]
-    
-    Agent --> LlmClient[LlmClient]
-    Agent --> Tools[Tools]
-    Agent --> Memory[Memory Manager]
-    
-    LlmClient --> LiteLLM[LiteLLM]
-    Tools --> FunctionTools[Function Tools]
-    Memory --> SessionManager
-```
-
----
-
-## Request/Response Flow
-
-```mermaid
-sequenceDiagram
-    participant Frontend
-    participant API
-    participant Agent
-    participant LLM
-    participant Tools
-    
-    Frontend->>API: POST /api/chat {message, session_id}
-    API->>Agent: run(message, session_id)
-    
-    Agent->>Agent: Load session
-    Agent->>Agent: step(context)
-    Agent->>LLM: generate(request)
-    LLM-->>Agent: Response with tool_calls
-    
-    alt Tool calls present
-        Agent->>Tools: act(context, tool_calls)
-        Tools-->>Agent: ToolResults
-        Agent->>Agent: step(context) [continue]
-    end
-    
-    Agent->>Agent: Save session
-    Agent-->>API: AgentResult
-    API->>API: Format response
-    API-->>Frontend: {response, trace, tools_used}
-    Frontend->>Frontend: Display message
-```
-
----
-
-## Tool Execution Details
-
-```mermaid
-flowchart TD
-    Start[ToolCall Received] --> FindTool[Find Tool by Name]
-    FindTool --> ToolExists{Tool Found?}
-    
-    ToolExists -->|No| Error[Raise ValueError]
-    ToolExists -->|Yes| CheckConfirmation{Requires Confirmation?}
-    
-    CheckConfirmation -->|Yes| Pending[Create PendingToolCall]
-    CheckConfirmation -->|No| Execute[Execute Tool]
-    
-    Execute --> ToolSuccess{Success?}
-    ToolSuccess -->|Yes| SuccessResult[ToolResult: success]
-    ToolSuccess -->|No| ErrorResult[ToolResult: error]
-    
-    Pending --> WaitUser[Wait for User Confirmation]
-    WaitUser --> UserApproved{Approved?}
-    UserApproved -->|Yes| Execute
-    UserApproved -->|No| RejectedResult[ToolResult: rejected]
-    
-    SuccessResult --> Return[Return ToolResult]
-    ErrorResult --> Return
-    RejectedResult --> Return
-    Error --> Return
-```
-
----
-
-## Memory Optimization Strategies
-
-```mermaid
-graph TB
-    Request[LlmRequest] --> Count[Count Tokens]
-    Count --> Threshold{> Threshold?}
-    
-    Threshold -->|No| Skip[Skip Optimization]
-    Threshold -->|Yes| Strategy{Choose Strategy}
-    
-    Strategy --> SlidingWindow[Sliding Window<br/>Keep Recent N]
-    Strategy --> Compaction[Compaction<br/>Replace with References]
-    Strategy --> Summarization[Summarization<br/>LLM Compression]
-    
-    SlidingWindow --> Reduced1[Reduced Tokens]
-    Compaction --> Reduced2[Reduced Tokens]
-    Summarization --> Reduced3[Reduced Tokens]
-    
-    Reduced1 --> Final[Optimized Request]
-    Reduced2 --> Final
-    Reduced3 --> Final
-    Skip --> Final
-```
-
----
-
-## Component Dependencies
-
-```mermaid
-graph TD
-    Agent --> LlmClient
-    Agent --> Tools
-    Agent --> Models
-    Agent --> Memory
-    Agent --> Callbacks
-    
-    LlmClient --> Models
-    LlmClient --> LiteLLM
-    
-    Tools --> Models
-    Tools --> Utils
-    
-    Memory --> Models
-    Memory --> LlmClient
-    
-    Callbacks --> Memory
-    Callbacks --> Models
-    
-    MCP --> Tools
-    MCP --> Models
-    
-    WebApp --> Agent
-    WebApp --> Models
-    
-    Models --> Pydantic
-    Tools --> ABC
-```
-
----
-
-## State Management
-
-```mermaid
-stateDiagram-v2
-    [*] --> Initialized: Agent created
-    Initialized --> Running: run() called
-    Running --> Thinking: step() called
-    Thinking --> Acting: Tool calls received
-    Acting --> Thinking: Tool results processed
-    Thinking --> Completed: Final response
-    Acting --> Completed: Final response
-    Completed --> [*]
-    
-    Running --> Pending: Tool confirmation required
-    Pending --> Running: Confirmation received
-```
-
----
-
-## Error Handling Flow
-
-```mermaid
-flowchart TD
-    Start[Operation] --> Try{Try}
-    Try -->|Success| Success[Return Result]
-    Try -->|Error| Catch[Catch Exception]
-    
-    Catch --> ErrorType{Error Type?}
-    ErrorType -->|LLM Error| LLMError[Return LlmResponse with error_message]
-    ErrorType -->|Tool Error| ToolError[Return ToolResult with error status]
-    ErrorType -->|Network Error| NetworkError[Retry or Return Error]
-    ErrorType -->|Validation Error| ValidationError[Return Validation Error]
-    
-    LLMError --> Log[Log Error]
-    ToolError --> Log
-    NetworkError --> Log
-    ValidationError --> Log
-    
-    Log --> ReturnError[Return Error to User]
-    Success --> [*]
-    ReturnError --> [*]
-```
-
----
-
-## Usage Examples
-
-These diagrams can be:
-1. Included in video thumbnails
-2. Shown during explanations
-3. Added to documentation
-4. Used in presentations
-5. Embedded in blog posts
-
-To render these diagrams:
-- Use Mermaid Live Editor: https://mermaid.live/
-- Use GitHub (renders automatically in .md files)
-- Use VS Code with Mermaid extension
-- Use documentation tools like MkDocs
-

misc/tutorials/EPISODE_01_INTRODUCTION.md

@@ -1,318 +0,0 @@
-# Episode 1: Introduction & Python Foundations
-
-**Duration**: 30 minutes  
-**What to Build**: None (concepts only)  
-**Target Audience**: Intermediate Python developers
-
----
-
-## Episode Structure
-
-### 1. Hook (2 min)
-**Show what we'll build:**
-- Quick demo of the final agent framework
-- Agent using calculator and web search
-- Session persistence demo
-- Web application preview
-
-**Hook Statement**: "By the end of this series, you'll have built a complete AI agent framework from scratch that can reason, use tools, remember conversations, and be deployed as a web app."
-
----
-
-### 2. Problem (3 min)
-**Why build an agent framework?**
-
-**The Problem:**
-- LLMs are powerful but limited to their training data
-- They can't access real-time information
-- They can't perform actions (file operations, API calls, etc.)
-- They need structure to be reliable
-
-**The Solution:**
-- Agent framework that gives LLMs tools
-- Multi-step reasoning loop
-- State management
-- Extensible architecture
-
-**Real-world Use Cases:**
-- Customer support bots with database access
-- Research assistants that can search the web
-- Code assistants that can read/write files
-- Data analysis agents that can process files
-
----
-
-### 3. Concept: Python Patterns We'll Use (20 min)
-
-#### 3.1 Type Hints (5 min)
-
-**Why Type Hints?**
-- Self-documenting code
-- IDE autocomplete
-- Catch errors early
-- Better collaboration
-
-**Common Patterns:**
-```python
-from typing import List, Optional, Literal, Union, Dict, Any
-
-# Basic types
-name: str = "Agent"
-count: int = 5
-
-# Collections
-messages: List[str] = []
-config: Dict[str, Any] = {}
-
-# Optional (can be None)
-result: Optional[str] = None  # Same as: str | None
-
-# Union (multiple types)
-content: Union[str, dict] = "text"  # Same as: str | dict
-
-# Literal (specific values only)
-role: Literal["user", "assistant", "system"] = "user"
-```
-
-**Live Demo:**
-- Show IDE autocomplete with type hints
-- Show what happens without type hints
-- Explain `Optional` vs required parameters
-
----
-
-#### 3.2 Pydantic (7 min)
-
-**What is Pydantic?**
-- Data validation library
-- Runtime type checking
-- Automatic serialization
-
-**Basic Example:**
-```python
-from pydantic import BaseModel, Field
-
-class Message(BaseModel):
-    role: Literal["user", "assistant"]
-    content: str
-
-# Valid
-msg = Message(role="user", content="Hello")
-print(msg.role)  # "user"
-
-# Invalid - raises ValidationError
-msg = Message(role="user")  # Missing 'content'!
-```
-
-**Field Defaults:**
-```python
-from datetime import datetime
-import uuid
-
-class Event(BaseModel):
-    event_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
-    timestamp: float = Field(default_factory=lambda: datetime.now().timestamp())
-    content: List[str] = Field(default_factory=list)  # NOT content: List[str] = []
-```
-
-**Why Field(default_factory)?**
-- Prevents shared mutable defaults
-- Each instance gets a new list/dict
-- Critical for avoiding bugs
-
-**Serialization:**
-```python
-# Model to dict
-data = msg.model_dump()
-
-# Model to JSON
-json_str = msg.model_dump_json()
-
-# Dict to model
-msg2 = Message.model_validate({"role": "user", "content": "hi"})
-```
-
-**When to Use Pydantic:**
-- Data crossing boundaries (API requests/responses)
-- User input validation
-- Configuration files
-- External data
-
----
-
-#### 3.3 Dataclasses (5 min)
-
-**What are Dataclasses?**
-- Lightweight data containers
-- Less overhead than Pydantic
-- Mutable by default
-
-**Example:**
-```python
-from dataclasses import dataclass, field
-from typing import List, Dict, Any
-
-@dataclass
-class ExecutionContext:
-    execution_id: str = field(default_factory=lambda: str(uuid.uuid4()))
-    events: List[Event] = field(default_factory=list)
-    current_step: int = 0
-    state: Dict[str, Any] = field(default_factory=dict)
-    
-    def add_event(self, event: Event):
-        self.events.append(event)
-```
-
-**Pydantic vs Dataclass:**
-| Feature | Pydantic | Dataclass |
-|---------|----------|-----------|
-| Validation | Yes | No |
-| JSON serialization | Built-in | Manual |
-| Performance | Slower | Faster |
-| Use Case | External data | Internal state |
-
-**Our Rule:**
-- **Pydantic** for data crossing boundaries
-- **Dataclass** for internal mutable state
-
----
-
-#### 3.4 Async/Await (3 min)
-
-**Why Async?**
-- LLM API calls take seconds
-- Without async, program waits doing nothing
-- With async, can do other work while waiting
-
-**Basic Example:**
-```python
-import asyncio
-
-async def call_llm(prompt: str):
-    await asyncio.sleep(2)  # Simulates API call
-    return f"Response to: {prompt}"
-
-# Sequential - takes 6 seconds
-async def sequential():
-    results = []
-    for prompt in ["A", "B", "C"]:
-        results.append(await call_llm(prompt))
-    return results
-
-# Concurrent - takes 2 seconds
-async def concurrent():
-    results = await asyncio.gather(
-        call_llm("A"),
-        call_llm("B"),
-        call_llm("C")
-    )
-    return results
-```
-
-**Key Rules:**
-1. `async` functions must be `await`ed
-2. `await` only works inside `async` functions
-3. Use `asyncio.run()` at top level
-
-**In Jupyter:**
-- Can use `await` directly (event loop already running)
-
----
-
-### 4. Demo: Working Agent (3 min)
-
-**Show the Final Product:**
-```python
-from agent_framework import Agent, LlmClient
-from agent_tools import calculator, search_web
-
-agent = Agent(
-    model=LlmClient(model="gpt-4o-mini"),
-    tools=[calculator, search_web],
-    instructions="You are a helpful assistant.",
-    max_steps=10
-)
-
-result = await agent.run("What is 123 * 456?")
-print(result.output)
-```
-
-**What Happens:**
-1. Agent receives user input
-2. Calls LLM with tools available
-3. LLM decides to use calculator
-4. Agent executes calculator tool
-5. Returns result to user
-
-**Show Trace:**
-- Display execution trace
-- Show each step
-- Highlight tool calls
-
----
-
-### 5. Next Steps (2 min)
-
-**Preview Episode 2:**
-- Making your first LLM API call
-- Understanding chat completion format
-- Building a simple LLM wrapper
-
-**What to Prepare:**
-- Python 3.10+ installed
-- OpenAI API key (or other provider)
-- Code editor ready
-
-**Repository:**
-- GitHub link
-- Each episode has a branch
-- Follow along with code
-
----
-
-## Key Takeaways
-
-1. **Type hints** make code self-documenting
-2. **Pydantic** validates data at runtime
-3. **Dataclasses** are lightweight for internal state
-4. **Async/await** enables concurrent operations
-5. **Field(default_factory=...)** prevents shared mutable defaults
-
----
-
-## Common Questions
-
-**Q: Do I need to know advanced Python?**  
-A: Intermediate level is enough. Know functions, classes, dictionaries, and basic async.
-
-**Q: Can I use this with local models?**  
-A: Yes! LiteLLM supports Ollama and other local providers.
-
-**Q: How is this different from LangChain?**  
-A: We're building from scratch to understand every detail. LangChain is great but hides complexity.
-
-**Q: What if I get stuck?**  
-A: Each episode builds on the previous. Pause, rewatch, and check the GitHub branches.
-
----
-
-## Resources
-
-- [Pydantic Documentation](https://docs.pydantic.dev/)
-- [Python Type Hints](https://docs.python.org/3/library/typing.html)
-- [Async/Await Guide](https://docs.python.org/3/library/asyncio.html)
-- [Repository](https://github.com/yourusername/ai-agent-from-scratch)
-
----
-
-## Exercises (Optional)
-
-1. Create a Pydantic model for a `User` with name, email, and age
-2. Create a dataclass for `AppState` with a list of users
-3. Write an async function that makes 3 concurrent API calls
-4. Experiment with type hints in your IDE
-
----
-
-**Next Episode**: [Episode 2: Your First LLM Call](./EPISODE_02_LLM_CALL.md)
-

misc/tutorials/EPISODE_02_LLM_CALL.md

@@ -1,395 +0,0 @@
-# Episode 2: Your First LLM Call
-
-**Duration**: 25 minutes  
-**What to Build**: Simple LLM wrapper script  
-**Target Audience**: Intermediate Python developers
-
----
-
-## Episode Structure
-
-### 1. Hook (2 min)
-**Show what we'll build:**
-- Simple LLM client that can chat
-- Multi-turn conversation
-- Error handling
-
-**Hook Statement**: "Today we'll build the foundation that lets us talk to LLMs. This is the bridge between our Python code and the AI."
-
----
-
-### 2. Problem (3 min)
-**Why do we need an LLM client?**
-
-**The Challenge:**
-- Different providers have different APIs
-- Message format is complex
-- Error handling is crucial
-- We need a unified interface
-
-**The Solution:**
-- Abstract the API complexity
-- Standardize message format
-- Handle errors gracefully
-- Support multiple providers
-
----
-
-### 3. Concept: Understanding Chat Completion APIs (5 min)
-
-#### 3.1 Message Format
-
-**The Standard Format:**
-```python
-messages = [
-    {"role": "system", "content": "You are a helpful assistant."},
-    {"role": "user", "content": "What is 2+2?"},
-    {"role": "assistant", "content": "2+2 equals 4."},
-    {"role": "user", "content": "And 3+3?"},
-]
-```
-
-**Roles Explained:**
-- `system`: Sets behavior/personality (optional but recommended)
-- `user`: Human's messages
-- `assistant`: AI's previous responses
-- `tool`: Tool execution results (we'll cover this later)
-
-**Key Point**: LLMs are **stateless**. You must send the full conversation history each time.
-
----
-
-#### 3.2 Making API Calls
-
-**Direct OpenAI:**
-```python
-from openai import OpenAI
-
-client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
-response = client.chat.completions.create(
-    model="gpt-4o-mini",
-    messages=[{"role": "user", "content": "Hello!"}]
-)
-print(response.choices[0].message.content)
-```
-
-**LiteLLM (Multi-Provider):**
-```python
-from litellm import completion
-
-# OpenAI
-response = completion(
-    model="gpt-4o-mini",
-    messages=[{"role": "user", "content": "Hello!"}]
-)
-
-# Anthropic (same interface!)
-response = completion(
-    model="anthropic/claude-3-sonnet",
-    messages=[{"role": "user", "content": "Hello!"}]
-)
-
-# Local models
-response = completion(
-    model="ollama/llama2",
-    messages=[{"role": "user", "content": "Hello!"}]
-)
-```
-
-**Why LiteLLM?**
-- Unified interface for all providers
-- Easy to switch models
-- Handles provider differences
-
----
-
-#### 3.3 Async Calls
-
-**Why Async?**
-- API calls take 1-5 seconds
-- Don't block the program
-- Can make multiple calls concurrently
-
-```python
-from litellm import acompletion
-
-async def get_response(prompt: str) -> str:
-    response = await acompletion(
-        model="gpt-4o-mini",
-        messages=[{"role": "user", "content": prompt}]
-    )
-    return response.choices[0].message.content
-
-# Run it
-result = asyncio.run(get_response("What is Python?"))
-```
-
----
-
-### 4. Live Coding: Building SimpleLlmClient (15 min)
-
-#### Step 1: Setup (2 min)
-```python
-# simple_llm_client.py
-import os
-from typing import Optional
-from litellm import acompletion
-from dotenv import load_dotenv
-
-load_dotenv()
-```
-
-#### Step 2: Response Model (3 min)
-```python
-from pydantic import BaseModel
-
-class LlmResponse(BaseModel):
-    """Standardized response from LLM."""
-    content: Optional[str] = None
-    error_message: Optional[str] = None
-    
-    @property
-    def success(self) -> bool:
-        return self.error_message is None
-```
-
-**Why This Model?**
-- Standardized interface
-- Error handling built-in
-- Easy to check success
-
-#### Step 3: Client Class (5 min)
-```python
-class SimpleLlmClient:
-    """A simple wrapper around LLM API calls."""
-    
-    def __init__(self, model: str = "gpt-4o-mini", temperature: float = 0.7):
-        self.model = model
-        self.temperature = temperature
-    
-    async def generate(self, messages: list[dict]) -> LlmResponse:
-        """Generate a response from the LLM."""
-        try:
-            response = await acompletion(
-                model=self.model,
-                messages=messages,
-                temperature=self.temperature,
-            )
-            
-            return LlmResponse(
-                content=response.choices[0].message.content
-            )
-            
-        except Exception as e:
-            return LlmResponse(
-                error_message=str(e)
-            )
-```
-
-**Key Points:**
-- Wraps API complexity
-- Handles errors gracefully
-- Returns standardized response
-
-#### Step 4: Testing (3 min)
-```python
-async def main():
-    client = SimpleLlmClient()
-    
-    response = await client.generate([
-        {"role": "system", "content": "You are helpful."},
-        {"role": "user", "content": "What is 2+2?"}
-    ])
-    
-    if response.success:
-        print(response.content)
-    else:
-        print(f"Error: {response.error_message}")
-
-import asyncio
-asyncio.run(main())
-```
-
-#### Step 5: Multi-Turn Conversation (2 min)
-```python
-async def chat():
-    client = SimpleLlmClient()
-    
-    # Maintain conversation history
-    messages = [
-        {"role": "system", "content": "You are a math tutor."}
-    ]
-    
-    # Turn 1
-    messages.append({"role": "user", "content": "What is 5 x 3?"})
-    response = await client.generate(messages)
-    print(f"AI: {response.content}")
-    
-    # Add AI response to history
-    messages.append({"role": "assistant", "content": response.content})
-    
-    # Turn 2 (AI remembers because we sent full history)
-    messages.append({"role": "user", "content": "Now divide that by 3"})
-    response = await client.generate(messages)
-    print(f"AI: {response.content}")  # Should say 5
-```
-
-**Key Point**: Must maintain full conversation history.
-
----
-
-### 5. Understanding the Response (2 min)
-
-**Response Structure:**
-```python
-response = await acompletion(...)
-
-# The response object
-print(response.model)           # "gpt-4o-mini"
-print(response.choices)         # List of completions
-
-# The main content
-choice = response.choices[0]
-print(choice.message.role)      # "assistant"
-print(choice.message.content)   # "Hello! How can I help you?"
-print(choice.finish_reason)     # "stop" or "tool_calls" or "length"
-
-# Token usage (for cost tracking)
-print(response.usage.prompt_tokens)      # Tokens in input
-print(response.usage.completion_tokens)  # Tokens in output
-print(response.usage.total_tokens)       # Total
-```
-
-**Finish Reasons:**
-- `stop`: Normal completion
-- `tool_calls`: Model wants to use a tool (we'll cover this)
-- `length`: Hit max token limit
-- `content_filter`: Content was filtered
-
----
-
-### 6. Error Handling (3 min)
-
-**Common Errors:**
-```python
-from litellm.exceptions import (
-    RateLimitError,
-    APIError,
-    AuthenticationError,
-    Timeout
-)
-
-async def safe_completion(messages: list) -> str | None:
-    try:
-        response = await acompletion(
-            model="gpt-4o-mini",
-            messages=messages,
-            timeout=30
-        )
-        return response.choices[0].message.content
-        
-    except AuthenticationError:
-        print("Invalid API key!")
-        return None
-        
-    except RateLimitError:
-        print("Rate limited - wait and retry")
-        await asyncio.sleep(60)
-        return await safe_completion(messages)  # Retry
-        
-    except Timeout:
-        print("Request timed out")
-        return None
-        
-    except APIError as e:
-        print(f"API error: {e}")
-        return None
-```
-
-**Best Practices:**
-- Always handle errors
-- Provide meaningful error messages
-- Implement retry logic for rate limits
-- Set timeouts
-
----
-
-### 7. Demo: Working Client (2 min)
-
-**Show:**
-- Single message
-- Multi-turn conversation
-- Error handling
-- Different models
-
----
-
-### 8. Next Steps (1 min)
-
-**Preview Episode 3:**
-- Building data models (Message, ToolCall, etc.)
-- Why we need structured models
-- Pydantic validation
-
-**What We Built:**
-- Simple LLM client
-- Error handling
-- Multi-turn conversations
-
----
-
-## Key Takeaways
-
-1. LLM APIs are **stateless** - send full history each time
-2. **LiteLLM** provides unified interface for multiple providers
-3. **Async** is essential for non-blocking operations
-4. **Error handling** is crucial for production
-5. **Message format** is standardized across providers
-
----
-
-## Common Mistakes
-
-**Mistake 1: Forgetting conversation history**
-```python
-# Wrong - AI doesn't remember
-response1 = await client.generate([{"role": "user", "content": "My name is Alice"}])
-response2 = await client.generate([{"role": "user", "content": "What's my name?"}])  # Doesn't know!
-
-# Right - Maintain history
-messages = [{"role": "user", "content": "My name is Alice"}]
-response1 = await client.generate(messages)
-messages.append({"role": "assistant", "content": response1.content})
-messages.append({"role": "user", "content": "What's my name?"})
-response2 = await client.generate(messages)  # Knows!
-```
-
-**Mistake 2: Not handling errors**
-```python
-# Wrong - crashes on error
-response = await acompletion(...)
-print(response.choices[0].message.content)  # Might crash!
-
-# Right - handle errors
-try:
-    response = await acompletion(...)
-    if response.choices[0].message.content:
-        print(response.choices[0].message.content)
-except Exception as e:
-    print(f"Error: {e}")
-```
-
----
-
-## Exercises
-
-1. Add retry logic with exponential backoff
-2. Implement streaming responses
-3. Add token usage tracking
-4. Support temperature and other parameters
-
----
-
-**Previous Episode**: [Episode 1: Introduction](./EPISODE_01_INTRODUCTION.md)  
-**Next Episode**: [Episode 3: Core Data Models](./EPISODE_03_DATA_MODELS.md)
-

misc/tutorials/EPISODE_03_DATA_MODELS.md

@@ -1,547 +0,0 @@
-# Episode 3: Core Data Models
-
-**Duration**: 35 minutes  
-**What to Build**: `agent_framework/models.py`  
-**Target Audience**: Intermediate Python developers
-
----
-
-## Episode Structure
-
-### 1. Hook (2 min)
-**Show what we'll build:**
-- Complete data model structure
-- Type-safe message handling
-- Execution tracking
-- Tool confirmation workflow
-
-**Hook Statement**: "Today we'll build the data structures that power our entire agent framework. These models ensure type safety and make our code predictable."
-
----
-
-### 2. Problem (3 min)
-**Why do we need structured data models?**
-
-**The Challenge:**
-- Raw dictionaries are error-prone
-- No validation
-- Hard to understand
-- Easy to make mistakes
-
-**The Solution:**
-- Pydantic models for validation
-- Type hints for clarity
-- Structured data flow
-- Self-documenting code
-
----
-
-### 3. Concept: Building Our Models (25 min)
-
-#### 3.1 Message Model (3 min)
-
-**What is a Message?**
-- Text content in conversation
-- Has a role (system, user, assistant)
-- Simple but critical
-
-**Implementation:**
-```python
-from pydantic import BaseModel
-from typing import Literal
-
-class Message(BaseModel):
-    """A text message in the conversation."""
-    type: Literal["message"] = "message"
-    role: Literal["system", "user", "assistant"]
-    content: str
-```
-
-**Why Literal?**
-- Only specific values allowed
-- Catches typos at runtime
-- Self-documenting
-
-**Live Coding**: Build Message model
-
----
-
-#### 3.2 ToolCall Model (3 min)
-
-**What is a ToolCall?**
-- LLM's request to execute a tool
-- Contains tool name and arguments
-- Has unique ID for tracking
-
-**Implementation:**
-```python
-class ToolCall(BaseModel):
-    """LLM's request to execute a tool."""
-    type: Literal["tool_call"] = "tool_call"
-    tool_call_id: str
-    name: str
-    arguments: dict
-```
-
-**Key Fields:**
-- `tool_call_id`: Links to ToolResult
-- `name`: Which tool to call
-- `arguments`: Parameters for the tool
-
-**Live Coding**: Build ToolCall model
-
----
-
-#### 3.3 ToolResult Model (3 min)
-
-**What is a ToolResult?**
-- Outcome of tool execution
-- Success or error status
-- Contains output or error message
-
-**Implementation:**
-```python
-class ToolResult(BaseModel):
-    """Result from tool execution."""
-    type: Literal["tool_result"] = "tool_result"
-    tool_call_id: str
-    name: str
-    status: Literal["success", "error"]
-    content: list
-```
-
-**Why list for content?**
-- Can have multiple outputs
-- Flexible for different tools
-- Matches API format
-
-**Live Coding**: Build ToolResult model
-
----
-
-#### 3.4 ContentItem Union (2 min)
-
-**What is ContentItem?**
-- Union type for all content types
-- Used in events and requests
-- Type-safe polymorphism
-
-**Implementation:**
-```python
-ContentItem = Union[Message, ToolCall, ToolResult]
-```
-
-**Why Union?**
-- Events can contain any content type
-- Type checker understands all possibilities
-- Runtime validation via Pydantic
-
-**Live Coding**: Define ContentItem
-
----
-
-#### 3.5 ToolConfirmation Model (3 min)
-
-**What is ToolConfirmation?**
-- User's decision on a pending tool call
-- Can approve or reject
-- Can modify arguments before execution
-
-**Implementation:**
-```python
-class ToolConfirmation(BaseModel):
-    """User's decision on a pending tool call."""
-    
-    tool_call_id: str
-    approved: bool
-    modified_arguments: dict | None = None
-    reason: str | None = None  # Reason for rejection (if not approved)
-```
-
-**Why This Model?**
-- Some tools are dangerous (delete file, send email)
-- Users should approve before execution
-- Allows argument modification (e.g., change file path)
-- Captures rejection reasons for debugging
-
-**Use Cases:**
-- Delete file confirmation
-- API call approval
-- Email sending confirmation
-- Database modification
-
-**Live Coding**: Build ToolConfirmation model
-
----
-
-#### 3.6 PendingToolCall Model (2 min)
-
-**What is PendingToolCall?**
-- A tool call awaiting user confirmation
-- Contains the original ToolCall
-- Has a confirmation message to show user
-
-**Implementation:**
-```python
-class PendingToolCall(BaseModel):
-    """A tool call awaiting user confirmation."""
-    
-    tool_call: ToolCall
-    confirmation_message: str
-```
-
-**Key Points:**
-- Wraps the original ToolCall
-- `confirmation_message` explains what will happen
-- Agent pauses until user responds
-
-**Flow:**
-1. Agent decides to call dangerous tool
-2. Creates PendingToolCall with message
-3. Returns to user for approval
-4. User submits ToolConfirmation
-5. Agent continues or skips based on approval
-
-**Live Coding**: Build PendingToolCall model
-
----
-
-#### 3.7 Event Model (4 min)
-
-**What is an Event?**
-- Recorded step in execution
-- Contains one or more content items
-- Has timestamp and author
-
-**Implementation:**
-```python
-import uuid
-from datetime import datetime
-
-class Event(BaseModel):
-    """A recorded occurrence during agent execution."""
-    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
-    execution_id: str
-    timestamp: float = Field(default_factory=lambda: datetime.now().timestamp())
-    author: str  # "user" or agent name
-    content: List[ContentItem] = Field(default_factory=list)
-```
-
-**Key Points:**
-- `default_factory` for unique IDs
-- Timestamp for ordering
-- Author tracks who created it
-- Content list can be empty
-
-**Live Coding**: Build Event model
-
----
-
-#### 3.8 ExecutionContext Dataclass (5 min)
-
-**What is ExecutionContext?**
-- Central state container
-- Mutable (needs to be dataclass)
-- Tracks entire execution
-
-**Implementation:**
-```python
-from dataclasses import dataclass, field
-from typing import Dict, Any, Optional
-
-@dataclass
-class ExecutionContext:
-    """Central storage for all execution state."""
-    
-    execution_id: str = field(default_factory=lambda: str(uuid.uuid4()))
-    events: List[Event] = field(default_factory=list)
-    current_step: int = 0
-    state: Dict[str, Any] = field(default_factory=dict)
-    final_result: Optional[str | BaseModel] = None
-    session_id: Optional[str] = None  # Link to session for persistence
-    
-    def add_event(self, event: Event):
-        """Append an event to the execution history."""
-        self.events.append(event)
-    
-    def increment_step(self):
-        """Move to the next execution step."""
-        self.current_step += 1
-```
-
-**Why Dataclass?**
-- Mutable state needs to be lightweight
-- No validation needed (internal use)
-- Better performance
-
-**Key Fields:**
-- `state`: Store pending tool calls, confirmations, custom data
-- `session_id`: Links to session for persistence
-
-**Live Coding**: Build ExecutionContext
-
----
-
-### 4. Testing Our Models (3 min)
-
-**Test Message:**
-```python
-msg = Message(role="user", content="Hello")
-print(msg.role)  # "user"
-print(msg.type)  # "message"
-```
-
-**Test ToolCall:**
-```python
-tool_call = ToolCall(
-    tool_call_id="call_123",
-    name="calculator",
-    arguments={"expression": "2+2"}
-)
-print(tool_call.name)  # "calculator"
-```
-
-**Test ToolConfirmation:**
-```python
-# User approves with modification
-confirmation = ToolConfirmation(
-    tool_call_id="call_123",
-    approved=True,
-    modified_arguments={"expression": "2+3"}  # Changed!
-)
-print(confirmation.approved)  # True
-
-# User rejects with reason
-rejection = ToolConfirmation(
-    tool_call_id="call_456",
-    approved=False,
-    reason="I don't want to delete that file"
-)
-print(rejection.reason)  # "I don't want to delete that file"
-```
-
-**Test PendingToolCall:**
-```python
-pending = PendingToolCall(
-    tool_call=tool_call,
-    confirmation_message="The agent wants to calculate '2+2'. Do you approve?"
-)
-print(pending.confirmation_message)
-```
-
-**Test Event:**
-```python
-event = Event(
-    execution_id="exec_123",
-    author="user",
-    content=[Message(role="user", content="Hello")]
-)
-print(len(event.content))  # 1
-```
-
-**Test ExecutionContext:**
-```python
-context = ExecutionContext()
-context.add_event(event)
-print(context.current_step)  # 0
-context.increment_step()
-print(context.current_step)  # 1
-
-# Store pending tool calls in state
-context.state["pending_tool_calls"] = [pending.model_dump()]
-```
-
----
-
-### 5. Why Pydantic vs Dataclass? (2 min)
-
-**Pydantic (Message, ToolCall, ToolResult, Event, ToolConfirmation, PendingToolCall):**
-- Data crossing boundaries
-- Needs validation
-- Serialization required
-- Immutable by default
-
-**Dataclass (ExecutionContext):**
-- Internal mutable state
-- No validation needed
-- Performance critical
-- Frequent updates
-
-**Rule of Thumb:**
-- External data → Pydantic
-- Internal state → Dataclass
-
----
-
-### 6. Demo: Complete Models (2 min)
-
-**Show:**
-- All models working together
-- Type safety in action
-- Validation catching errors
-- Serialization working
-- Confirmation workflow
-
----
-
-### 7. Next Steps (1 min)
-
-**Preview Episode 4:**
-- Building the LLM client
-- Converting our models to API format
-- Parsing API responses
-
-**What We Built:**
-- 7 Pydantic models: Message, ToolCall, ToolResult, ToolConfirmation, PendingToolCall, Event
-- 1 Dataclass: ExecutionContext
-- ContentItem union type
-- Complete data model structure matching actual codebase
-
----
-
-## Key Takeaways
-
-1. **Pydantic** validates data at runtime
-2. **Literal types** constrain values
-3. **Union types** enable polymorphism
-4. **Field(default_factory=...)** prevents shared defaults
-5. **Dataclass** for mutable internal state
-6. **ToolConfirmation** enables user approval workflow
-7. **PendingToolCall** pauses execution for confirmation
-
----
-
-## Common Mistakes
-
-**Mistake 1: Mutable default arguments**
-```python
-# Wrong
-class BadEvent(BaseModel):
-    content: List[str] = []  # Shared across instances!
-
-# Right
-class GoodEvent(BaseModel):
-    content: List[str] = Field(default_factory=list)  # New list each time
-```
-
-**Mistake 2: Missing type hints**
-```python
-# Wrong - no type safety
-def process(event):
-    return event.content
-
-# Right - type checker helps
-def process(event: Event) -> List[ContentItem]:
-    return event.content
-```
-
-**Mistake 3: Forgetting optional fields**
-```python
-# Wrong - reason required even for approval
-class BadConfirmation(BaseModel):
-    approved: bool
-    reason: str  # Always required!
-
-# Right - reason optional
-class GoodConfirmation(BaseModel):
-    approved: bool
-    reason: str | None = None  # Only needed for rejection
-```
-
----
-
-## Exercises
-
-1. **Build ToolConfirmation Validator**: Add validation that `reason` is required when `approved=False`
-2. **Create Helper Function**: Write `extract_pending_calls(context: ExecutionContext) -> List[PendingToolCall]`
-3. **Add Metadata to Event**: Add an optional `metadata: dict` field to Event for custom data
-4. **Create ToolCallWithResult Model**: Combine ToolCall and ToolResult into a single model for reporting
-
----
-
-## Complete models.py File
-
-```python
-"""Core data models for the agent framework."""
-
-from typing import Literal, Union, List, Dict, Optional, Any
-from pydantic import BaseModel, Field
-from dataclasses import dataclass, field
-import uuid
-from datetime import datetime
-
-
-class Message(BaseModel):
-    """A text message in the conversation."""
-    type: Literal["message"] = "message"
-    role: Literal["system", "user", "assistant"]
-    content: str
-
-
-class ToolCall(BaseModel):
-    """LLM's request to execute a tool."""
-    type: Literal["tool_call"] = "tool_call"
-    tool_call_id: str
-    name: str
-    arguments: dict
-
-
-class ToolResult(BaseModel):
-    """Result from tool execution."""
-    type: Literal["tool_result"] = "tool_result"
-    tool_call_id: str
-    name: str
-    status: Literal["success", "error"]
-    content: list
-
-
-ContentItem = Union[Message, ToolCall, ToolResult]
-
-
-class ToolConfirmation(BaseModel):
-    """User's decision on a pending tool call."""
-    
-    tool_call_id: str
-    approved: bool
-    modified_arguments: dict | None = None
-    reason: str | None = None
-
-
-class PendingToolCall(BaseModel):
-    """A tool call awaiting user confirmation."""
-    
-    tool_call: ToolCall
-    confirmation_message: str
-
-
-class Event(BaseModel):
-    """A recorded occurrence during agent execution."""
-    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
-    execution_id: str
-    timestamp: float = Field(default_factory=lambda: datetime.now().timestamp())
-    author: str
-    content: List[ContentItem] = Field(default_factory=list)
-
-
-@dataclass
-class ExecutionContext:
-    """Central storage for all execution state."""
-    
-    execution_id: str = field(default_factory=lambda: str(uuid.uuid4()))
-    events: List[Event] = field(default_factory=list)
-    current_step: int = 0
-    state: Dict[str, Any] = field(default_factory=dict)
-    final_result: Optional[str | BaseModel] = None
-    session_id: Optional[str] = None
-    
-    def add_event(self, event: Event):
-        self.events.append(event)
-    
-    def increment_step(self):
-        self.current_step += 1
-```
-
----
-
-**Previous Episode**: [Episode 2: Your First LLM Call](./EPISODE_02_LLM_CALL.md)  
-**Next Episode**: [Episode 4: The LLM Client](./EPISODE_04_LLM_CLIENT.md)

misc/tutorials/EPISODE_04_LLM_CLIENT.md

@@ -1,377 +0,0 @@
-# Episode 4: The LLM Client
-
-**Duration**: 30 minutes  
-**What to Build**: `agent_framework/llm.py`  
-**Target Audience**: Intermediate Python developers
-
----
-
-## Episode Structure
-
-### 1. Hook (2 min)
-**Show what we'll build:**
-- Complete LLM client abstraction
-- Request/response models
-- Message format conversion
-
-**Hook Statement**: "Today we'll build the bridge between our data models and the LLM API. This client will handle all the complexity of API communication."
-
----
-
-### 2. Problem (3 min)
-**Why do we need an LLM client abstraction?**
-
-**The Challenge:**
-- API format is different from our models
-- Need to convert back and forth
-- Error handling is complex
-- Multiple providers have different formats
-
-**The Solution:**
-- Request/response models
-- Conversion functions
-- Unified interface
-- Error handling built-in
-
----
-
-### 3. Concept: Request/Response Pattern (5 min)
-
-**The Pattern:**
-1. Create `LlmRequest` from our models
-2. Convert to API format
-3. Call API
-4. Parse response into `LlmResponse`
-5. Return our models
-
-**Benefits:**
-- Type safety
-- Easy to test
-- Provider agnostic
-- Clear data flow
-
----
-
-### 4. Live Coding: Building the Client (20 min)
-
-#### Step 1: Request Model (3 min)
-```python
-from pydantic import BaseModel, Field
-from typing import List, Optional
-from .models import ContentItem
-from .tools import BaseTool
-
-class LlmRequest(BaseModel):
-    """Request object for LLM calls."""
-    instructions: List[str] = Field(default_factory=list)
-    contents: List[ContentItem] = Field(default_factory=list)
-    tools: List[BaseTool] = Field(default_factory=list)
-    tool_choice: Optional[str] = 'auto'
-```
-
-**Key Fields:**
-- `instructions`: System messages
-- `contents`: Conversation history
-- `tools`: Available tools
-- `tool_choice`: Force tool usage or not
-
-**Live Coding**: Build LlmRequest
-
----
-
-#### Step 2: Response Model (2 min)
-```python
-class LlmResponse(BaseModel):
-    """Response object from LLM calls."""
-    content: List[ContentItem] = Field(default_factory=list)
-    error_message: Optional[str] = None
-    usage_metadata: Dict[str, Any] = Field(default_factory=dict)
-```
-
-**Key Fields:**
-- `content`: Messages and tool calls
-- `error_message`: Error if any
-- `usage_metadata`: Token usage
-
-**Live Coding**: Build LlmResponse
-
----
-
-#### Step 3: build_messages() Function (5 min)
-
-**Purpose**: Convert our models to API format
-
-**Implementation:**
-```python
-import json
-from .models import Message, ToolCall, ToolResult
-
-def build_messages(request: LlmRequest) -> List[dict]:
-    """Convert LlmRequest to API message format."""
-    messages = []
-    
-    # Add system instructions
-    for instruction in request.instructions:
-        messages.append({"role": "system", "content": instruction})
-    
-    # Convert content items
-    for item in request.contents:
-        if isinstance(item, Message):
-            messages.append({"role": item.role, "content": item.content})
-            
-        elif isinstance(item, ToolCall):
-            tool_call_dict = {
-                "id": item.tool_call_id,
-                "type": "function",
-                "function": {
-                    "name": item.name,
-                    "arguments": json.dumps(item.arguments)
-                }
-            }
-            # Append to previous assistant message if exists
-            if messages and messages[-1]["role"] == "assistant":
-                messages[-1].setdefault("tool_calls", []).append(tool_call_dict)
-            else:
-                messages.append({
-                    "role": "assistant",
-                    "content": None,
-                    "tool_calls": [tool_call_dict]
-                })
-                
-        elif isinstance(item, ToolResult):
-            messages.append({
-                "role": "tool",
-                "tool_call_id": item.tool_call_id,
-                "content": str(item.content[0]) if item.content else ""
-            })
-    
-    return messages
-```
-
-**Key Points:**
-- System messages first
-- Tool calls attach to assistant messages
-- Tool results use "tool" role
-- JSON stringify arguments
-
-**Live Coding**: Build build_messages()
-
----
-
-#### Step 4: LlmClient Class (5 min)
-```python
-from litellm import acompletion
-from typing import Dict, Any
-
-class LlmClient:
-    """Client for LLM API calls using LiteLLM."""
-    
-    def __init__(self, model: str, **config):
-        self.model = model
-        self.config = config
-    
-    async def generate(self, request: LlmRequest) -> LlmResponse:
-        """Generate a response from the LLM."""
-        try:
-            messages = self._build_messages(request)
-            tools = [t.tool_definition for t in request.tools] if request.tools else None
-           
-            response = await acompletion(
-                model=self.model,
-                messages=messages,
-                tools=tools,
-                **({"tool_choice": request.tool_choice} 
-                   if request.tool_choice else {}),
-                **self.config
-            )
-            
-            return self._parse_response(response)
-        except Exception as e:
-            return LlmResponse(error_message=str(e))
-    
-    def _build_messages(self, request: LlmRequest) -> List[dict]:
-        """Convert LlmRequest to API message format."""
-        return build_messages(request)
-```
-
-**Key Points:**
-- Wraps LiteLLM
-- Handles tools
-- Error handling
-- Configurable
-
-**Live Coding**: Build LlmClient
-
----
-
-#### Step 5: _parse_response() Method (5 min)
-```python
-def _parse_response(self, response) -> LlmResponse:
-    """Convert API response to LlmResponse."""
-    choice = response.choices[0]
-    content_items = []
-    
-    # Parse message content
-    if choice.message.content:
-        content_items.append(Message(
-            role="assistant",
-            content=choice.message.content
-        ))
-
-    # Parse tool calls
-    if choice.message.tool_calls:
-        for tc in choice.message.tool_calls:
-            content_items.append(ToolCall(
-                tool_call_id=tc.id,
-                name=tc.function.name,
-                arguments=json.loads(tc.function.arguments)
-            ))
-    
-    return LlmResponse(
-        content=content_items,
-        usage_metadata={
-            "input_tokens": response.usage.prompt_tokens,
-            "output_tokens": response.usage.completion_tokens,
-        }
-    )
-```
-
-**Key Points:**
-- Extract content and tool calls
-- Parse JSON arguments
-- Track token usage
-- Return our models
-
-**Live Coding**: Build _parse_response()
-
----
-
-### 5. Testing the Client (3 min)
-
-**Test Basic Call:**
-```python
-from agent_framework.llm import LlmClient, LlmRequest
-from agent_framework.models import Message
-
-client = LlmClient(model="gpt-4o-mini")
-
-request = LlmRequest(
-    instructions=["You are helpful."],
-    contents=[Message(role="user", content="Hello!")]
-)
-
-response = await client.generate(request)
-print(response.content[0].content)  # "Hello! How can I help?"
-```
-
-**Test with Tools:**
-```python
-from agent_framework.tools import FunctionTool
-
-@tool
-def calculator(expression: str) -> str:
-    """Evaluate a math expression."""
-    return str(eval(expression))
-
-request = LlmRequest(
-    instructions=["Use tools when needed."],
-    contents=[Message(role="user", content="What is 2+2?")],
-    tools=[calculator]
-)
-
-response = await client.generate(request)
-# Should contain ToolCall for calculator
-```
-
----
-
-### 6. Error Handling (2 min)
-
-**Built-in Error Handling:**
-```python
-# Invalid API key
-response = await client.generate(request)
-if response.error_message:
-    print(f"Error: {response.error_message}")
-```
-
-**Common Errors:**
-- Authentication errors
-- Rate limits
-- Invalid tool definitions
-- Network timeouts
-
----
-
-### 7. Demo: Complete Client (2 min)
-
-**Show:**
-- Basic message
-- Multi-turn conversation
-- Tool calls
-- Error handling
-
----
-
-### 8. Next Steps (1 min)
-
-**Preview Episode 5:**
-- Building the agent loop
-- Think-Act-Observe cycle
-- Execution context management
-
-**What We Built:**
-- Complete LLM client
-- Request/response models
-- Message conversion
-
----
-
-## Key Takeaways
-
-1. **Request/Response pattern** provides clean abstraction
-2. **build_messages()** converts our models to API format
-3. **Error handling** is built into the response
-4. **Tool support** is integrated
-5. **Provider agnostic** via LiteLLM
-
----
-
-## Common Mistakes
-
-**Mistake 1: Forgetting to JSON stringify arguments**
-```python
-# Wrong
-"arguments": item.arguments  # Dict, not string!
-
-# Right
-"arguments": json.dumps(item.arguments)  # JSON string
-```
-
-**Mistake 2: Not handling tool calls in response**
-```python
-# Wrong - misses tool calls
-if choice.message.content:
-    return choice.message.content
-
-# Right - check both
-if choice.message.content:
-    # Add message
-if choice.message.tool_calls:
-    # Add tool calls
-```
-
----
-
-## Exercises
-
-1. Add streaming support
-2. Implement retry logic
-3. Add response caching
-4. Support multiple response formats
-
----
-
-**Previous Episode**: [Episode 3: Core Data Models](./EPISODE_03_DATA_MODELS.md)  
-**Next Episode**: [Episode 5: The Basic Agent Loop](./EPISODE_05_AGENT_LOOP.md)
-

misc/tutorials/EPISODE_05_AGENT_LOOP.md

@@ -1,356 +0,0 @@
-# Episode 5: The Basic Agent Loop
-
-**Duration**: 35 minutes  
-**What to Build**: Basic `agent_framework/agent.py` (no tools yet)  
-**Target Audience**: Intermediate Python developers
-
----
-
-## Episode Structure
-
-### 1. Hook (2 min)
-**Show what we'll build:**
-- Agent that can have conversations
-- Multi-step reasoning
-- Execution tracking
-
-**Hook Statement**: "Today we'll build the core agent loop - the brain that orchestrates everything. This is where the magic happens."
-
----
-
-### 2. Problem (3 min)
-**Why do we need an agent loop?**
-
-**The Challenge:**
-- LLMs are stateless
-- Need to maintain conversation history
-- Need to track execution steps
-- Need to know when to stop
-
-**The Solution:**
-- Think-Act-Observe cycle
-- ExecutionContext for state
-- Event recording
-- Step-by-step execution
-
----
-
-### 3. Concept: Think-Act-Observe Cycle (5 min)
-
-**The Cycle:**
-1. **Think**: Call LLM with context
-2. **Act**: Execute tools if needed (next episode)
-3. **Observe**: Process results and continue
-
-**Why This Pattern?**
-- Mimics human reasoning
-- Allows multi-step problem solving
-- Clear separation of concerns
-- Easy to debug
-
----
-
-### 4. Live Coding: Building the Agent (25 min)
-
-#### Step 1: Agent.__init__ (3 min)
-```python
-from dataclasses import dataclass
-from typing import List, Optional
-from .llm import LlmClient
-from .models import ExecutionContext
-
-class Agent:
-    """Agent that can reason and use tools to solve tasks."""
-    
-    def __init__(
-        self,
-        model: LlmClient,
-        tools: List[BaseTool] = None,
-        instructions: str = "",
-        max_steps: int = 5,
-        name: str = "agent"
-    ):
-        self.model = model
-        self.instructions = instructions
-        self.max_steps = max_steps
-        self.name = name
-        self.tools = tools or []
-```
-
-**Key Parameters:**
-- `model`: LLM client
-- `tools`: Available tools (empty for now)
-- `instructions`: System prompt
-- `max_steps`: Safety limit
-- `name`: Agent identifier
-
-**Live Coding**: Build __init__
-
----
-
-#### Step 2: Agent.run() Method (5 min)
-```python
-from .models import Event, Message, AgentResult
-
-async def run(
-    self, 
-    user_input: str, 
-    context: ExecutionContext = None
-) -> AgentResult:
-    """Execute the agent."""
-    # Create or reuse context
-    if context is None:
-        context = ExecutionContext()
-    
-    # Add user input as the first event
-    user_event = Event(
-        execution_id=context.execution_id,
-        author="user",
-        content=[Message(role="user", content=user_input)]
-    )
-    context.add_event(user_event)
-    
-    # Execute steps until completion or max steps reached
-    while not context.final_result and context.current_step < self.max_steps:
-        await self.step(context)
-        # Check if the last event is a final response
-        last_event = context.events[-1]
-        if self._is_final_response(last_event):
-            context.final_result = self._extract_final_result(last_event)
-    
-    return AgentResult(output=context.final_result, context=context)
-```
-
-**Key Points:**
-- Creates context if needed
-- Records user input
-- Loops until done
-- Checks for completion
-
-**Live Coding**: Build run()
-
----
-
-#### Step 3: Agent.step() Method (5 min)
-```python
-async def step(self, context: ExecutionContext):
-    """Execute one step of the agent loop."""
-    
-    # Prepare LLM request
-    llm_request = self._prepare_llm_request(context)
-   
-    # Get LLM's decision (Think)
-    llm_response = await self.think(llm_request)
-    
-    # Record LLM response as an event
-    response_event = Event(
-        execution_id=context.execution_id,
-        author=self.name,
-        content=llm_response.content,
-    )
-    context.add_event(response_event)
-    
-    # Execute tools if needed (Act) - next episode!
-    # For now, just record the response
-    
-    context.increment_step()
-```
-
-**Key Points:**
-- Prepares request
-- Calls LLM
-- Records response
-- Increments step
-
-**Live Coding**: Build step()
-
----
-
-#### Step 4: _prepare_llm_request() Method (4 min)
-```python
-from .llm import LlmRequest
-
-def _prepare_llm_request(self, context: ExecutionContext) -> LlmRequest:
-    """Convert execution context to LLM request."""
-    # Flatten events into content items
-    flat_contents = []
-    for event in context.events:
-        flat_contents.extend(event.content)
-    
-    return LlmRequest(
-        instructions=[self.instructions] if self.instructions else [],
-        contents=flat_contents,
-        tools=self.tools,  # Empty for now
-        tool_choice=None  # No tools yet
-    )
-```
-
-**Key Points:**
-- Flattens events
-- Includes instructions
-- Adds conversation history
-- No tools yet
-
-**Live Coding**: Build _prepare_llm_request()
-
----
-
-#### Step 5: think() Method (2 min)
-```python
-async def think(self, llm_request: LlmRequest) -> LlmResponse:
-    """Get LLM's response/decision."""
-    return await self.model.generate(llm_request)
-```
-
-**Simple wrapper** around LLM client.
-
-**Live Coding**: Build think()
-
----
-
-#### Step 6: Completion Detection (3 min)
-```python
-def _is_final_response(self, event: Event) -> bool:
-    """Check if this event contains a final response."""
-    # For now, if it's a message and no tool calls, it's final
-    has_tool_calls = any(isinstance(c, ToolCall) for c in event.content)
-    has_tool_results = any(isinstance(c, ToolResult) for c in event.content)
-    return not has_tool_calls and not has_tool_results
-
-def _extract_final_result(self, event: Event) -> str:
-    """Extract final result from event."""
-    for item in event.content:
-        if isinstance(item, Message) and item.role == "assistant":
-            return item.content
-    return None
-```
-
-**Key Points:**
-- Checks for tool activity
-- Extracts message content
-- Simple for now
-
-**Live Coding**: Build completion detection
-
----
-
-#### Step 7: AgentResult (3 min)
-```python
-@dataclass
-class AgentResult:
-    """Result of an agent execution."""
-    output: str | BaseModel
-    context: ExecutionContext
-    status: Literal["complete", "pending", "error"] = "complete"
-```
-
-**Simple result container.**
-
-**Live Coding**: Build AgentResult
-
----
-
-### 5. Testing the Agent (3 min)
-
-**Basic Conversation:**
-```python
-from agent_framework import Agent, LlmClient
-
-agent = Agent(
-    model=LlmClient(model="gpt-4o-mini"),
-    instructions="You are a helpful assistant.",
-    max_steps=5
-)
-
-result = await agent.run("Hello! My name is Alice.")
-print(result.output)
-print(f"Steps: {result.context.current_step}")
-```
-
-**Multi-Turn:**
-```python
-# First turn
-result1 = await agent.run("My name is Alice")
-print(result1.output)
-
-# Second turn (new context - doesn't remember)
-result2 = await agent.run("What's my name?")
-print(result2.output)  # Doesn't know!
-```
-
-**Note**: Session persistence comes later!
-
----
-
-### 6. Demo: Working Agent (2 min)
-
-**Show:**
-- Basic conversation
-- Multi-step reasoning
-- Execution trace
-- Step counting
-
----
-
-### 7. Next Steps (1 min)
-
-**Preview Episode 6:**
-- Building the tool system
-- Creating tools
-- Tool definitions
-
-**What We Built:**
-- Basic agent loop
-- Conversation handling
-- Execution tracking
-
----
-
-## Key Takeaways
-
-1. **Think-Act-Observe** cycle is the core pattern
-2. **ExecutionContext** tracks all state
-3. **Events** record every step
-4. **Max steps** prevents infinite loops
-5. **Completion detection** knows when to stop
-
----
-
-## Common Mistakes
-
-**Mistake 1: Not incrementing step**
-```python
-# Wrong - infinite loop!
-while not context.final_result:
-    await self.step(context)
-    # Missing: context.increment_step()
-
-# Right
-await self.step(context)  # step() increments internally
-```
-
-**Mistake 2: Not checking max steps**
-```python
-# Wrong - can loop forever
-while not context.final_result:
-    await self.step(context)
-
-# Right
-while not context.final_result and context.current_step < self.max_steps:
-    await self.step(context)
-```
-
----
-
-## Exercises
-
-1. Add verbose logging
-2. Implement step-by-step trace display
-3. Add error handling for LLM failures
-4. Create a "thinking" indicator
-
----
-
-**Previous Episode**: [Episode 4: The LLM Client](./EPISODE_04_LLM_CLIENT.md)  
-**Next Episode**: [Episode 6: Building the Tool System](./EPISODE_06_TOOL_SYSTEM.md)
-

misc/tutorials/EPISODE_06_TOOL_SYSTEM.md

@@ -1,631 +0,0 @@
-# Episode 6: Building the Tool System
-
-**Duration**: 40 minutes  
-**What to Build**: `agent_framework/tools.py`  
-**Target Audience**: Intermediate Python developers
-
----
-
-## Episode Structure
-
-### 1. Hook (2 min)
-**Show what we'll build:**
-- Tool system that wraps functions
-- Automatic schema generation
-- @tool decorator
-- Tool confirmation for dangerous operations
-
-**Hook Statement**: "Today we'll build the system that lets LLMs use Python functions. This is what makes agents powerful - they can actually do things!"
-
----
-
-### 2. Problem (3 min)
-**Why do we need a tool system?**
-
-**The Challenge:**
-- LLMs can't execute code directly
-- Need to bridge Python functions to LLM
-- Need to describe functions to LLM
-- Need to handle execution safely
-- Some tools are dangerous (delete file, send email)
-
-**The Solution:**
-- BaseTool abstract interface
-- FunctionTool wrapper
-- Automatic schema generation
-- @tool decorator for ease
-- Confirmation workflow for safety
-
----
-
-### 3. Concept: Tool Architecture (5 min)
-
-**The Flow:**
-1. Define Python function
-2. Wrap as BaseTool
-3. Generate JSON schema
-4. Send to LLM
-5. LLM calls tool
-6. Check if confirmation required
-7. Execute function (or wait for approval)
-8. Return result
-
-**Key Components:**
-- BaseTool: Abstract interface
-- FunctionTool: Wraps functions
-- Schema generation: From type hints
-- Decorator: Syntactic sugar
-- Confirmation: Safety for dangerous tools
-
----
-
-### 4. Live Coding: Building the Tool System (30 min)
-
-#### Step 1: BaseTool Abstract Class (7 min)
-```python
-from abc import ABC, abstractmethod
-from typing import Dict, Any
-from .models import ExecutionContext
-
-class BaseTool(ABC):
-    """Abstract base class for all tools."""
-    
-    def __init__(
-        self, 
-        name: str = None, 
-        description: str = None, 
-        tool_definition: Dict[str, Any] = None,
-        # Confirmation support
-        requires_confirmation: bool = False,
-        confirmation_message_template: str = None
-    ):
-        self.name = name or self.__class__.__name__
-        self.description = description or self.__doc__ or ""
-        self._tool_definition = tool_definition
-        self.requires_confirmation = requires_confirmation
-        self.confirmation_message_template = confirmation_message_template or (
-            "The agent wants to execute '{name}' with arguments: {arguments}. "
-            "Do you approve?"
-        )
-    
-    @property
-    def tool_definition(self) -> Dict[str, Any] | None:
-        return self._tool_definition
-    
-    @abstractmethod
-    async def execute(self, context: ExecutionContext, **kwargs) -> Any:
-        pass
-    
-    async def __call__(self, context: ExecutionContext, **kwargs) -> Any:
-        return await self.execute(context, **kwargs)
-
-    def get_confirmation_message(self, arguments: dict[str, Any]) -> str:
-        """Generate a confirmation message for this tool call."""
-        return self.confirmation_message_template.format(
-            name=self.name,
-            arguments=arguments
-        )
-```
-
-**Key Points:**
-- Abstract base class
-- Name and description
-- Tool definition (JSON schema)
-- Execute method
-- **NEW: `requires_confirmation`** - marks dangerous tools
-- **NEW: `confirmation_message_template`** - customizable message
-- **NEW: `get_confirmation_message()`** - generates message for user
-
-**Why Confirmation?**
-- Some tools are dangerous (delete files, send emails)
-- Users should approve before execution
-- Allows argument modification
-
-**Live Coding**: Build BaseTool with confirmation
-
----
-
-#### Step 2: Schema Generation Utilities (5 min)
-```python
-import inspect
-from .utils import function_to_input_schema, format_tool_definition
-
-def function_to_input_schema(func) -> dict:
-    """Convert function signature to JSON Schema."""
-    type_map = {
-        str: "string",
-        int: "integer",
-        float: "number",
-        bool: "boolean",
-        list: "array",
-        dict: "object",
-    }
-    
-    signature = inspect.signature(func)
-    parameters = {}
-    
-    for param in signature.parameters.values():
-        param_type = type_map.get(param.annotation, "string")
-        parameters[param.name] = {"type": param_type}
-    
-    required = [
-        param.name
-        for param in signature.parameters.values()
-        if param.default == inspect._empty
-    ]
-    
-    return {
-        "type": "object",
-        "properties": parameters,
-        "required": required,
-    }
-
-def format_tool_definition(name: str, description: str, parameters: dict) -> dict:
-    """Format tool definition in OpenAI function calling format."""
-    return {
-        "type": "function",
-        "function": {
-            "name": name,
-            "description": description,
-            "parameters": parameters,
-        },
-    }
-```
-
-**Key Points:**
-- Inspects function signature
-- Maps Python types to JSON Schema
-- Handles required parameters
-- Formats for OpenAI
-
-**Live Coding**: Build schema generation
-
----
-
-#### Step 3: FunctionTool Class (8 min)
-```python
-class FunctionTool(BaseTool):
-    """Wraps a Python function as a BaseTool."""
-    
-    def __init__(
-        self, 
-        func: Callable, 
-        name: str = None, 
-        description: str = None,
-        tool_definition: Dict[str, Any] = None,
-        requires_confirmation: bool = False,
-        confirmation_message_template: str = None
-    ):
-        self.func = func
-        self.needs_context = 'context' in inspect.signature(func).parameters
-        
-        self.name = name or func.__name__
-        self.description = description or (func.__doc__ or "").strip()
-        tool_definition = tool_definition or self._generate_definition()
-        
-        super().__init__(
-            name=self.name, 
-            description=self.description, 
-            tool_definition=tool_definition,
-            requires_confirmation=requires_confirmation,
-            confirmation_message_template=confirmation_message_template
-        )
-    
-    async def execute(self, context: ExecutionContext = None, **kwargs) -> Any:
-        """Execute the wrapped function.
-        
-        Context is only required if the wrapped function has a 'context' parameter.
-        """
-        if self.needs_context:
-            if context is None:
-                raise ValueError(
-                    f"Tool '{self.name}' requires a context parameter. "
-                    f"Please provide an ExecutionContext instance."
-                )
-            result = self.func(context=context, **kwargs)
-        else:
-            result = self.func(**kwargs)
-        
-        # Handle both sync and async functions
-        if inspect.iscoroutine(result):
-            return await result
-        return result
-    
-    def _generate_definition(self) -> Dict[str, Any]:
-        """Generate tool definition from function signature."""
-        parameters = function_to_input_schema(self.func)
-        return format_tool_definition(self.name, self.description, parameters)
-```
-
-**Key Points:**
-- Wraps any function
-- Detects context parameter
-- Handles sync/async
-- Auto-generates schema
-- **Passes confirmation params to parent**
-
-**Live Coding**: Build FunctionTool
-
----
-
-#### Step 4: @tool Decorator with Confirmation (6 min)
-```python
-def tool(
-    func: Callable = None,
-    *,
-    name: str = None,
-    description: str = None,
-    tool_definition: Dict[str, Any] = None,
-    requires_confirmation: bool = False,
-    confirmation_message: str = None
-):
-    """Decorator to convert a function into a FunctionTool.
-    
-    Usage:
-        @tool
-        def my_function(x: int) -> int:
-            return x * 2
-        
-        # Or with parameters:
-        @tool(name="custom_name", description="Custom description")
-        def my_function(x: int) -> int:
-            return x * 2
-        
-        # With confirmation:
-        @tool(requires_confirmation=True, confirmation_message="Delete file?")
-        def delete_file(filename: str) -> str:
-            ...
-    """
-    def decorator(f: Callable) -> FunctionTool:
-        return FunctionTool(
-            func=f,
-            name=name,
-            description=description,
-            tool_definition=tool_definition,
-            requires_confirmation=requires_confirmation,
-            confirmation_message_template=confirmation_message
-        )
-    
-    if func is not None:
-        return decorator(func)
-    return decorator
-```
-
-**Usage Examples:**
-
-**Simple Tool (no confirmation):**
-```python
-@tool
-def calculator(expression: str) -> str:
-    """Evaluate a math expression."""
-    return str(eval(expression))
-```
-
-**Dangerous Tool (requires confirmation):**
-```python
-@tool(
-    requires_confirmation=True,
-    confirmation_message="Delete file '{arguments[filename]}'? This cannot be undone."
-)
-def delete_file(filename: str) -> str:
-    """Delete a file from the filesystem."""
-    import os
-    os.remove(filename)
-    return f"Deleted {filename}"
-```
-
-**Custom Confirmation Message:**
-```python
-@tool(
-    requires_confirmation=True,
-    confirmation_message="Send email to {arguments[recipient]}? Subject: {arguments[subject]}"
-)
-def send_email(recipient: str, subject: str, body: str) -> str:
-    """Send an email."""
-    # ... send email ...
-    return "Email sent"
-```
-
-**Live Coding**: Build @tool decorator with confirmation
-
----
-
-#### Step 5: Testing Tools (4 min)
-
-**Simple Tool:**
-```python
-@tool
-def add(a: int, b: int) -> int:
-    """Add two numbers."""
-    return a + b
-
-print(add.name)  # "add"
-print(add.requires_confirmation)  # False
-result = await add.execute(context=None, a=2, b=3)
-print(result)  # 5
-```
-
-**Tool with Context:**
-```python
-@tool
-def get_step_count(context: ExecutionContext) -> int:
-    """Get current step count."""
-    return context.current_step
-
-print(get_step_count.needs_context)  # True
-```
-
-**Tool with Confirmation:**
-```python
-@tool(
-    requires_confirmation=True,
-    confirmation_message="Delete '{arguments[filename]}'?"
-)
-def delete_file(filename: str) -> str:
-    """Delete a file."""
-    return f"Deleted {filename}"
-
-print(delete_file.requires_confirmation)  # True
-
-# Generate confirmation message
-message = delete_file.get_confirmation_message({"filename": "secret.txt"})
-print(message)  # "Delete 'secret.txt'?"
-```
-
-**Test Schema:**
-```python
-print(add.tool_definition)
-# {
-#     "type": "function",
-#     "function": {
-#         "name": "add",
-#         "description": "Add two numbers.",
-#         "parameters": {
-#             "type": "object",
-#             "properties": {
-#                 "a": {"type": "integer"},
-#                 "b": {"type": "integer"}
-#             },
-#             "required": ["a", "b"]
-#         }
-#     }
-# }
-```
-
----
-
-### 5. Demo: Creating Tools (2 min)
-
-**Show:**
-- Simple calculator tool
-- Tool with context
-- Tool with confirmation
-- Schema generation
-- Confirmation message generation
-
----
-
-### 6. Next Steps (1 min)
-
-**Preview Episode 7:**
-- Integrating tools into agent
-- Tool execution in agent loop
-- **Handling pending tool calls**
-- **Processing confirmations**
-
-**What We Built:**
-- Complete tool system
-- Schema generation
-- @tool decorator
-- Confirmation workflow
-
----
-
-## Key Takeaways
-
-1. **BaseTool** provides abstract interface
-2. **FunctionTool** wraps any function
-3. **Schema generation** from type hints
-4. **@tool decorator** for ease of use
-5. **Context-aware** tools supported
-6. **`requires_confirmation`** marks dangerous tools
-7. **`get_confirmation_message()`** generates user-facing message
-
----
-
-## Common Mistakes
-
-**Mistake 1: Forgetting docstring**
-```python
-# Wrong - no description for LLM
-@tool
-def add(a: int, b: int) -> int:
-    return a + b
-
-# Right - LLM knows what it does
-@tool
-def add(a: int, b: int) -> int:
-    """Add two numbers together."""
-    return a + b
-```
-
-**Mistake 2: Not handling async functions**
-```python
-# Wrong - doesn't await
-result = self.func(**kwargs)
-return result
-
-# Right - checks if coroutine
-result = self.func(**kwargs)
-if inspect.iscoroutine(result):
-    return await result
-return result
-```
-
-**Mistake 3: Forgetting confirmation for dangerous tools**
-```python
-# Wrong - dangerous tool without confirmation
-@tool
-def delete_file(filename: str) -> str:
-    os.remove(filename)
-    return "Deleted"
-
-# Right - requires user approval
-@tool(requires_confirmation=True)
-def delete_file(filename: str) -> str:
-    os.remove(filename)
-    return "Deleted"
-```
-
-**Mistake 4: Bad confirmation message**
-```python
-# Wrong - generic message
-@tool(
-    requires_confirmation=True,
-    confirmation_message="Are you sure?"
-)
-def delete_file(filename: str) -> str: ...
-
-# Right - specific and informative
-@tool(
-    requires_confirmation=True,
-    confirmation_message="Delete file '{arguments[filename]}'? This cannot be undone."
-)
-def delete_file(filename: str) -> str: ...
-```
-
----
-
-## Exercises
-
-1. **Add `requires_confirmation` to a tool**: Create a `send_email` tool that requires confirmation
-2. **Custom confirmation message**: Create a message template that includes all arguments
-3. **Create tool registry**: Build a `ToolRegistry` class that tracks all tools and their confirmation status
-4. **Add validation**: Add a method to validate arguments before execution
-
----
-
-## Complete tools.py File
-
-```python
-"""Tool system for the agent framework."""
-
-from abc import ABC, abstractmethod
-from typing import Dict, Any, Callable
-import inspect
-from .models import ExecutionContext
-from .utils import function_to_input_schema, format_tool_definition
-
-
-class BaseTool(ABC):
-    """Abstract base class for all tools."""
-    
-    def __init__(
-        self, 
-        name: str = None, 
-        description: str = None, 
-        tool_definition: Dict[str, Any] = None,
-        requires_confirmation: bool = False,
-        confirmation_message_template: str = None
-    ):
-        self.name = name or self.__class__.__name__
-        self.description = description or self.__doc__ or ""
-        self._tool_definition = tool_definition
-        self.requires_confirmation = requires_confirmation
-        self.confirmation_message_template = confirmation_message_template or (
-            "The agent wants to execute '{name}' with arguments: {arguments}. "
-            "Do you approve?"
-        )
-    
-    @property
-    def tool_definition(self) -> Dict[str, Any] | None:
-        return self._tool_definition
-    
-    @abstractmethod
-    async def execute(self, context: ExecutionContext, **kwargs) -> Any:
-        pass
-    
-    async def __call__(self, context: ExecutionContext, **kwargs) -> Any:
-        return await self.execute(context, **kwargs)
-
-    def get_confirmation_message(self, arguments: dict[str, Any]) -> str:
-        """Generate a confirmation message for this tool call."""
-        return self.confirmation_message_template.format(
-            name=self.name,
-            arguments=arguments
-        )
-
-
-class FunctionTool(BaseTool):
-    """Wraps a Python function as a BaseTool."""
-    
-    def __init__(
-        self, 
-        func: Callable, 
-        name: str = None, 
-        description: str = None,
-        tool_definition: Dict[str, Any] = None,
-        requires_confirmation: bool = False,
-        confirmation_message_template: str = None
-    ):
-        self.func = func
-        self.needs_context = 'context' in inspect.signature(func).parameters
-        
-        self.name = name or func.__name__
-        self.description = description or (func.__doc__ or "").strip()
-        tool_definition = tool_definition or self._generate_definition()
-        
-        super().__init__(
-            name=self.name, 
-            description=self.description, 
-            tool_definition=tool_definition,
-            requires_confirmation=requires_confirmation,
-            confirmation_message_template=confirmation_message_template
-        )
-    
-    async def execute(self, context: ExecutionContext = None, **kwargs) -> Any:
-        if self.needs_context:
-            if context is None:
-                raise ValueError(f"Tool '{self.name}' requires a context parameter.")
-            result = self.func(context=context, **kwargs)
-        else:
-            result = self.func(**kwargs)
-        
-        if inspect.iscoroutine(result):
-            return await result
-        return result
-    
-    def _generate_definition(self) -> Dict[str, Any]:
-        parameters = function_to_input_schema(self.func)
-        return format_tool_definition(self.name, self.description, parameters)
-
-
-def tool(
-    func: Callable = None,
-    *,
-    name: str = None,
-    description: str = None,
-    tool_definition: Dict[str, Any] = None,
-    requires_confirmation: bool = False,
-    confirmation_message: str = None
-):
-    """Decorator to convert a function into a FunctionTool."""
-    def decorator(f: Callable) -> FunctionTool:
-        return FunctionTool(
-            func=f,
-            name=name,
-            description=description,
-            tool_definition=tool_definition,
-            requires_confirmation=requires_confirmation,
-            confirmation_message_template=confirmation_message
-        )
-    
-    if func is not None:
-        return decorator(func)
-    return decorator
-```
-
----
-
-**Previous Episode**: [Episode 5: The Basic Agent Loop](./EPISODE_05_AGENT_LOOP.md)  
-**Next Episode**: [Episode 7: Tool Execution & Complete Agent](./EPISODE_07_TOOL_EXECUTION.md)

misc/tutorials/EPISODE_07_TOOL_EXECUTION.md

@@ -1,594 +0,0 @@
-# Episode 7: Tool Execution & Complete Agent
-
-**Duration**: 45 minutes  
-**What to Build**: Complete `agent_framework/agent.py` with tool execution and confirmation  
-**Target Audience**: Intermediate Python developers
-
----
-
-## Episode Structure
-
-### 1. Hook (2 min)
-**Show what we'll build:**
-- Complete agent with tool execution
-- Calculator and web search working
-- Multi-step problem solving
-- Tool confirmation workflow
-
-**Hook Statement**: "Today we'll complete the agent by adding tool execution and safety confirmations. This is where everything comes together - the agent can now actually do things, safely!"
-
----
-
-### 2. Problem (3 min)
-**Why do we need tool execution?**
-
-**The Challenge:**
-- LLM decides to use tools
-- Need to execute them
-- Handle results
-- Continue reasoning
-- Some tools are dangerous!
-
-**The Solution:**
-- Act() method
-- Tool dispatch
-- Result handling
-- Error management
-- Confirmation workflow for safety
-
----
-
-### 3. Concept: Tool Execution Flow (5 min)
-
-**The Flow:**
-1. LLM returns tool calls
-2. Agent finds tools by name
-3. Check if confirmation required
-4. If yes: pause and return pending calls
-5. User submits confirmation
-6. Execute approved tools
-7. Record results
-8. Continue reasoning
-
-**Key Steps:**
-- Parse tool calls from response
-- Map to tool instances
-- Check `requires_confirmation`
-- Handle pending state
-- Process confirmations
-- Create ToolResult objects
-
----
-
-### 4. Live Coding: Completing the Agent (35 min)
-
-#### Step 1: Update AgentResult (3 min)
-```python
-from dataclasses import dataclass
-from typing import Literal
-from pydantic import Field
-
-@dataclass
-class AgentResult:
-    """Result of an agent execution."""
-    output: str | BaseModel
-    context: ExecutionContext
-    status: Literal["complete", "pending", "error"] = "complete"
-    pending_tool_calls: list[PendingToolCall] = Field(default_factory=list)
-```
-
-**Key Points:**
-- `status`: Indicates if execution is complete, pending, or errored
-- `pending_tool_calls`: List of tools awaiting user confirmation
-- Enables pausing and resuming agent execution
-
-**Live Coding**: Update AgentResult
-
----
-
-#### Step 2: Update step() to Handle Tools (5 min)
-```python
-async def step(self, context: ExecutionContext):
-    """Execute one step of the agent loop."""
-    
-    # Process pending confirmations if both are present
-    if ("pending_tool_calls" in context.state and 
-        "tool_confirmations" in context.state):
-        confirmation_results = await self._process_confirmations(context)
-        
-        # Add results as an event so they appear in contents
-        if confirmation_results:
-            confirmation_event = Event(
-                execution_id=context.execution_id,
-                author=self.name,
-                content=confirmation_results,
-            )
-            context.add_event(confirmation_event)
-        
-        # Clear processed state
-        del context.state["pending_tool_calls"]
-        del context.state["tool_confirmations"]
-    
-    llm_request = self._prepare_llm_request(context)
-    llm_response = await self.think(llm_request)
-    
-    # Record LLM response
-    response_event = Event(
-        execution_id=context.execution_id,
-        author=self.name,
-        content=llm_response.content,
-    )
-    context.add_event(response_event)
-    
-    # Execute tools if the LLM requested any
-    tool_calls = [c for c in llm_response.content if isinstance(c, ToolCall)]
-    if tool_calls:
-        tool_results = await self.act(context, tool_calls)
-        tool_event = Event(
-            execution_id=context.execution_id,
-            author=self.name,
-            content=tool_results,
-        )
-        context.add_event(tool_event)
-    
-    context.increment_step()
-```
-
-**Key Changes:**
-- Check for pending confirmations at start
-- Process confirmations before LLM call
-- Clear processed state after handling
-
-**Live Coding**: Update step()
-
----
-
-#### Step 3: act() Method with Confirmation (10 min)
-```python
-from .models import ToolResult, PendingToolCall
-
-async def act(
-    self, 
-    context: ExecutionContext, 
-    tool_calls: List[ToolCall]
-) -> List[ToolResult]:
-    """Execute tool calls and return results."""
-    tools_dict = {tool.name: tool for tool in self.tools}
-    results = []
-    pending_calls = []  # Track tools needing confirmation
-
-    for tool_call in tool_calls:
-        if tool_call.name not in tools_dict:
-            raise ValueError(f"Tool '{tool_call.name}' not found")
-        
-        tool = tools_dict[tool_call.name]
-        
-        # Check if confirmation is required
-        if tool.requires_confirmation:
-            pending = PendingToolCall(
-                tool_call=tool_call,
-                confirmation_message=tool.get_confirmation_message(
-                    tool_call.arguments
-                )
-            )
-            pending_calls.append(pending)
-            continue  # Skip execution, wait for confirmation
-        
-        # Execute tool if no confirmation needed
-        try:
-            tool_response = await tool(context, **tool_call.arguments)
-            status = "success"
-        except Exception as e:
-            tool_response = str(e)
-            status = "error"
-        
-        tool_result = ToolResult(
-            tool_call_id=tool_call.tool_call_id,
-            name=tool_call.name,
-            status=status,
-            content=[tool_response],
-        )
-        results.append(tool_result)
-    
-    # Store pending calls in state for later processing
-    if pending_calls:
-        context.state["pending_tool_calls"] = [
-            p.model_dump() for p in pending_calls
-        ]
-    
-    return results
-```
-
-**Key Points:**
-- Check `tool.requires_confirmation`
-- Create PendingToolCall with message
-- Store in `context.state` for persistence
-- Skip execution for pending tools
-
-**Live Coding**: Build act() with confirmation
-
----
-
-#### Step 4: Process Confirmations (10 min)
-```python
-async def _process_confirmations(
-    self,
-    context: ExecutionContext
-) -> List[ToolResult]:
-    """Process user confirmations and execute approved tools."""
-    tools_dict = {tool.name: tool for tool in self.tools}
-    results = []
-
-    # Restore pending tool calls from state
-    pending_map = {
-        p["tool_call"]["tool_call_id"]: PendingToolCall.model_validate(p)
-        for p in context.state["pending_tool_calls"]
-    }
-
-    # Build confirmation lookup by tool_call_id
-    confirmation_map = {
-        c["tool_call_id"]: ToolConfirmation.model_validate(c)
-        for c in context.state["tool_confirmations"]
-    }
-
-    # Process ALL pending tool calls
-    for tool_call_id, pending in pending_map.items():
-        tool = tools_dict.get(pending.tool_call.name)
-        confirmation = confirmation_map.get(tool_call_id)
-
-        if confirmation and confirmation.approved:
-            # Merge original arguments with modifications
-            arguments = {
-                **pending.tool_call.arguments,
-                **(confirmation.modified_arguments or {})
-            }
-
-            # Execute the approved tool
-            try:
-                output = await tool(context, **arguments)
-                results.append(ToolResult(
-                    tool_call_id=tool_call_id,
-                    name=pending.tool_call.name,
-                    status="success",
-                    content=[output],
-                ))
-            except Exception as e:
-                results.append(ToolResult(
-                    tool_call_id=tool_call_id,
-                    name=pending.tool_call.name,
-                    status="error",
-                    content=[str(e)],
-                ))
-        else:
-            # Rejected: either explicitly or not in confirmation list
-            if confirmation:
-                reason = confirmation.reason or "Tool execution was rejected by user."
-            else:
-                reason = "Tool execution was not approved."
-
-            results.append(ToolResult(
-                tool_call_id=tool_call_id,
-                name=pending.tool_call.name,
-                status="error",
-                content=[reason],
-            ))
-
-    return results
-```
-
-**Key Points:**
-- Deserialize pending calls from state
-- Match confirmations by `tool_call_id`
-- Execute approved tools with merged arguments
-- Return error result for rejected tools
-- LLM sees rejection reason and can adapt
-
-**Live Coding**: Build _process_confirmations()
-
----
-
-#### Step 5: Update run() for Pending State (5 min)
-```python
-async def run(
-    self, 
-    user_input: str, 
-    context: ExecutionContext = None,
-    tool_confirmations: Optional[List[ToolConfirmation]] = None
-) -> AgentResult:
-    """Execute the agent with optional confirmation support."""
-    
-    # Store confirmations in state if provided
-    if tool_confirmations:
-        if context is None:
-            context = ExecutionContext()
-        context.state["tool_confirmations"] = [
-            c.model_dump() for c in tool_confirmations
-        ]
-    
-    # Create or reuse context
-    if context is None:
-        context = ExecutionContext()
-    
-    # Add user input as the first event
-    user_event = Event(
-        execution_id=context.execution_id,
-        author="user",
-        content=[Message(role="user", content=user_input)]
-    )
-    context.add_event(user_event)
-    
-    # Execute steps until completion or max steps reached
-    while not context.final_result and context.current_step < self.max_steps:
-        await self.step(context)
-        
-        # Check for pending confirmations after each step
-        if context.state.get("pending_tool_calls"):
-            pending_calls = [
-                PendingToolCall.model_validate(p)
-                for p in context.state["pending_tool_calls"]
-            ]
-            return AgentResult(
-                status="pending",
-                context=context,
-                pending_tool_calls=pending_calls,
-            )
-        
-        # Check if the last event is a final response
-        last_event = context.events[-1]
-        if self._is_final_response(last_event):
-            context.final_result = self._extract_final_result(last_event)
-    
-    return AgentResult(output=context.final_result, context=context)
-```
-
-**Key Points:**
-- Accept `tool_confirmations` parameter
-- Store in context.state for processing
-- Return "pending" status when confirmations needed
-- Resume execution when confirmations provided
-
-**Live Coding**: Update run()
-
----
-
-#### Step 6: Testing Confirmation Workflow (2 min)
-
-**Create Dangerous Tool:**
-```python
-from agent_framework import tool
-
-@tool(
-    requires_confirmation=True,
-    confirmation_message="Delete file '{arguments[filename]}'? This cannot be undone."
-)
-def delete_file(filename: str) -> str:
-    """Delete a file from the filesystem."""
-    import os
-    os.remove(filename)
-    return f"Deleted {filename}"
-```
-
-**Test Workflow:**
-```python
-from agent_framework import Agent, LlmClient, ToolConfirmation
-
-agent = Agent(
-    model=LlmClient(model="gpt-4o-mini"),
-    tools=[delete_file],
-    instructions="Help manage files."
-)
-
-# First call - gets pending
-result = await agent.run("Delete the file named 'test.txt'")
-print(result.status)  # "pending"
-print(result.pending_tool_calls[0].confirmation_message)
-# "Delete file 'test.txt'? This cannot be undone."
-
-# User approves
-confirmation = ToolConfirmation(
-    tool_call_id=result.pending_tool_calls[0].tool_call.tool_call_id,
-    approved=True
-)
-
-# Resume with confirmation
-result = await agent.run(
-    "",  # Empty because we're resuming
-    context=result.context,
-    tool_confirmations=[confirmation]
-)
-print(result.status)  # "complete"
-print(result.output)  # Agent's response about deletion
-```
-
-**Test Rejection:**
-```python
-# User rejects with reason
-confirmation = ToolConfirmation(
-    tool_call_id=result.pending_tool_calls[0].tool_call.tool_call_id,
-    approved=False,
-    reason="I don't want to delete that file"
-)
-
-result = await agent.run("", context=result.context, tool_confirmations=[confirmation])
-# Agent sees the rejection reason and responds appropriately
-```
-
----
-
-### 5. Demo: Complete Agent (3 min)
-
-**Show:**
-- Calculator tool working (no confirmation)
-- Delete file tool pausing for confirmation
-- User approving/rejecting
-- Agent adapting to rejection
-- Multi-step reasoning with confirmations
-
----
-
-### 6. Error Handling (2 min)
-
-**Tool Not Found:**
-```python
-if tool_call.name not in tools_dict:
-    raise ValueError(f"Tool '{tool_call.name}' not found")
-```
-
-**Tool Execution Error:**
-```python
-try:
-    tool_response = await tool(context, **tool_call.arguments)
-    status = "success"
-except Exception as e:
-    tool_response = str(e)
-    status = "error"
-```
-
-**Confirmation Not Provided:**
-```python
-if confirmation:
-    reason = confirmation.reason or "Tool execution was rejected by user."
-else:
-    reason = "Tool execution was not approved."
-```
-
-**Best Practices:**
-- Always handle errors gracefully
-- Return error in ToolResult
-- Let agent continue reasoning
-- Provide clear rejection reasons
-
----
-
-### 7. Next Steps (1 min)
-
-**Preview Episode 8:**
-- MCP integration
-- External tool servers
-- Tool discovery
-
-**What We Built:**
-- Complete agent with tools
-- Tool execution
-- Confirmation workflow
-- Error handling
-
----
-
-## Key Takeaways
-
-1. **act()** executes tools from LLM decisions
-2. **Tool dispatch** maps names to instances
-3. **requires_confirmation** pauses for user approval
-4. **PendingToolCall** stores awaiting tools
-5. **ToolConfirmation** carries user's decision
-6. **_process_confirmations()** handles approved/rejected tools
-7. **AgentResult.status** indicates execution state
-
----
-
-## Common Mistakes
-
-**Mistake 1: Not handling tool errors**
-```python
-# Wrong - crashes on error
-tool_response = await tool(context, **tool_call.arguments)
-
-# Right - handles gracefully
-try:
-    tool_response = await tool(context, **tool_call.arguments)
-    status = "success"
-except Exception as e:
-    tool_response = str(e)
-    status = "error"
-```
-
-**Mistake 2: Forgetting to store pending calls**
-```python
-# Wrong - pending calls lost
-if tool.requires_confirmation:
-    pending_calls.append(...)
-# Missing: storing in context.state
-
-# Right - persists for later
-if pending_calls:
-    context.state["pending_tool_calls"] = [p.model_dump() for p in pending_calls]
-```
-
-**Mistake 3: Not clearing processed state**
-```python
-# Wrong - processes same confirmations repeatedly
-confirmation_results = await self._process_confirmations(context)
-
-# Right - clears after processing
-del context.state["pending_tool_calls"]
-del context.state["tool_confirmations"]
-```
-
-**Mistake 4: Ignoring modified arguments**
-```python
-# Wrong - ignores user modifications
-output = await tool(context, **pending.tool_call.arguments)
-
-# Right - merges modifications
-arguments = {
-    **pending.tool_call.arguments,
-    **(confirmation.modified_arguments or {})
-}
-output = await tool(context, **arguments)
-```
-
----
-
-## Exercises
-
-1. **Add Tool Timeout**: Implement a timeout for tool execution
-2. **Implement Auto-Approve**: Add a flag to auto-approve tools for testing
-3. **Add Confirmation Expiry**: Make pending confirmations expire after a timeout
-4. **Create Approval Logger**: Log all confirmation decisions for audit
-
----
-
-## Complete Confirmation Flow
-
-```
-User: "Delete test.txt"
-    |
-    v
-Agent.run() -> Agent.step() -> Agent.act()
-    |
-    v
-act() sees requires_confirmation=True
-    |
-    v
-Creates PendingToolCall, stores in context.state
-    |
-    v
-Returns to run(), detects pending_tool_calls
-    |
-    v
-Returns AgentResult(status="pending", pending_tool_calls=[...])
-    |
-    v
-User sees confirmation message, submits ToolConfirmation
-    |
-    v
-Agent.run(context=..., tool_confirmations=[...])
-    |
-    v
-step() calls _process_confirmations()
-    |
-    v
-Executes approved tools, returns ToolResults
-    |
-    v
-Agent continues reasoning with results
-    |
-    v
-Returns AgentResult(status="complete", output="File deleted")
-```
-
----
-
-**Previous Episode**: [Episode 6: Building the Tool System](./EPISODE_06_TOOL_SYSTEM.md)  
-**Next Episode**: [Episode 8: MCP Integration](./EPISODE_08_MCP.md)

misc/tutorials/EPISODE_08_MCP.md

@@ -1,304 +0,0 @@
-# Episode 8: MCP Integration
-
-**Duration**: 30 minutes  
-**What to Build**: `agent_framework/mcp.py`  
-**Target Audience**: Intermediate Python developers
-
----
-
-## Episode Structure
-
-### 1. Hook (2 min)
-**Show what we'll build:**
-- Loading tools from MCP servers
-- Tavily search integration
-- External tool discovery
-
-**Hook Statement**: "Today we'll integrate with MCP - a protocol that lets us discover and use tools from external servers. This opens up a whole ecosystem of tools!"
-
----
-
-### 2. Problem (3 min)
-**Why do we need MCP?**
-
-**The Challenge:**
-- Tools live on separate servers
-- Need standard protocol
-- Want tool discovery
-- Don't want to hardcode tools
-
-**The Solution:**
-- Model Context Protocol (MCP)
-- Stdio communication
-- Tool discovery
-- Automatic wrapping
-
----
-
-### 3. Concept: What is MCP? (5 min)
-
-**MCP (Model Context Protocol):**
-- Standard protocol for tool servers
-- JSON-RPC over stdio
-- Tool discovery
-- Tool execution
-
-**Benefits:**
-- Decouples tools from agents
-- Standard interface
-- Easy integration
-- Tool marketplace potential
-
-**Flow:**
-1. Connect to MCP server
-2. Discover available tools
-3. Wrap as FunctionTool
-4. Use in agent
-
----
-
-### 4. Live Coding: Building MCP Integration (20 min)
-
-#### Step 1: Setup and Imports (2 min)
-```python
-import os
-from typing import Dict, List
-from mcp import ClientSession, StdioServerParameters
-from mcp.client.stdio import stdio_client
-
-from .tools import BaseTool, FunctionTool
-```
-
-**Dependencies:**
-- `mcp` package
-- Stdio client for communication
-
-**Live Coding**: Setup imports
-
----
-
-#### Step 2: Helper Function - Extract Text (2 min)
-```python
-def _extract_text_content(result) -> str:
-    """Extract text content from MCP tool result."""
-    if not hasattr(result, 'content'):
-        return str(result)
-    
-    texts = []
-    for item in result.content:
-        if hasattr(item, 'text'):
-            texts.append(item.text)
-        else:
-            texts.append(str(item))
-    
-    return "\n\n".join(texts)
-```
-
-**Purpose**: MCP returns structured content, we need text.
-
-**Live Coding**: Build extract function
-
----
-
-#### Step 3: load_mcp_tools() Function (6 min)
-```python
-async def load_mcp_tools(connection: Dict) -> List[BaseTool]:
-    """Load tools from an MCP server and convert to FunctionTools.
-    
-    Args:
-        connection: Dictionary with connection parameters:
-            - command: Command to run the MCP server
-            - args: Arguments for the command
-            - env: Environment variables (optional)
-    
-    Returns:
-        List of BaseTool instances wrapping MCP tools
-    """
-    tools = []
-    
-    async with stdio_client(StdioServerParameters(**connection)) as (read, write):
-        async with ClientSession(read, write) as session:
-            await session.initialize()
-            mcp_tools = await session.list_tools()
-            
-            for mcp_tool in mcp_tools.tools:
-                func_tool = _create_mcp_tool(mcp_tool, connection)
-                tools.append(func_tool)
-    
-    return tools
-```
-
-**Key Points:**
-- Connects via stdio
-- Initializes session
-- Lists tools
-- Wraps each tool
-
-**Live Coding**: Build load_mcp_tools()
-
----
-
-#### Step 4: _create_mcp_tool() Function (8 min)
-```python
-def _create_mcp_tool(mcp_tool, connection: Dict) -> FunctionTool:
-    """Create a FunctionTool that wraps an MCP tool."""
-    
-    async def call_mcp(**kwargs):
-        async with stdio_client(StdioServerParameters(**connection)) as (read, write):
-            async with ClientSession(read, write) as session:
-                await session.initialize()
-                result = await session.call_tool(mcp_tool.name, kwargs)
-                return _extract_text_content(result)
-    
-    tool_definition = {
-        "type": "function",
-        "function": {
-            "name": mcp_tool.name,
-            "description": mcp_tool.description,
-            "parameters": mcp_tool.inputSchema,
-        }
-    }
-    
-    return FunctionTool(
-        func=call_mcp,
-        name=mcp_tool.name,
-        description=mcp_tool.description,
-        tool_definition=tool_definition
-    )
-```
-
-**Key Points:**
-- Creates wrapper function
-- Connects on each call
-- Uses MCP schema
-- Returns FunctionTool
-
-**Live Coding**: Build _create_mcp_tool()
-
----
-
-#### Step 5: Testing MCP Integration (2 min)
-```python
-import os
-from agent_framework.mcp import load_mcp_tools
-
-connection = {
-    "command": "npx",
-    "args": ["-y", "tavily-mcp@latest"],
-    "env": {"TAVILY_API_KEY": os.getenv("TAVILY_API_KEY")}
-}
-
-tools = await load_mcp_tools(connection)
-print(f"Loaded {len(tools)} tools")
-for tool in tools:
-    print(f"  - {tool.name}: {tool.description}")
-```
-
-**Expected Output:**
-```
-Loaded 5 tools
-  - tavily_search: Search the web...
-  - tavily_extract: Extract content from URLs...
-  ...
-```
-
----
-
-### 5. Demo: Using MCP Tools (3 min)
-
-**Show:**
-- Loading Tavily tools
-- Using in agent
-- Web search working
-- Tool discovery
-
----
-
-### 6. MCP Server Setup (2 min)
-
-**Tavily MCP Server:**
-```bash
-# Install via npx
-npx -y tavily-mcp@latest
-
-# Or set up locally
-npm install -g tavily-mcp
-```
-
-**Other MCP Servers:**
-- File system tools
-- Database tools
-- API tools
-- Custom servers
-
----
-
-### 7. Next Steps (1 min)
-
-**Preview Episode 9:**
-- Session management
-- Memory optimization
-- Token management
-
-**What We Built:**
-- MCP integration
-- Tool discovery
-- External tool support
-
----
-
-## Key Takeaways
-
-1. **MCP** provides standard tool protocol
-2. **Stdio communication** for tool servers
-3. **Tool discovery** finds available tools
-4. **Automatic wrapping** converts to FunctionTool
-5. **Decoupled** tools from agents
-
----
-
-## Common Mistakes
-
-**Mistake 1: Not handling connection errors**
-```python
-# Wrong - crashes if server unavailable
-tools = await load_mcp_tools(connection)
-
-# Right - handle gracefully
-try:
-    tools = await load_mcp_tools(connection)
-except Exception as e:
-    print(f"Failed to load MCP tools: {e}")
-    tools = []
-```
-
-**Mistake 2: Forgetting environment variables**
-```python
-# Wrong - missing API key
-connection = {
-    "command": "npx",
-    "args": ["-y", "tavily-mcp@latest"]
-}
-
-# Right - include env
-connection = {
-    "command": "npx",
-    "args": ["-y", "tavily-mcp@latest"],
-    "env": {"TAVILY_API_KEY": os.getenv("TAVILY_API_KEY")}
-}
-```
-
----
-
-## Exercises
-
-1. Add connection pooling
-2. Implement tool caching
-3. Add MCP server health checks
-4. Create custom MCP server
-
----
-
-**Previous Episode**: [Episode 7: Tool Execution](./EPISODE_07_TOOL_EXECUTION.md)  
-**Next Episode**: [Episode 9: Session & Memory Management](./EPISODE_09_MEMORY.md)
-

misc/tutorials/EPISODE_09_MEMORY.md

@@ -1,658 +0,0 @@
-# Episode 9: Session & Memory Management
-
-**Duration**: 40 minutes  
-**What to Build**: `agent_framework/memory.py`, session integration in `agent.py`  
-**Target Audience**: Intermediate Python developers
-
----
-
-## Episode Structure
-
-### 1. Hook (2 min)
-**Show what we'll build:**
-- Session persistence
-- Memory optimization
-- Token management
-- Full session integration with agent
-
-**Hook Statement**: "Today we'll add memory to our agent - it will remember conversations across multiple interactions and optimize token usage. This makes agents truly useful for real applications!"
-
----
-
-### 2. Problem (3 min)
-**Why do we need memory management?**
-
-**The Challenge:**
-- Conversations get long
-- Token costs increase
-- Context windows limited
-- Need to remember across sessions
-- State must persist across agent runs
-
-**The Solution:**
-- Session persistence
-- Token counting
-- Memory optimization strategies
-- Full integration with agent loop
-
----
-
-### 3. Concept: Memory Strategies (5 min)
-
-**Strategies:**
-1. **Sliding Window**: Keep recent N messages
-2. **Compaction**: Replace tool calls/results with references
-3. **Summarization**: Compress old history with LLM
-
-**When to Use:**
-- Sliding Window: Simple, fast
-- Compaction: Tool-heavy conversations
-- Summarization: Very long conversations
-
----
-
-### 4. Live Coding: Building Memory System (30 min)
-
-#### Step 1: Session Models (3 min)
-```python
-# In agent_framework/models.py
-from pydantic import BaseModel, Field
-from datetime import datetime
-from typing import Any
-
-class Session(BaseModel):
-    """Container for persistent conversation state."""
-    session_id: str
-    user_id: str | None = None
-    events: list[Event] = Field(default_factory=list)
-    state: dict[str, Any] = Field(default_factory=dict)
-    created_at: datetime = Field(default_factory=datetime.now)
-    updated_at: datetime = Field(default_factory=datetime.now)
-```
-
-**Key Points:**
-- Stores events from conversation
-- Custom state for pending calls, etc.
-- Timestamps for tracking
-
-**Live Coding**: Build Session model
-
----
-
-#### Step 2: Session Manager (5 min)
-```python
-# In agent_framework/models.py
-from abc import ABC, abstractmethod
-
-class BaseSessionManager(ABC):
-    """Abstract base class for session management."""
-    
-    @abstractmethod
-    async def create(self, session_id: str, user_id: str | None = None) -> Session:
-        """Create a new session."""
-        pass
-    
-    @abstractmethod
-    async def get(self, session_id: str) -> Session | None:
-        """Retrieve a session by ID. Returns None if not found."""
-        pass
-    
-    @abstractmethod
-    async def save(self, session: Session) -> None:
-        """Persist session changes to storage."""
-        pass
-    
-    async def get_or_create(self, session_id: str, user_id: str | None = None) -> Session:
-        """Get existing session or create new one."""
-        session = await self.get(session_id)
-        if session is None:
-            session = await self.create(session_id, user_id)
-        return session
-
-
-class InMemorySessionManager(BaseSessionManager):
-    """In-memory session storage for development and testing."""
-    
-    def __init__(self):
-        self._sessions: dict[str, Session] = {}
-    
-    async def create(self, session_id: str, user_id: str | None = None) -> Session:
-        """Create a new session."""
-        if session_id in self._sessions:
-            raise ValueError(f"Session {session_id} already exists")
-        
-        session = Session(session_id=session_id, user_id=user_id)
-        self._sessions[session_id] = session
-        return session
-    
-    async def get(self, session_id: str) -> Session | None:
-        """Retrieve a session by ID."""
-        return self._sessions.get(session_id)
-    
-    async def save(self, session: Session) -> None:
-        """Save session to storage."""
-        self._sessions[session.session_id] = session
-```
-
-**Key Points:**
-- Abstract interface for flexibility
-- In-memory implementation for development
-- Easy to extend (database, Redis, etc.)
-
-**Live Coding**: Build session managers
-
----
-
-#### Step 3: Session Integration in Agent (8 min)
-
-**Update ExecutionContext:**
-```python
-# In agent_framework/models.py
-@dataclass
-class ExecutionContext:
-    """Central storage for all execution state."""
-    
-    execution_id: str = field(default_factory=lambda: str(uuid.uuid4()))
-    events: List[Event] = field(default_factory=list)
-    current_step: int = 0
-    state: Dict[str, Any] = field(default_factory=dict)
-    final_result: Optional[str | BaseModel] = None
-    session_id: Optional[str] = None  # NEW: Link to session for persistence
-```
-
-**Update Agent.__init__:**
-```python
-class Agent:
-    def __init__(
-        self,
-        model: LlmClient,
-        tools: List[BaseTool] = None,
-        instructions: str = "",
-        max_steps: int = 5,
-        session_manager: BaseSessionManager | None = None  # NEW
-    ):
-        # ... other init ...
-        self.session_manager = session_manager or InMemorySessionManager()
-```
-
-**Update Agent.run() with Full Session Support:**
-```python
-async def run(
-    self, 
-    user_input: str, 
-    context: ExecutionContext = None,
-    session_id: Optional[str] = None,
-    tool_confirmations: Optional[List[ToolConfirmation]] = None
-) -> AgentResult:
-    """Execute the agent with optional session support.
-    
-    Args:
-        user_input: User's input message
-        context: Optional execution context (creates new if None)
-        session_id: Optional session ID for persistent conversations
-        tool_confirmations: Optional list of tool confirmations for pending calls
-    """
-    # Load or create session if session_id is provided
-    session = None
-    if session_id and self.session_manager:
-        session = await self.session_manager.get_or_create(session_id)
-        
-        # Load session data into context if context is new
-        if context is None:
-            context = ExecutionContext()
-            # Restore events and state from session
-            context.events = session.events.copy()
-            context.state = session.state.copy()
-            context.execution_id = session.session_id
-        context.session_id = session_id
-
-    if tool_confirmations:
-        if context is None:
-            context = ExecutionContext()
-        context.state["tool_confirmations"] = [
-            c.model_dump() for c in tool_confirmations
-        ]
-    
-    # Create or reuse context
-    if context is None:
-        context = ExecutionContext()
-    
-    # Add user input as the first event
-    user_event = Event(
-        execution_id=context.execution_id,
-        author="user",
-        content=[Message(role="user", content=user_input)]
-    )
-    context.add_event(user_event)
-    
-    # Execute steps until completion or max steps reached
-    while not context.final_result and context.current_step < self.max_steps:
-        await self.step(context)
-        
-        # Check for pending confirmations after each step
-        if context.state.get("pending_tool_calls"):
-            pending_calls = [
-                PendingToolCall.model_validate(p)
-                for p in context.state["pending_tool_calls"]
-            ]
-            # Save session state before returning
-            if session:
-                session.events = context.events
-                session.state = context.state
-                await self.session_manager.save(session)
-            return AgentResult(
-                status="pending",
-                context=context,
-                pending_tool_calls=pending_calls,
-            )
-        
-        # Check if the last event is a final response
-        last_event = context.events[-1]
-        if self._is_final_response(last_event):
-            context.final_result = self._extract_final_result(last_event)
-    
-    # Save session after execution completes
-    if session:
-        session.events = context.events
-        session.state = context.state
-        await self.session_manager.save(session)
-
-    return AgentResult(output=context.final_result, context=context)
-```
-
-**Key Points:**
-- Load session at start of run()
-- Restore events and state from session
-- Set `context.session_id` for tracking
-- Save session before returning pending
-- Save session after completion
-
-**Live Coding**: Integrate session with agent
-
----
-
-#### Step 4: Token Counting (4 min)
-```python
-# In agent_framework/memory.py
-import tiktoken
-import json
-from .llm import build_messages
-from .models import LlmRequest
-
-def count_tokens(request: LlmRequest, model_id: str = "gpt-4") -> int:
-    """Calculate total token count of LlmRequest."""
-    try:
-        encoding = tiktoken.encoding_for_model(model_id)
-    except KeyError:
-        encoding = tiktoken.get_encoding("o200k_base")
-    
-    messages = build_messages(request)
-    total_tokens = 0
-    
-    for message in messages:
-        total_tokens += 4  # Per-message overhead
-        
-        if message.get("content"):
-            total_tokens += len(encoding.encode(message["content"]))
-        
-        if message.get("tool_calls"):
-            for tool_call in message["tool_calls"]:
-                func = tool_call.get("function", {})
-                if func.get("name"):
-                    total_tokens += len(encoding.encode(func["name"]))
-                if func.get("arguments"):
-                    total_tokens += len(encoding.encode(func["arguments"]))
-    
-    if request.tools:
-        for tool in request.tools:
-            tool_def = tool.tool_definition
-            total_tokens += len(encoding.encode(json.dumps(tool_def)))
-    
-    return total_tokens
-```
-
-**Key Points:**
-- Uses tiktoken for accurate counting
-- Counts messages, tool calls, tools
-- Model-specific encoding
-
-**Live Coding**: Build token counting
-
----
-
-#### Step 5: Sliding Window (4 min)
-```python
-# In agent_framework/memory.py
-from .models import Message
-
-def apply_sliding_window(
-    context: ExecutionContext,
-    request: LlmRequest,
-    window_size: int = 20
-) -> None:
-    """Keep only the most recent N messages."""
-    contents = request.contents
-    
-    # Find user message position
-    user_message_idx = None
-    for i, item in enumerate(contents):
-        if isinstance(item, Message) and item.role == "user":
-            user_message_idx = i
-            break
-    
-    if user_message_idx is None:
-        return
-    
-    # Preserve up to user message
-    preserved = contents[:user_message_idx + 1]
-    
-    # Keep only the most recent N from remaining items
-    remaining = contents[user_message_idx + 1:]
-    if len(remaining) > window_size:
-        remaining = remaining[-window_size:]
-    
-    request.contents = preserved + remaining
-```
-
-**Key Points:**
-- Preserves user message
-- Keeps recent N items
-- Simple and fast
-
-**Live Coding**: Build sliding window
-
----
-
-#### Step 6: Compaction (4 min)
-```python
-# In agent_framework/memory.py
-from .models import ToolCall, ToolResult
-
-TOOLRESULT_COMPACTION_RULES = {
-    "read_file": "File content from {file_path}. Re-read if needed.",
-    "search_web": "Search results processed. Query: {query}. Re-search if needed.",
-}
-
-def apply_compaction(context: ExecutionContext, request: LlmRequest) -> None:
-    """Compress tool calls and results into reference messages."""
-    tool_call_args = {}
-    compacted = []
-    
-    for item in request.contents:
-        if isinstance(item, ToolCall):
-            tool_call_args[item.tool_call_id] = item.arguments
-            compacted.append(item)  # Keep tool calls
-            
-        elif isinstance(item, ToolResult):
-            if item.name in TOOLRESULT_COMPACTION_RULES:
-                args = tool_call_args.get(item.tool_call_id, {})
-                template = TOOLRESULT_COMPACTION_RULES[item.name]
-                compressed_content = template.format(
-                    file_path=args.get("file_path", "unknown"),
-                    query=args.get("query", "unknown")
-                )
-                compacted.append(ToolResult(
-                    tool_call_id=item.tool_call_id,
-                    name=item.name,
-                    status=item.status,
-                    content=[compressed_content]
-                ))
-            else:
-                compacted.append(item)
-        else:
-            compacted.append(item)
-    
-    request.contents = compacted
-```
-
-**Key Points:**
-- Replaces tool results with references
-- Configurable rules
-- Reduces token count
-
-**Live Coding**: Build compaction
-
----
-
-#### Step 7: Optimizer Callback (3 min)
-```python
-# In agent_framework/callbacks.py
-import inspect
-from typing import Callable, Optional
-from .models import ExecutionContext
-from .llm import LlmRequest, LlmResponse
-from .memory import count_tokens
-
-def create_optimizer_callback(
-    apply_optimization: Callable,
-    threshold: int = 50000,
-    model_id: str = "gpt-4"
-) -> Callable:
-    """Factory for optimization callbacks."""
-    async def callback(
-        context: ExecutionContext,
-        request: LlmRequest
-    ) -> Optional[LlmResponse]:
-        token_count = count_tokens(request, model_id=model_id)
-        
-        if token_count < threshold:
-            return None
-        
-        result = apply_optimization(context, request)
-        if inspect.isawaitable(result):
-            await result
-        return None
-    
-    return callback
-```
-
-**Key Points:**
-- Factory function
-- Checks threshold
-- Supports sync/async
-
-**Live Coding**: Build callback system
-
----
-
-### 5. Testing Session Integration (3 min)
-
-**Test Session Persistence:**
-```python
-import asyncio
-from agent_framework import Agent, LlmClient, InMemorySessionManager
-from agent_tools import calculator
-
-# Create a shared session manager
-session_manager = InMemorySessionManager()
-
-# Create agent with session support
-agent = Agent(
-    model=LlmClient(model="gpt-4o-mini"),
-    tools=[calculator],
-    instructions="You are a helpful assistant.",
-    session_manager=session_manager
-)
-
-session_id = "user-123"
-
-# First conversation - introduce yourself
-result1 = await agent.run(
-    "Hi! My name is Alice and I'm a software engineer.",
-    session_id=session_id
-)
-print(f"Response 1: {result1.output}")
-print(f"Events: {len(result1.context.events)}")
-
-# Second conversation - continue
-result2 = await agent.run(
-    "What's 1234 * 5678?",
-    session_id=session_id
-)
-print(f"Response 2: {result2.output}")
-print(f"Events: {len(result2.context.events)}")  # Should include previous events!
-
-# Third conversation - test memory
-result3 = await agent.run(
-    "What's my name and what do I do for work?",
-    session_id=session_id
-)
-print(f"Response 3: {result3.output}")
-# Should remember: "Your name is Alice and you're a software engineer."
-
-# Different session - should NOT remember
-result4 = await agent.run(
-    "What's my name?",
-    session_id="different-user"
-)
-print(f"Response 4: {result4.output}")
-# Should say it doesn't know
-```
-
-**Test Session Isolation:**
-```python
-# Check stored sessions
-print("Session Storage Summary:")
-for sid, session in session_manager._sessions.items():
-    print(f"Session ID: {session.session_id}")
-    print(f"  Events: {len(session.events)}")
-    print(f"  State keys: {list(session.state.keys())}")
-```
-
----
-
-### 6. Demo: Memory in Action (3 min)
-
-**Show:**
-- Session persistence across runs
-- Token counting
-- Sliding window optimization
-- Long conversation handling
-- Session isolation between users
-
----
-
-### 7. Next Steps (1 min)
-
-**Preview Episode 10:**
-- Web deployment
-- FastAPI backend
-- Frontend interface
-
-**What We Built:**
-- Session model and managers
-- Full session integration with Agent.run()
-- Token counting
-- Memory optimization strategies
-
----
-
-## Key Takeaways
-
-1. **Sessions** persist conversations across multiple run() calls
-2. **session_id** links context to session
-3. **Events and state** are restored from session
-4. **Session saves** on pending and completion
-5. **Token counting** tracks usage
-6. **Optimization strategies** reduce costs
-
----
-
-## Common Mistakes
-
-**Mistake 1: Not loading session state**
-```python
-# Wrong - creates empty context
-if context is None:
-    context = ExecutionContext()
-
-# Right - loads from session
-if context is None:
-    context = ExecutionContext()
-    context.events = session.events.copy()
-    context.state = session.state.copy()
-```
-
-**Mistake 2: Not saving before pending return**
-```python
-# Wrong - loses state on pending
-if context.state.get("pending_tool_calls"):
-    return AgentResult(status="pending", ...)
-
-# Right - saves before returning
-if context.state.get("pending_tool_calls"):
-    if session:
-        session.events = context.events
-        session.state = context.state
-        await self.session_manager.save(session)
-    return AgentResult(status="pending", ...)
-```
-
-**Mistake 3: Mutating session directly**
-```python
-# Wrong - might not persist
-session.events.append(new_event)
-
-# Right - copy and save
-session.events = context.events  # Full replacement
-await self.session_manager.save(session)
-```
-
----
-
-## Exercises
-
-1. **Implement Database Session Manager**: Create a PostgreSQL or SQLite session manager
-2. **Add Session Expiry**: Auto-delete sessions after 24 hours of inactivity
-3. **Build Token Dashboard**: Track token usage per session
-4. **Add Summarization Strategy**: Use LLM to summarize old history
-
----
-
-## Complete Session Flow
-
-```
-User Request with session_id="user-123"
-    |
-    v
-Agent.run(session_id="user-123")
-    |
-    v
-session_manager.get_or_create("user-123")
-    |
-    v
-[New Session?] --Yes--> Create empty Session
-    |                        |
-    No                       |
-    |                        v
-    v                   context = ExecutionContext()
-Load existing Session       |
-    |                        v
-    v               context.events = []
-context = ExecutionContext()
-context.events = session.events.copy()
-context.state = session.state.copy()
-    |
-    v
-Execute agent loop (step, step, ...)
-    |
-    +--[Pending?]--Yes--> Save session, return pending
-    |
-    No
-    |
-    v
-Complete execution
-    |
-    v
-session.events = context.events
-session.state = context.state
-await session_manager.save(session)
-    |
-    v
-Return AgentResult(status="complete")
-```
-
----
-
-**Previous Episode**: [Episode 8: MCP Integration](./EPISODE_08_MCP.md)  
-**Next Episode**: [Episode 10: Web Deployment](./EPISODE_10_WEB_DEPLOYMENT.md)

misc/tutorials/EPISODE_10_WEB_DEPLOYMENT.md

@@ -1,425 +0,0 @@
-# Episode 10: Web Deployment
-
-**Duration**: 35 minutes  
-**What to Build**: `web_app/app.py`, `web_app/static/index.html`  
-**Target Audience**: Intermediate Python developers
-
----
-
-## Episode Structure
-
-### 1. Hook (2 min)
-**Show what we'll build:**
-- Complete web application
-- Chat interface
-- File uploads
-- Session management
-
-**Hook Statement**: "Today we'll deploy our agent as a web application. This is the final piece - making it accessible to users through a beautiful interface!"
-
----
-
-### 2. Problem (3 min)
-**Why deploy as a web app?**
-
-**The Challenge:**
-- Command-line isn't user-friendly
-- Need file uploads
-- Want real-time interaction
-- Need session management UI
-
-**The Solution:**
-- FastAPI backend
-- Modern frontend
-- RESTful API
-- Static file serving
-
----
-
-### 3. Concept: Web Architecture (5 min)
-
-**Architecture:**
-```
-Frontend (HTML/CSS/JS)
-    ↓ HTTP Requests
-FastAPI Backend
-    ↓
-Agent Framework
-    ↓
-LLM API
-```
-
-**Components:**
-- Backend: FastAPI server
-- Frontend: Static HTML/CSS/JS
-- API: RESTful endpoints
-- File handling: Upload directory
-
----
-
-### 4. Live Coding: Building Web App (25 min)
-
-#### Step 1: FastAPI Setup (3 min)
-```python
-from fastapi import FastAPI, UploadFile, File, HTTPException
-from fastapi.staticfiles import StaticFiles
-from fastapi.responses import HTMLResponse
-from fastapi.middleware.cors import CORSMiddleware
-from pydantic import BaseModel
-from pathlib import Path
-import uuid
-
-app = FastAPI(title="Agent Chat")
-
-# Enable CORS
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=["*"],
-    allow_credentials=True,
-    allow_methods=["*"],
-    allow_headers=["*"],
-)
-
-# Serve static files
-app.mount("/static", StaticFiles(directory="static"), name="static")
-```
-
-**Key Points:**
-- FastAPI app
-- CORS enabled
-- Static file serving
-
-**Live Coding**: Setup FastAPI
-
----
-
-#### Step 2: Agent Creation (2 min)
-```python
-from agent_framework import Agent, LlmClient, InMemorySessionManager
-from agent_tools import calculator, search_web, read_file
-
-session_manager = InMemorySessionManager()
-UPLOAD_DIR = Path("uploads")
-UPLOAD_DIR.mkdir(exist_ok=True)
-
-def create_agent(use_session: bool = True) -> Agent:
-    """Create an agent instance."""
-    return Agent(
-        model=LlmClient(model="gpt-4o-mini"),
-        tools=[calculator, search_web, read_file],
-        instructions="You are a helpful assistant.",
-        max_steps=10,
-        session_manager=session_manager if use_session else None
-    )
-```
-
-**Key Points:**
-- Shared session manager
-- Configurable tools
-- Session toggle
-
-**Live Coding**: Build agent creation
-
----
-
-#### Step 3: API Models (2 min)
-```python
-class ChatRequest(BaseModel):
-    message: str
-    session_id: Optional[str] = None
-    use_session: bool = True
-
-class ChatResponse(BaseModel):
-    response: str
-    session_id: str
-    events_count: int
-    tools_used: List[str]
-    trace: str
-```
-
-**Key Points:**
-- Request/response models
-- Session support
-- Trace included
-
-**Live Coding**: Build API models
-
----
-
-#### Step 4: Chat Endpoint (5 min)
-```python
-@app.post("/api/chat")
-async def chat(request: ChatRequest) -> ChatResponse:
-    """Send a message to the agent."""
-    session_id = request.session_id or str(uuid.uuid4())
-    agent = create_agent(use_session=request.use_session)
-    
-    try:
-        if request.use_session:
-            result = await agent.run(request.message, session_id=session_id)
-        else:
-            result = await agent.run(request.message)
-        
-        # Extract tools used
-        tools_used = []
-        for event in result.context.events:
-            for item in event.content:
-                if hasattr(item, 'name') and item.type == "tool_call":
-                    if item.name not in tools_used:
-                        tools_used.append(item.name)
-        
-        # Format trace
-        from agent_framework import format_trace
-        trace_output = format_trace(result.context)
-        
-        return ChatResponse(
-            response=str(result.output) if result.output else "No response.",
-            session_id=session_id,
-            events_count=len(result.context.events),
-            tools_used=tools_used,
-            trace=trace_output
-        )
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))
-```
-
-**Key Points:**
-- Handles sessions
-- Extracts tools
-- Formats trace
-- Error handling
-
-**Live Coding**: Build chat endpoint
-
----
-
-#### Step 5: File Upload Endpoint (3 min)
-```python
-@app.post("/api/upload")
-async def upload_file(file: UploadFile = File(...)):
-    """Upload a file."""
-    file_path = UPLOAD_DIR / file.filename
-    
-    with open(file_path, "wb") as f:
-        content = await file.read()
-        f.write(content)
-    
-    return {"filename": file.filename, "path": str(file_path)}
-```
-
-**Key Points:**
-- Saves to uploads directory
-- Returns file info
-
-**Live Coding**: Build upload endpoint
-
----
-
-#### Step 6: Frontend HTML Structure (5 min)
-```html
-<!DOCTYPE html>
-<html>
-<head>
-    <title>Agent Chat</title>
-    <link rel="stylesheet" href="/static/style.css">
-</head>
-<body>
-    <div class="container">
-        <div class="sidebar">
-            <h2>Tools</h2>
-            <div id="tools-list"></div>
-            
-            <h2>Files</h2>
-            <input type="file" id="file-input">
-            <div id="files-list"></div>
-        </div>
-        
-        <div class="chat-area">
-            <div class="chat-header">
-                <h1>Agent Chat</h1>
-                <button id="trace-btn">View Trace</button>
-            </div>
-            <div id="messages"></div>
-            <div class="input-area">
-                <input type="text" id="message-input" placeholder="Type a message...">
-                <button id="send-btn">Send</button>
-            </div>
-        </div>
-    </div>
-    
-    <script src="/static/script.js"></script>
-</body>
-</html>
-```
-
-**Key Points:**
-- Sidebar for tools/files
-- Chat area
-- Input area
-- Trace button
-
-**Live Coding**: Build HTML structure
-
----
-
-#### Step 7: Frontend JavaScript (5 min)
-```javascript
-let sessionId = null;
-
-async function sendMessage() {
-    const input = document.getElementById('message-input');
-    const message = input.value;
-    if (!message) return;
-    
-    // Add user message to UI
-    addMessage('user', message);
-    input.value = '';
-    
-    // Send to API
-    const response = await fetch('/api/chat', {
-        method: 'POST',
-        headers: {'Content-Type': 'application/json'},
-        body: JSON.stringify({
-            message: message,
-            session_id: sessionId,
-            use_session: true
-        })
-    });
-    
-    const data = await response.json();
-    sessionId = data.session_id;
-    
-    // Add agent response
-    addMessage('assistant', data.response);
-}
-
-function addMessage(role, content) {
-    const messages = document.getElementById('messages');
-    const div = document.createElement('div');
-    div.className = `message ${role}`;
-    div.textContent = content;
-    messages.appendChild(div);
-    messages.scrollTop = messages.scrollHeight;
-}
-
-document.getElementById('send-btn').addEventListener('click', sendMessage);
-document.getElementById('message-input').addEventListener('keypress', (e) => {
-    if (e.key === 'Enter') sendMessage();
-});
-```
-
-**Key Points:**
-- Session management
-- Message sending
-- UI updates
-
-**Live Coding**: Build JavaScript
-
----
-
-### 5. Demo: Complete Web App (3 min)
-
-**Show:**
-- Chat interface
-- File upload
-- Tool listing
-- Trace display
-- Session persistence
-
----
-
-### 6. Deployment Tips (2 min)
-
-**Development:**
-```bash
-uvicorn web_app.app:app --reload
-```
-
-**Production:**
-```bash
-uvicorn web_app.app:app --host 0.0.0.0 --port 8000
-```
-
-**Docker:**
-```dockerfile
-FROM python:3.11
-WORKDIR /app
-COPY . .
-RUN pip install -r requirements.txt
-CMD ["uvicorn", "web_app.app:app", "--host", "0.0.0.0", "--port", "8000"]
-```
-
----
-
-### 7. Next Steps (1 min)
-
-**What We Built:**
-- Complete web application
-- Full agent framework
-- Production-ready system
-
-**Future Enhancements:**
-- WebSocket for streaming
-- User authentication
-- Database sessions
-- Monitoring and logging
-
----
-
-## Key Takeaways
-
-1. **FastAPI** provides easy API creation
-2. **Static files** for frontend
-3. **RESTful API** for communication
-4. **Session management** via API
-5. **File handling** for uploads
-
----
-
-## Common Mistakes
-
-**Mistake 1: Not handling CORS**
-```python
-# Wrong - CORS errors
-app = FastAPI()
-
-# Right - CORS enabled
-app.add_middleware(CORSMiddleware, allow_origins=["*"])
-```
-
-**Mistake 2: Not serving static files**
-```python
-# Wrong - can't load CSS/JS
-app = FastAPI()
-
-# Right - serve static files
-app.mount("/static", StaticFiles(directory="static"), name="static")
-```
-
----
-
-## Exercises
-
-1. Add WebSocket support
-2. Implement user authentication
-3. Add database session storage
-4. Create admin dashboard
-
----
-
-**Previous Episode**: [Episode 9: Session & Memory Management](./EPISODE_09_MEMORY.md)  
-**Series Complete!** 🎉
-
----
-
-## Series Summary
-
-You've built:
-- Complete agent framework
-- Tool system
-- MCP integration
-- Memory management
-- Web deployment
-
-**Congratulations on completing the series!**
-

misc/tutorials/EXERCISES.md

@@ -1,991 +0,0 @@
-# Exercises and Challenges
-
-This document contains exercises for each episode to reinforce learning. Exercises are designed to build incrementally toward the actual codebase implementation.
-
----
-
-## Episode 1: Python Foundations
-
-### Exercise 1: Pydantic Model
-Create a `User` model with:
-- `name`: string (required)
-- `email`: string (required, must contain "@")
-- `age`: integer (optional, must be >= 0)
-- `is_active`: boolean (default: True)
-
-**Solution:**
-```python
-from pydantic import BaseModel, field_validator
-
-class User(BaseModel):
-    name: str
-    email: str
-    age: int | None = None
-    is_active: bool = True
-    
-    @field_validator('email')
-    def validate_email(cls, v):
-        if '@' not in v:
-            raise ValueError('Email must contain @')
-        return v
-    
-    @field_validator('age')
-    def validate_age(cls, v):
-        if v is not None and v < 0:
-            raise ValueError('Age must be >= 0')
-        return v
-```
-
-### Exercise 2: Dataclass with Methods
-Create a `ShoppingCart` dataclass with:
-- `items`: list of strings (default: empty list)
-- `total`: float (default: 0.0)
-- Methods: `add_item(name, price)`, `get_total()`
-
-**Solution:**
-```python
-from dataclasses import dataclass, field
-
-@dataclass
-class ShoppingCart:
-    items: list[dict] = field(default_factory=list)
-    total: float = 0.0
-    
-    def add_item(self, name: str, price: float):
-        self.items.append({"name": name, "price": price})
-        self.total += price
-    
-    def get_total(self) -> float:
-        return self.total
-```
-
-### Exercise 3: Async Parallel Calls
-Write a function that makes 5 concurrent API calls and returns all results.
-
-**Solution:**
-```python
-import asyncio
-
-async def call_api(id: int) -> str:
-    await asyncio.sleep(1)  # Simulate API call
-    return f"Result {id}"
-
-async def parallel_calls():
-    results = await asyncio.gather(
-        call_api(1),
-        call_api(2),
-        call_api(3),
-        call_api(4),
-        call_api(5)
-    )
-    return results
-
-# Run it
-results = asyncio.run(parallel_calls())
-print(results)
-```
-
----
-
-## Episode 2: Your First LLM Call
-
-### Exercise 1: Retry with Backoff
-Implement exponential backoff for rate limit errors.
-
-**Solution:**
-```python
-import asyncio
-from litellm import acompletion
-from litellm.exceptions import RateLimitError
-
-async def call_with_retry(messages: list, max_retries: int = 3):
-    delay = 1
-    for attempt in range(max_retries):
-        try:
-            response = await acompletion(
-                model="gpt-4o-mini",
-                messages=messages
-            )
-            return response.choices[0].message.content
-        except RateLimitError:
-            if attempt < max_retries - 1:
-                await asyncio.sleep(delay)
-                delay *= 2  # Exponential backoff
-            else:
-                raise
-```
-
-### Exercise 2: Streaming Responses
-Implement streaming for real-time output.
-
-**Solution:**
-```python
-from litellm import acompletion
-
-async def stream_response(prompt: str):
-    messages = [{"role": "user", "content": prompt}]
-    
-    response = await acompletion(
-        model="gpt-4o-mini",
-        messages=messages,
-        stream=True
-    )
-    
-    async for chunk in response:
-        if chunk.choices[0].delta.content:
-            yield chunk.choices[0].delta.content
-
-# Usage
-async def main():
-    async for chunk in stream_response("Tell me a story"):
-        print(chunk, end='', flush=True)
-
-asyncio.run(main())
-```
-
-### Exercise 3: Temperature Experiment
-Call the LLM 5 times with temperature=0 and 5 times with temperature=1. Compare outputs.
-
-**Solution:**
-```python
-async def temperature_experiment(prompt: str):
-    results_temp0 = []
-    results_temp1 = []
-    
-    for _ in range(5):
-        response = await acompletion(
-            model="gpt-4o-mini",
-            messages=[{"role": "user", "content": prompt}],
-            temperature=0
-        )
-        results_temp0.append(response.choices[0].message.content)
-    
-    for _ in range(5):
-        response = await acompletion(
-            model="gpt-4o-mini",
-            messages=[{"role": "user", "content": prompt}],
-            temperature=1
-        )
-        results_temp1.append(response.choices[0].message.content)
-    
-    print("Temperature 0 (deterministic):")
-    for r in results_temp0:
-        print(f"  {r}")
-    
-    print("\nTemperature 1 (creative):")
-    for r in results_temp1:
-        print(f"  {r}")
-```
-
----
-
-## Episode 3: Core Data Models
-
-### Exercise 1: Build ToolConfirmation Model
-Create the `ToolConfirmation` model that captures a user's decision on a pending tool call. It should have:
-- `tool_call_id`: string (required) - links to the pending tool call
-- `approved`: boolean (required) - whether user approved
-- `modified_arguments`: optional dict - if user wants to change arguments
-- `reason`: optional string - reason for rejection
-
-**Solution:**
-```python
-from pydantic import BaseModel
-
-class ToolConfirmation(BaseModel):
-    """User's decision on a pending tool call."""
-    
-    tool_call_id: str
-    approved: bool
-    modified_arguments: dict | None = None
-    reason: str | None = None  # Reason for rejection
-```
-
-### Exercise 2: Build PendingToolCall Model
-Create the `PendingToolCall` model that wraps a ToolCall awaiting confirmation:
-- `tool_call`: ToolCall (required) - the original tool call
-- `confirmation_message`: string (required) - message to show user
-
-**Solution:**
-```python
-class PendingToolCall(BaseModel):
-    """A tool call awaiting user confirmation."""
-    
-    tool_call: ToolCall  # Assumes ToolCall is already defined
-    confirmation_message: str
-```
-
-### Exercise 3: Add Validation to ToolConfirmation
-Add a validator that requires `reason` when `approved=False`.
-
-**Solution:**
-```python
-from pydantic import BaseModel, model_validator
-
-class ToolConfirmation(BaseModel):
-    """User's decision on a pending tool call."""
-    
-    tool_call_id: str
-    approved: bool
-    modified_arguments: dict | None = None
-    reason: str | None = None
-    
-    @model_validator(mode='after')
-    def validate_reason_on_rejection(self):
-        if not self.approved and not self.reason:
-            raise ValueError('reason is required when approved=False')
-        return self
-```
-
-### Exercise 4: Extract Pending Calls Helper
-Create a helper function to extract pending tool calls from ExecutionContext state.
-
-**Solution:**
-```python
-from typing import List
-
-def extract_pending_calls(context: ExecutionContext) -> List[PendingToolCall]:
-    """Extract all pending tool calls from context state."""
-    raw_pending = context.state.get("pending_tool_calls", [])
-    return [PendingToolCall.model_validate(p) for p in raw_pending]
-```
-
----
-
-## Episode 4: The LLM Client
-
-### Exercise 1: Add Streaming Support
-Add streaming support to `LlmClient`.
-
-**Solution:**
-```python
-async def generate_streaming(self, request: LlmRequest):
-    """Generate streaming response from LLM."""
-    messages = self._build_messages(request)
-    
-    response = await acompletion(
-        model=self.model,
-        messages=messages,
-        stream=True
-    )
-    
-    async for chunk in response:
-        if chunk.choices[0].delta.content:
-            yield chunk.choices[0].delta.content
-```
-
-### Exercise 2: Response Caching
-Implement response caching based on request hash.
-
-**Solution:**
-```python
-import hashlib
-import json
-
-class LlmClient:
-    def __init__(self, model: str, cache: dict = None, **config):
-        self.model = model
-        self.config = config
-        self.cache = cache or {}
-    
-    def _get_cache_key(self, request: LlmRequest) -> str:
-        """Generate cache key from request."""
-        data = {
-            "model": self.model,
-            "instructions": request.instructions,
-            "contents": [c.model_dump() for c in request.contents]
-        }
-        return hashlib.md5(json.dumps(data, sort_keys=True).encode()).hexdigest()
-    
-    async def generate(self, request: LlmRequest) -> LlmResponse:
-        cache_key = self._get_cache_key(request)
-        if cache_key in self.cache:
-            return self.cache[cache_key]
-        
-        response = await self._generate_uncached(request)
-        self.cache[cache_key] = response
-        return response
-```
-
----
-
-## Episode 5: The Basic Agent Loop
-
-### Exercise 1: Add Verbose Logging
-Add verbose logging to show agent thinking process.
-
-**Solution:**
-```python
-import logging
-
-class Agent:
-    def __init__(self, ..., verbose: bool = False):
-        # ... existing code ...
-        self.verbose = verbose
-        if verbose:
-            logging.basicConfig(level=logging.INFO)
-    
-    async def step(self, context: ExecutionContext):
-        if self.verbose:
-            logging.info(f"Step {context.current_step + 1}: Thinking...")
-        
-        llm_request = self._prepare_llm_request(context)
-        llm_response = await self.think(llm_request)
-        
-        if self.verbose:
-            logging.info(f"Step {context.current_step + 1}: Got response")
-            for item in llm_response.content:
-                if isinstance(item, Message):
-                    logging.info(f"  Message: {item.content[:100]}")
-```
-
-### Exercise 2: Step-by-Step Trace
-Implement a method to display step-by-step trace.
-
-**Solution:**
-```python
-def display_step_trace(self, context: ExecutionContext, step: int):
-    """Display trace for a specific step."""
-    if step >= len(context.events):
-        print(f"Step {step} does not exist")
-        return
-    
-    event = context.events[step]
-    print(f"\n{'='*60}")
-    print(f"Step {step + 1} - {event.author.upper()}")
-    print(f"{'='*60}")
-    
-    for item in event.content:
-        if isinstance(item, Message):
-            print(f"[Message] {item.role}: {item.content}")
-        elif isinstance(item, ToolCall):
-            print(f"[Tool Call] {item.name}({item.arguments})")
-        elif isinstance(item, ToolResult):
-            print(f"[Tool Result] {item.name}: {item.status}")
-```
-
----
-
-## Episode 6: Building the Tool System
-
-### Exercise 1: Add requires_confirmation to a Tool
-Create a `delete_file` tool that requires confirmation before execution.
-
-**Solution:**
-```python
-from agent_framework import tool
-
-@tool(
-    requires_confirmation=True,
-    confirmation_message="Delete file '{arguments[filename]}'? This cannot be undone."
-)
-def delete_file(filename: str) -> str:
-    """Delete a file from the filesystem."""
-    import os
-    os.remove(filename)
-    return f"Deleted {filename}"
-
-# Test it
-print(delete_file.requires_confirmation)  # True
-print(delete_file.get_confirmation_message({"filename": "test.txt"}))
-# "Delete file 'test.txt'? This cannot be undone."
-```
-
-### Exercise 2: Create Custom Confirmation Message Template
-Create a `send_email` tool with a detailed confirmation message.
-
-**Solution:**
-```python
-@tool(
-    requires_confirmation=True,
-    confirmation_message=(
-        "Send email?\n"
-        "  To: {arguments[recipient]}\n"
-        "  Subject: {arguments[subject]}\n"
-        "  Body preview: {arguments[body][:50]}..."
-    )
-)
-def send_email(recipient: str, subject: str, body: str) -> str:
-    """Send an email to a recipient."""
-    # ... email sending logic ...
-    return f"Email sent to {recipient}"
-
-# Test confirmation message
-msg = send_email.get_confirmation_message({
-    "recipient": "user@example.com",
-    "subject": "Hello",
-    "body": "This is a test email with some content that is quite long..."
-})
-print(msg)
-```
-
-### Exercise 3: Tool Registry with Confirmation Status
-Create a tool registry that tracks confirmation requirements.
-
-**Solution:**
-```python
-class ToolRegistry:
-    def __init__(self):
-        self._tools: Dict[str, BaseTool] = {}
-    
-    def register(self, tool: BaseTool):
-        """Register a tool."""
-        self._tools[tool.name] = tool
-    
-    def get(self, name: str) -> BaseTool | None:
-        """Get a tool by name."""
-        return self._tools.get(name)
-    
-    def list_all(self) -> List[BaseTool]:
-        """List all registered tools."""
-        return list(self._tools.values())
-    
-    def list_dangerous(self) -> List[BaseTool]:
-        """List tools requiring confirmation."""
-        return [t for t in self._tools.values() if t.requires_confirmation]
-    
-    def list_safe(self) -> List[BaseTool]:
-        """List tools not requiring confirmation."""
-        return [t for t in self._tools.values() if not t.requires_confirmation]
-
-# Usage
-registry = ToolRegistry()
-registry.register(calculator)
-registry.register(delete_file)
-print(f"Safe tools: {[t.name for t in registry.list_safe()]}")
-print(f"Dangerous tools: {[t.name for t in registry.list_dangerous()]}")
-```
-
----
-
-## Episode 7: Tool Execution with Confirmation
-
-### Exercise 1: Implement Pending Tool Call Detection
-Write the logic to detect when a tool requires confirmation and create a PendingToolCall.
-
-**Solution:**
-```python
-async def act(
-    self, 
-    context: ExecutionContext, 
-    tool_calls: List[ToolCall]
-) -> List[ToolResult]:
-    tools_dict = {tool.name: tool for tool in self.tools}
-    results = []
-    pending_calls = []
-
-    for tool_call in tool_calls:
-        tool = tools_dict[tool_call.name]
-        
-        # Check if confirmation is required
-        if tool.requires_confirmation:
-            pending = PendingToolCall(
-                tool_call=tool_call,
-                confirmation_message=tool.get_confirmation_message(
-                    tool_call.arguments
-                )
-            )
-            pending_calls.append(pending)
-            continue  # Skip execution
-        
-        # Execute tool normally
-        try:
-            result = await tool(context, **tool_call.arguments)
-            status = "success"
-        except Exception as e:
-            result = str(e)
-            status = "error"
-        
-        results.append(ToolResult(
-            tool_call_id=tool_call.tool_call_id,
-            name=tool_call.name,
-            status=status,
-            content=[result]
-        ))
-    
-    # Store pending calls in state
-    if pending_calls:
-        context.state["pending_tool_calls"] = [
-            p.model_dump() for p in pending_calls
-        ]
-    
-    return results
-```
-
-### Exercise 2: Build Confirmation Processing Logic
-Implement `_process_confirmations` that handles approved and rejected tools.
-
-**Solution:**
-```python
-async def _process_confirmations(
-    self,
-    context: ExecutionContext
-) -> List[ToolResult]:
-    tools_dict = {tool.name: tool for tool in self.tools}
-    results = []
-
-    # Build maps
-    pending_map = {
-        p["tool_call"]["tool_call_id"]: PendingToolCall.model_validate(p)
-        for p in context.state["pending_tool_calls"]
-    }
-    confirmation_map = {
-        c["tool_call_id"]: ToolConfirmation.model_validate(c)
-        for c in context.state["tool_confirmations"]
-    }
-
-    for tool_call_id, pending in pending_map.items():
-        tool = tools_dict.get(pending.tool_call.name)
-        confirmation = confirmation_map.get(tool_call_id)
-
-        if confirmation and confirmation.approved:
-            # Merge modified arguments
-            arguments = {
-                **pending.tool_call.arguments,
-                **(confirmation.modified_arguments or {})
-            }
-            
-            try:
-                output = await tool(context, **arguments)
-                results.append(ToolResult(
-                    tool_call_id=tool_call_id,
-                    name=pending.tool_call.name,
-                    status="success",
-                    content=[output],
-                ))
-            except Exception as e:
-                results.append(ToolResult(
-                    tool_call_id=tool_call_id,
-                    name=pending.tool_call.name,
-                    status="error",
-                    content=[str(e)],
-                ))
-        else:
-            # Rejected
-            reason = (confirmation.reason if confirmation 
-                      else "Tool execution was not approved.")
-            results.append(ToolResult(
-                tool_call_id=tool_call_id,
-                name=pending.tool_call.name,
-                status="error",
-                content=[reason],
-            ))
-
-    return results
-```
-
-### Exercise 3: Test Complete Confirmation Workflow
-Write a test that demonstrates the full confirmation workflow.
-
-**Solution:**
-```python
-import asyncio
-from agent_framework import Agent, LlmClient, ToolConfirmation, tool
-
-@tool(requires_confirmation=True)
-def dangerous_action(action: str) -> str:
-    """Perform a dangerous action."""
-    return f"Executed: {action}"
-
-async def test_confirmation_workflow():
-    agent = Agent(
-        model=LlmClient(model="gpt-4o-mini"),
-        tools=[dangerous_action],
-        instructions="Execute dangerous actions when asked."
-    )
-    
-    # Step 1: Initial request triggers pending
-    result1 = await agent.run("Execute the dangerous action 'delete_all'")
-    print(f"Status: {result1.status}")  # "pending"
-    print(f"Pending: {result1.pending_tool_calls[0].confirmation_message}")
-    
-    # Step 2: User approves
-    confirmation = ToolConfirmation(
-        tool_call_id=result1.pending_tool_calls[0].tool_call.tool_call_id,
-        approved=True
-    )
-    
-    result2 = await agent.run(
-        "",  # Empty - resuming
-        context=result1.context,
-        tool_confirmations=[confirmation]
-    )
-    print(f"Status: {result2.status}")  # "complete"
-    print(f"Output: {result2.output}")
-
-asyncio.run(test_confirmation_workflow())
-```
-
----
-
-## Episode 8: MCP Integration
-
-### Exercise 1: Connection Pooling
-Implement connection pooling for MCP servers.
-
-**Solution:**
-```python
-from collections import defaultdict
-
-class MCPConnectionPool:
-    def __init__(self):
-        self._pools: Dict[str, List] = defaultdict(list)
-        self._max_pool_size = 5
-    
-    async def get_connection(self, connection_params: Dict):
-        """Get or create connection from pool."""
-        key = str(connection_params)
-        
-        if self._pools[key]:
-            return self._pools[key].pop()
-        
-        # Create new connection
-        return await self._create_connection(connection_params)
-    
-    async def return_connection(self, connection_params: Dict, connection):
-        """Return connection to pool."""
-        key = str(connection_params)
-        if len(self._pools[key]) < self._max_pool_size:
-            self._pools[key].append(connection)
-```
-
-### Exercise 2: MCP Server Health Check
-Add health check for MCP servers.
-
-**Solution:**
-```python
-async def check_mcp_health(connection: Dict) -> bool:
-    """Check if MCP server is healthy."""
-    try:
-        async with stdio_client(StdioServerParameters(**connection)) as (read, write):
-            async with ClientSession(read, write) as session:
-                await session.initialize()
-                await session.list_tools()
-                return True
-    except Exception:
-        return False
-```
-
----
-
-## Episode 9: Session & Memory Management
-
-### Exercise 1: Build Session Restoration Logic
-Implement the logic to restore session data into ExecutionContext.
-
-**Solution:**
-```python
-async def run(
-    self, 
-    user_input: str, 
-    session_id: Optional[str] = None,
-    context: ExecutionContext = None
-) -> AgentResult:
-    # Load session if provided
-    session = None
-    if session_id and self.session_manager:
-        session = await self.session_manager.get_or_create(session_id)
-        
-        # Restore into context
-        if context is None:
-            context = ExecutionContext()
-            context.events = session.events.copy()
-            context.state = session.state.copy()
-            context.execution_id = session.session_id
-        context.session_id = session_id
-    
-    if context is None:
-        context = ExecutionContext()
-    
-    # ... rest of run logic ...
-```
-
-### Exercise 2: Implement Database Session Manager
-Create a SQLite-backed session manager.
-
-**Solution:**
-```python
-import sqlite3
-import json
-from datetime import datetime
-
-class DatabaseSessionManager(BaseSessionManager):
-    def __init__(self, db_path: str = "sessions.db"):
-        self.db_path = db_path
-        self._init_db()
-    
-    def _init_db(self):
-        conn = sqlite3.connect(self.db_path)
-        conn.execute("""
-            CREATE TABLE IF NOT EXISTS sessions (
-                session_id TEXT PRIMARY KEY,
-                user_id TEXT,
-                events TEXT,
-                state TEXT,
-                created_at TEXT,
-                updated_at TEXT
-            )
-        """)
-        conn.close()
-    
-    async def create(self, session_id: str, user_id: str | None = None) -> Session:
-        session = Session(session_id=session_id, user_id=user_id)
-        await self.save(session)
-        return session
-    
-    async def get(self, session_id: str) -> Session | None:
-        conn = sqlite3.connect(self.db_path)
-        cursor = conn.execute(
-            "SELECT * FROM sessions WHERE session_id = ?",
-            (session_id,)
-        )
-        row = cursor.fetchone()
-        conn.close()
-        
-        if row is None:
-            return None
-        
-        return Session(
-            session_id=row[0],
-            user_id=row[1],
-            events=[Event.model_validate(e) for e in json.loads(row[2])],
-            state=json.loads(row[3]),
-            created_at=datetime.fromisoformat(row[4]),
-            updated_at=datetime.fromisoformat(row[5])
-        )
-    
-    async def save(self, session: Session) -> None:
-        conn = sqlite3.connect(self.db_path)
-        conn.execute("""
-            INSERT OR REPLACE INTO sessions 
-            (session_id, user_id, events, state, created_at, updated_at)
-            VALUES (?, ?, ?, ?, ?, ?)
-        """, (
-            session.session_id,
-            session.user_id,
-            json.dumps([e.model_dump() for e in session.events]),
-            json.dumps(session.state),
-            session.created_at.isoformat(),
-            datetime.now().isoformat()
-        ))
-        conn.commit()
-        conn.close()
-```
-
-### Exercise 3: Session with Pending Tool Calls
-Test that pending tool calls persist across session saves.
-
-**Solution:**
-```python
-async def test_session_with_pending():
-    session_manager = InMemorySessionManager()
-    
-    agent = Agent(
-        model=LlmClient(model="gpt-4o-mini"),
-        tools=[delete_file],  # requires confirmation
-        session_manager=session_manager
-    )
-    
-    session_id = "test-session"
-    
-    # First call - should return pending
-    result1 = await agent.run("Delete test.txt", session_id=session_id)
-    assert result1.status == "pending"
-    
-    # Check session was saved with pending state
-    session = await session_manager.get(session_id)
-    assert "pending_tool_calls" in session.state
-    print(f"Session has {len(session.state['pending_tool_calls'])} pending calls")
-    
-    # Resume with confirmation
-    confirmation = ToolConfirmation(
-        tool_call_id=result1.pending_tool_calls[0].tool_call.tool_call_id,
-        approved=True
-    )
-    
-    result2 = await agent.run("", session_id=session_id, 
-                               tool_confirmations=[confirmation])
-    assert result2.status == "complete"
-    
-    # Check pending was cleared
-    session = await session_manager.get(session_id)
-    assert "pending_tool_calls" not in session.state
-    print("Session pending calls cleared after completion")
-
-asyncio.run(test_session_with_pending())
-```
-
----
-
-## Episode 10: Web Deployment
-
-### Exercise 1: WebSocket Support
-Add WebSocket support for streaming responses.
-
-**Solution:**
-```python
-from fastapi import WebSocket
-
-@app.websocket("/ws/chat")
-async def websocket_chat(websocket: WebSocket):
-    await websocket.accept()
-    
-    agent = create_agent()
-    session_id = None
-    
-    while True:
-        data = await websocket.receive_json()
-        message = data.get("message")
-        
-        if message:
-            result = await agent.run(message, session_id=session_id)
-            session_id = result.context.session_id
-            
-            await websocket.send_json({
-                "type": "response",
-                "content": result.output
-            })
-```
-
-### Exercise 2: Confirmation UI
-Add a UI component for handling tool confirmations.
-
-**Solution:**
-```javascript
-// In index.html
-async function handlePendingToolCalls(pendingCalls) {
-    const modal = document.getElementById('confirmationModal');
-    const content = document.getElementById('confirmationContent');
-    
-    content.innerHTML = pendingCalls.map(pending => `
-        <div class="pending-call" data-id="${pending.tool_call.tool_call_id}">
-            <p>${pending.confirmation_message}</p>
-            <button onclick="approveToolCall('${pending.tool_call.tool_call_id}')">
-                Approve
-            </button>
-            <button onclick="rejectToolCall('${pending.tool_call.tool_call_id}')">
-                Reject
-            </button>
-        </div>
-    `).join('');
-    
-    modal.style.display = 'block';
-}
-
-async function approveToolCall(toolCallId) {
-    const confirmation = {
-        tool_call_id: toolCallId,
-        approved: true
-    };
-    
-    await resumeWithConfirmation([confirmation]);
-}
-
-async function rejectToolCall(toolCallId) {
-    const reason = prompt('Reason for rejection:');
-    const confirmation = {
-        tool_call_id: toolCallId,
-        approved: false,
-        reason: reason
-    };
-    
-    await resumeWithConfirmation([confirmation]);
-}
-```
-
----
-
-## Final Integration Challenge
-
-### Build Complete Agent with All Features
-Create an agent that:
-1. Uses multiple tools (calculator, search, file operations)
-2. Has dangerous tools requiring confirmation
-3. Persists sessions across requests
-4. Displays execution trace
-
-**Solution:**
-```python
-import asyncio
-from agent_framework import (
-    Agent, LlmClient, InMemorySessionManager, 
-    ToolConfirmation, format_trace, tool
-)
-from agent_tools import calculator, search_web
-
-@tool(
-    requires_confirmation=True,
-    confirmation_message="Delete '{arguments[filename]}'?"
-)
-def delete_file(filename: str) -> str:
-    """Delete a file."""
-    return f"Deleted {filename}"
-
-async def main():
-    session_manager = InMemorySessionManager()
-    
-    agent = Agent(
-        model=LlmClient(model="gpt-4o-mini"),
-        tools=[calculator, search_web, delete_file],
-        instructions="You are a helpful assistant with file management capabilities.",
-        session_manager=session_manager
-    )
-    
-    session_id = "demo-session"
-    
-    # Conversation 1: Simple calculation
-    result1 = await agent.run("What is 25 * 17?", session_id=session_id)
-    print(f"Response: {result1.output}\n")
-    
-    # Conversation 2: Try dangerous action
-    result2 = await agent.run("Delete old_data.txt", session_id=session_id)
-    
-    if result2.status == "pending":
-        print("Agent wants to delete a file!")
-        print(f"Message: {result2.pending_tool_calls[0].confirmation_message}")
-        
-        # Approve the deletion
-        confirmation = ToolConfirmation(
-            tool_call_id=result2.pending_tool_calls[0].tool_call.tool_call_id,
-            approved=True
-        )
-        
-        result2 = await agent.run(
-            "", 
-            session_id=session_id,
-            tool_confirmations=[confirmation]
-        )
-    
-    print(f"Response: {result2.output}\n")
-    
-    # Conversation 3: Test memory
-    result3 = await agent.run(
-        "What calculations did I ask about earlier?", 
-        session_id=session_id
-    )
-    print(f"Response: {result3.output}\n")
-    
-    # Display trace
-    print(format_trace(result3.context))
-
-asyncio.run(main())
-```
-
----
-
-## Solutions Location
-
-Solutions can be found in:
-- `misc/tutorials/exercises/solutions/`
-- Each episode has its own solution file
-- Solutions include explanations
-
----
-
-## Contributing Exercises
-
-Feel free to contribute additional exercises:
-1. Fork the repository
-2. Add exercise to appropriate episode section
-3. Include solution
-4. Submit pull request

misc/tutorials/FEATURE_DOCUMENTATION.md

@@ -1,653 +0,0 @@
-# AI Agent Framework: Complete Feature Documentation
-
-## Overview
-
-This document provides a comprehensive inventory of all features implemented in the AI Agent Framework. This framework allows you to build AI agents that can reason, use tools, maintain conversation state, and be deployed as web applications.
-
----
-
-## Core Framework Features
-
-### 1. Agent Execution Engine (`agent_framework/agent.py`)
-
-The `Agent` class is the heart of the framework, orchestrating the entire execution flow.
-
-#### Key Features:
-
-- **Think-Act-Observe Loop**: Multi-step reasoning where the agent thinks (calls LLM), acts (executes tools), and observes (processes results) in a continuous cycle
-- **Structured Output**: Support for Pydantic models as output types, ensuring type-safe responses
-- **Max Steps Control**: Configurable iteration limits to prevent infinite loops
-- **Tool Confirmation**: Optional user approval for tool execution before running
-- **Pending Tool Calls**: Suspend execution and wait for user confirmation when required
-- **Callbacks**: `before_tool_callbacks` and `after_tool_callbacks` for extensibility
-- **Session Integration**: Persistent conversation state across multiple runs
-
-#### Key Methods:
-
-```python
-Agent.__init__(
-    model: LlmClient,
-    tools: List[BaseTool] = None,
-    instructions: str = "",
-    max_steps: int = 5,
-    output_type: Optional[Type[BaseModel]] = None,
-    session_manager: BaseSessionManager | None = None
-)
-
-Agent.run(
-    user_input: str,
-    context: ExecutionContext = None,
-    session_id: Optional[str] = None,
-    tool_confirmations: Optional[List[ToolConfirmation]] = None
-) -> AgentResult
-
-Agent.step(context: ExecutionContext)  # Single iteration
-Agent.think(llm_request: LlmRequest) -> LlmResponse  # LLM call
-Agent.act(context: ExecutionContext, tool_calls: List[ToolCall]) -> List[ToolResult]  # Tool execution
-```
-
----
-
-### 2. Data Models (`agent_framework/models.py`)
-
-All data structures used throughout the framework.
-
-#### Message
-Represents a text message in the conversation.
-
-```python
-class Message(BaseModel):
-    type: Literal["message"] = "message"
-    role: Literal["system", "user", "assistant"]
-    content: str
-```
-
-#### ToolCall
-LLM's request to execute a tool.
-
-```python
-class ToolCall(BaseModel):
-    type: Literal["tool_call"] = "tool_call"
-    tool_call_id: str
-    name: str
-    arguments: dict
-```
-
-#### ToolResult
-Result from tool execution (success or error).
-
-```python
-class ToolResult(BaseModel):
-    type: Literal["tool_result"] = "tool_result"
-    tool_call_id: str
-    name: str
-    status: Literal["success", "error"]
-    content: list
-```
-
-#### Event
-A recorded occurrence during agent execution with timestamp.
-
-```python
-class Event(BaseModel):
-    id: str
-    execution_id: str
-    timestamp: float
-    author: str  # "user" or agent name
-    content: List[ContentItem]
-```
-
-#### ExecutionContext
-Central state container (dataclass) for all execution state.
-
-```python
-@dataclass
-class ExecutionContext:
-    execution_id: str
-    events: List[Event]
-    current_step: int
-    state: Dict[str, Any]
-    final_result: Optional[str | BaseModel]
-    session_id: Optional[str]
-```
-
-#### Session
-Persistent conversation state across multiple `run()` calls.
-
-```python
-class Session(BaseModel):
-    session_id: str
-    user_id: str | None
-    events: list[Event]
-    state: dict[str, Any]
-    created_at: datetime
-    updated_at: datetime
-```
-
-#### Session Management
-- **BaseSessionManager**: Abstract interface for session storage
-- **InMemorySessionManager**: In-memory implementation for development/testing
-
-#### Tool Confirmation
-- **ToolConfirmation**: User's decision on a pending tool call (approved/rejected with optional modifications)
-- **PendingToolCall**: Tool calls awaiting user confirmation
-
----
-
-### 3. LLM Client (`agent_framework/llm.py`)
-
-Unified interface for interacting with LLM APIs.
-
-#### LlmClient
-Multi-provider support via LiteLLM (OpenAI, Anthropic, local models).
-
-```python
-class LlmClient:
-    def __init__(self, model: str, **config)
-    async def generate(self, request: LlmRequest) -> LlmResponse
-```
-
-#### LlmRequest
-Structured request model.
-
-```python
-class LlmRequest(BaseModel):
-    instructions: List[str]
-    contents: List[ContentItem]
-    tools: List[BaseTool]
-    tool_choice: Optional[str]  # "auto", "required", or None
-```
-
-#### LlmResponse
-Structured response model.
-
-```python
-class LlmResponse(BaseModel):
-    content: List[ContentItem]
-    error_message: Optional[str]
-    usage_metadata: Dict[str, Any]
-```
-
-#### build_messages()
-Converts internal models to API message format.
-
-```python
-def build_messages(request: LlmRequest) -> List[dict]
-```
-
----
-
-### 4. Tool System (`agent_framework/tools.py`)
-
-Complete tool abstraction layer.
-
-#### BaseTool
-Abstract base class for all tools.
-
-```python
-class BaseTool(ABC):
-    name: str
-    description: str
-    tool_definition: Dict[str, Any]
-    requires_confirmation: bool
-    async def execute(self, context: ExecutionContext, **kwargs) -> Any
-```
-
-#### FunctionTool
-Wraps Python functions as tools.
-
-```python
-class FunctionTool(BaseTool):
-    def __init__(
-        self,
-        func: Callable,
-        name: str = None,
-        description: str = None,
-        tool_definition: Dict[str, Any] = None,
-        requires_confirmation: bool = False
-    )
-```
-
-#### @tool Decorator
-Syntactic sugar for tool creation.
-
-```python
-@tool
-def my_function(x: int) -> int:
-    """Description for LLM."""
-    return x * 2
-```
-
-#### Features:
-- **Automatic Schema Generation**: From function type hints
-- **Context-Aware Tools**: Optional ExecutionContext parameter
-- **Tool Confirmation**: Per-tool confirmation requirements
-- **Custom Tool Definitions**: Override auto-generated schemas
-
----
-
-### 5. MCP Integration (`agent_framework/mcp.py`)
-
-Integration with Model Context Protocol servers.
-
-#### load_mcp_tools()
-Discovers and loads tools from MCP servers.
-
-```python
-async def load_mcp_tools(connection: Dict) -> List[BaseTool]
-```
-
-#### Features:
-- **MCP Tool Wrapping**: Converts MCP tools to FunctionTool
-- **Stdio Client**: Connects to MCP servers via stdio
-- **Schema Conversion**: MCP schemas to OpenAI format
-
-#### Example:
-```python
-connection = {
-    "command": "npx",
-    "args": ["-y", "tavily-mcp@latest"],
-    "env": {"TAVILY_API_KEY": os.getenv("TAVILY_API_KEY")}
-}
-tools = await load_mcp_tools(connection)
-```
-
----
-
-### 6. Memory Management (`agent_framework/memory.py`)
-
-Token optimization and conversation history management.
-
-#### Token Counting
-Accurate token counting using tiktoken.
-
-```python
-def count_tokens(request: LlmRequest, model_id: str = "gpt-4") -> int
-```
-
-#### Sliding Window
-Keeps only the most recent N messages.
-
-```python
-def apply_sliding_window(
-    context: ExecutionContext,
-    request: LlmRequest,
-    window_size: int = 20
-) -> None
-```
-
-#### Compaction
-Replaces tool calls/results with compact references.
-
-```python
-def apply_compaction(context: ExecutionContext, request: LlmRequest) -> None
-```
-
-#### Summarization
-LLM-based history compression.
-
-```python
-async def apply_summarization(
-    context: ExecutionContext,
-    request: LlmRequest,
-    llm_client: LlmClient,
-    keep_recent: int = 5
-) -> None
-```
-
-#### ContextOptimizer
-Hierarchical optimization strategy.
-
-```python
-class ContextOptimizer:
-    def __init__(
-        self,
-        llm_client: LlmClient,
-        token_threshold: int = 50000,
-        enable_compaction: bool = True,
-        enable_summarization: bool = True
-    )
-```
-
----
-
-### 7. Callbacks (`agent_framework/callbacks.py`)
-
-Extensibility hooks for agent execution.
-
-#### create_optimizer_callback()
-Factory for optimization callbacks.
-
-```python
-def create_optimizer_callback(
-    apply_optimization: Callable,
-    threshold: int = 50000,
-    model_id: str = "gpt-4"
-) -> Callable
-```
-
-#### Features:
-- **Before LLM Callbacks**: Modify requests before API calls
-- **After Tool Callbacks**: Process tool results
-- **Async Support**: Both sync and async callbacks
-
----
-
-### 8. Utilities (`agent_framework/utils.py`)
-
-Helper functions for tool definitions and trace display.
-
-#### Schema Generation
-```python
-function_to_input_schema(func) -> dict
-format_tool_definition(name, description, parameters) -> dict
-function_to_tool_definition(func) -> dict
-```
-
-#### Trace Display
-```python
-format_trace(context: ExecutionContext) -> str
-display_trace(context: ExecutionContext) -> None
-```
-
-#### MCP Conversion
-```python
-mcp_tools_to_openai_format(mcp_tools) -> list[dict]
-```
-
----
-
-## Built-in Tools (`agent_tools/`)
-
-### File Tools (`file_tools.py`)
-
-#### read_file()
-Reads text files (supports .txt, .csv, .json).
-
-```python
-@tool
-def read_file(file_path: str) -> str
-```
-
-#### read_media_file()
-Reads PDFs, Excel files, and images.
-
-```python
-@tool
-def read_media_file(file_path: str) -> str
-```
-
-Supports:
-- PDFs (via pymupdf)
-- Excel files (via pandas/openpyxl)
-- Images (via PIL)
-
-#### list_files()
-Lists directory contents.
-
-```python
-@tool
-def list_files(directory_path: str) -> str
-```
-
-#### unzip_file()
-Extracts zip archives.
-
-```python
-@tool
-def unzip_file(zip_path: str, extract_to: str = None) -> str
-```
-
----
-
-### Web Tools (`web_tools.py`)
-
-#### search_web()
-Tavily API integration for web search.
-
-```python
-@tool
-def search_web(query: str, max_results: int = 5) -> str
-```
-
----
-
-### Math Tools (`math_tools.py`)
-
-#### calculator()
-Safe eval-based calculator.
-
-```python
-@tool
-def calculator(expression: str) -> str
-```
-
----
-
-## Web Application (`web_app/`)
-
-### Backend (`app.py`)
-
-FastAPI server providing RESTful API for agent interaction.
-
-#### Endpoints:
-
-- `GET /`: Serves the chat interface
-- `POST /api/chat`: Send message to agent
-- `POST /api/upload`: Upload files
-- `GET /api/uploads`: List uploaded files
-- `DELETE /api/uploads/{filename}`: Delete uploaded file
-- `GET /api/tools`: List available tools
-- `GET /api/sessions/{session_id}`: Get session info
-- `DELETE /api/sessions/{session_id}`: Clear session
-
-#### Features:
-- **File Upload**: Handle user file uploads
-- **Session Management**: API-based session handling
-- **Tool Listing**: Expose available tools via API
-- **Trace Display**: Return formatted execution traces
-- **CORS Support**: Cross-origin requests enabled
-
----
-
-### Frontend (`static/index.html`)
-
-Modern chat interface with full framework integration.
-
-#### Features:
-- **Chat Interface**: Real-time conversation UI
-- **File Upload UI**: Drag-and-drop file uploads
-- **Tool List Display**: Show available tools in sidebar
-- **Session Toggle**: Enable/disable session persistence
-- **Trace Modal**: View execution traces in formatted view
-- **Session ID Display**: Show current session ID
-- **Clear Session**: Reset conversation state
-- **Responsive Design**: Works on desktop and mobile
-
----
-
-## Additional Features
-
-### GAIA Evaluation (`gaia/`)
-
-Benchmark integration for evaluating agent performance.
-
-- **Problem Loading**: Load GAIA benchmark problems
-- **File Handling**: Download and extract attached files
-- **Evaluation**: Run agent on benchmark problems
-- **Results**: Track accuracy and solvability
-
-### RAG Examples (`rag/`)
-
-Examples of retrieval-augmented generation.
-
-- **Chunking**: Text chunking strategies
-- **Embeddings**: Vector embeddings using OpenAI
-- **Vector Search**: Cosine similarity search
-- **Integration**: Using RAG with agents
-
-### Example Scripts
-
-- **example_agent.py**: Basic agent usage example
-- **test_session.py**: Session persistence demonstration
-
----
-
-## Architecture Overview
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                    User/Application                      │
-└──────────────────────┬────────────────────────────────────┘
-                       │
-                       ▼
-┌─────────────────────────────────────────────────────────┐
-│                      Agent.run()                         │
-│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
-│  │    Think     │→ │     Act      │→ │   Observe    │  │
-│  │  (LLM Call)  │  │ (Tool Exec)  │  │ (Process)    │  │
-│  └──────────────┘  └──────────────┘  └──────────────┘  │
-└──────────────────────┬────────────────────────────────────┘
-                       │
-        ┌──────────────┼──────────────┐
-        ▼              ▼              ▼
-┌─────────────┐ ┌─────────────┐ ┌─────────────┐
-│  LlmClient  │ │   Tools     │ │  Execution  │
-│             │ │             │ │   Context   │
-└─────────────┘ └─────────────┘ └─────────────┘
-        │              │              │
-        ▼              ▼              ▼
-┌─────────────┐ ┌─────────────┐ ┌─────────────┐
-│   LiteLLM   │ │  MCP Tools  │ │   Session   │
-│             │ │             │ │   Manager   │
-└─────────────┘ └─────────────┘ └─────────────┘
-```
-
----
-
-## Usage Examples
-
-### Basic Agent
-
-```python
-from agent_framework import Agent, LlmClient
-from agent_tools import calculator, search_web
-
-agent = Agent(
-    model=LlmClient(model="gpt-4o-mini"),
-    tools=[calculator, search_web],
-    instructions="You are a helpful assistant.",
-    max_steps=10
-)
-
-result = await agent.run("What is 123 * 456?")
-print(result.output)
-```
-
-### Agent with Session
-
-```python
-from agent_framework import Agent, LlmClient, InMemorySessionManager
-
-session_manager = InMemorySessionManager()
-
-agent = Agent(
-    model=LlmClient(model="gpt-4o-mini"),
-    tools=[calculator],
-    session_manager=session_manager
-)
-
-# First conversation
-result1 = await agent.run("My name is Alice", session_id="user-123")
-
-# Second conversation (remembers context)
-result2 = await agent.run("What's my name?", session_id="user-123")
-```
-
-### Agent with Structured Output
-
-```python
-from pydantic import BaseModel
-from typing import Literal
-
-class SentimentAnalysis(BaseModel):
-    sentiment: Literal["positive", "negative", "neutral"]
-    confidence: float
-    key_phrases: list[str]
-
-agent = Agent(
-    model=LlmClient(model="gpt-4o-mini"),
-    tools=[],
-    instructions="Analyze sentiment.",
-    output_type=SentimentAnalysis
-)
-
-result = await agent.run("I love this product!")
-print(result.output.sentiment)  # "positive"
-```
-
-### Agent with Memory Optimization
-
-```python
-from agent_framework import Agent, LlmClient, create_optimizer_callback
-from agent_framework.memory import apply_sliding_window
-
-optimizer = create_optimizer_callback(
-    apply_optimization=apply_sliding_window,
-    threshold=30000
-)
-
-agent = Agent(
-    model=LlmClient(model="gpt-4o-mini"),
-    tools=[calculator],
-    before_llm_callback=optimizer
-)
-```
-
----
-
-## Design Decisions
-
-### Why Pydantic for Models?
-- Runtime validation catches errors early
-- Automatic serialization/deserialization
-- Type safety with IDE support
-
-### Why Dataclass for ExecutionContext?
-- Mutable state needs to be lightweight
-- No validation needed (internal use)
-- Better performance for frequent updates
-
-### Why LiteLLM?
-- Multi-provider support (OpenAI, Anthropic, local)
-- Unified API interface
-- Easy to switch models
-
-### Why MCP?
-- Standard protocol for tool discovery
-- Decouples tool servers from agents
-- Easy integration of external tools
-
----
-
-## Future Enhancements
-
-Potential areas for expansion:
-
-1. **Database Session Manager**: Persistent storage for sessions
-2. **Streaming Responses**: Real-time token streaming
-3. **Multi-Agent Coordination**: Agents working together
-4. **Tool Marketplace**: Discover and share tools
-5. **Advanced Memory**: Vector-based memory retrieval
-6. **Cost Tracking**: Monitor API usage and costs
-7. **Rate Limiting**: Built-in rate limiting
-8. **Monitoring**: Observability and logging
-
----
-
-## Conclusion
-
-This framework provides a complete foundation for building production-ready AI agents. It balances flexibility with structure, allowing you to build simple chatbots or complex multi-agent systems.
-
-For tutorials and examples, see the `misc/tutorials/` directory.
-

misc/tutorials/GITHUB_STRUCTURE.md

@@ -1,342 +0,0 @@
-# GitHub Repository Structure for Tutorial Series
-
-This document outlines the recommended GitHub repository structure for organizing the tutorial series code.
-
----
-
-## Repository Organization
-
-```
-ai-agent-from-scratch/
-├── README.md                          # Main repository README
-├── LICENSE                            # License file
-├── pyproject.toml                     # Project configuration
-├── requirements.txt                   # Python dependencies
-│
-├── agent_framework/                   # Core framework (built in episodes 3-9)
-│   ├── __init__.py
-│   ├── models.py                      # Episode 3
-│   ├── llm.py                         # Episode 4
-│   ├── agent.py                       # Episodes 5, 7
-│   ├── tools.py                       # Episode 6
-│   ├── mcp.py                         # Episode 8
-│   ├── memory.py                      # Episode 9
-│   ├── callbacks.py                   # Episode 9
-│   ├── utils.py
-│   └── README.md
-│
-├── agent_tools/                       # Built-in tools (Episode 6-7)
-│   ├── __init__.py
-│   ├── file_tools.py
-│   ├── web_tools.py
-│   ├── math_tools.py
-│   └── README.md
-│
-├── web_app/                           # Web deployment (Episode 10)
-│   ├── app.py
-│   ├── static/
-│   │   └── index.html
-│   ├── uploads/
-│   └── README.md
-│
-├── examples/                           # Example scripts
-│   ├── example_agent.py
-│   ├── test_session.py
-│   └── README.md
-│
-├── misc/
-│   └── tutorials/                     # Tutorial materials
-│       ├── FEATURE_DOCUMENTATION.md
-│       ├── ARCHITECTURE_DIAGRAMS.md
-│       ├── GITHUB_STRUCTURE.md
-│       ├── EPISODE_01_INTRODUCTION.md
-│       ├── EPISODE_02_LLM_CALL.md
-│       ├── EPISODE_03_DATA_MODELS.md
-│       ├── EPISODE_04_LLM_CLIENT.md
-│       ├── EPISODE_05_AGENT_LOOP.md
-│       ├── EPISODE_06_TOOL_SYSTEM.md
-│       ├── EPISODE_07_TOOL_EXECUTION.md
-│       ├── EPISODE_08_MCP.md
-│       ├── EPISODE_09_MEMORY.md
-│       ├── EPISODE_10_WEB_DEPLOYMENT.md
-│       └── exercises/
-│
-└── .github/
-    └── workflows/                     # CI/CD (optional)
-        └── tests.yml
-```
-
----
-
-## Branch Strategy
-
-### Main Branch
-- `main`: Complete, working codebase
-- Always stable
-- Production-ready
-
-### Episode Branches
-- `episode-1`: Python foundations (concepts only)
-- `episode-2`: LLM client basics
-- `episode-3`: Data models complete
-- `episode-4`: LLM client complete
-- `episode-5`: Basic agent loop
-- `episode-6`: Tool system complete
-- `episode-7`: Complete agent with tools
-- `episode-8`: MCP integration
-- `episode-9`: Memory management
-- `episode-10`: Web deployment
-
-### Feature Branches (Optional)
-- `feature/session-db`: Database session manager
-- `feature/streaming`: Streaming responses
-- `feature/auth`: User authentication
-
----
-
-## Commit Message Convention
-
-Use clear, descriptive commit messages that match episodes:
-
-```
-Episode 3: Add Message, ToolCall, ToolResult models
-Episode 3: Add Event model with timestamp
-Episode 4: Implement LlmClient with LiteLLM
-Episode 4: Add build_messages() function
-Episode 5: Create basic Agent class
-Episode 5: Implement agent.run() method
-Episode 6: Add BaseTool abstract class
-Episode 6: Implement FunctionTool wrapper
-Episode 6: Add @tool decorator
-Episode 7: Implement tool execution in agent
-Episode 7: Add error handling for tools
-Episode 8: Add MCP integration
-Episode 9: Implement session management
-Episode 9: Add memory optimization
-Episode 10: Create FastAPI backend
-Episode 10: Build frontend interface
-```
-
----
-
-## README Structure
-
-### Main README.md
-
-```markdown
-# AI Agent Framework from Scratch
-
-A complete AI agent framework built from scratch, designed for learning and production use.
-
-## Features
-
-- Multi-step reasoning with tools
-- Session persistence
-- Memory optimization
-- MCP integration
-- Web deployment
-
-## Quick Start
-
-\`\`\`bash
-pip install -e .
-python examples/example_agent.py
-\`\`\`
-
-## Tutorial Series
-
-This repository accompanies a 10-part YouTube tutorial series:
-
-1. [Episode 1: Introduction & Python Foundations](./misc/tutorials/EPISODE_01_INTRODUCTION.md)
-2. [Episode 2: Your First LLM Call](./misc/tutorials/EPISODE_02_LLM_CALL.md)
-3. [Episode 3: Core Data Models](./misc/tutorials/EPISODE_03_DATA_MODELS.md)
-4. [Episode 4: The LLM Client](./misc/tutorials/EPISODE_04_LLM_CLIENT.md)
-5. [Episode 5: The Basic Agent Loop](./misc/tutorials/EPISODE_05_AGENT_LOOP.md)
-6. [Episode 6: Building the Tool System](./misc/tutorials/EPISODE_06_TOOL_SYSTEM.md)
-7. [Episode 7: Tool Execution & Complete Agent](./misc/tutorials/EPISODE_07_TOOL_EXECUTION.md)
-8. [Episode 8: MCP Integration](./misc/tutorials/EPISODE_08_MCP.md)
-9. [Episode 9: Session & Memory Management](./misc/tutorials/EPISODE_09_MEMORY.md)
-10. [Episode 10: Web Deployment](./misc/tutorials/EPISODE_10_WEB_DEPLOYMENT.md)
-
-## Documentation
-
-- [Feature Documentation](./misc/tutorials/FEATURE_DOCUMENTATION.md)
-- [Architecture Diagrams](./misc/tutorials/ARCHITECTURE_DIAGRAMS.md)
-
-## Contributing
-
-Contributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
-```
-
----
-
-## Tagging Strategy
-
-Tag releases to match episodes:
-
-```bash
-# Episode milestones
-git tag -a v0.1.0-episode-3 -m "Episode 3: Data Models Complete"
-git tag -a v0.2.0-episode-5 -m "Episode 5: Basic Agent Loop"
-git tag -a v0.3.0-episode-7 -m "Episode 7: Complete Agent"
-git tag -a v1.0.0-episode-10 -m "Episode 10: Full Framework"
-
-# Push tags
-git push origin --tags
-```
-
----
-
-## Issue Templates
-
-### Bug Report Template
-
-```markdown
-**Episode**: [Which episode?]
-**Component**: [agent_framework/agent.py, etc.]
-**Description**: [What's wrong?]
-**Steps to Reproduce**: [How to reproduce]
-**Expected Behavior**: [What should happen]
-**Actual Behavior**: [What actually happens]
-```
-
-### Feature Request Template
-
-```markdown
-**Episode**: [Which episode?]
-**Feature**: [What feature?]
-**Use Case**: [Why is this needed?]
-**Proposed Solution**: [How should it work?]
-```
-
----
-
-## Pull Request Template
-
-```markdown
-## Description
-[What does this PR do?]
-
-## Episode
-[Which episode does this relate to?]
-
-## Changes
-- [ ] Added new feature
-- [ ] Fixed bug
-- [ ] Updated documentation
-- [ ] Added tests
-
-## Testing
-[How was this tested?]
-
-## Checklist
-- [ ] Code follows style guidelines
-- [ ] Tests pass
-- [ ] Documentation updated
-- [ ] Episode branch updated
-```
-
----
-
-## GitHub Actions (Optional)
-
-### CI Workflow
-
-```yaml
-name: Tests
-
-on: [push, pull_request]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
-        with:
-          python-version: '3.11'
-      - run: pip install -e .
-      - run: pip install pytest
-      - run: pytest tests/
-```
-
----
-
-## Documentation Organization
-
-### Episode-Specific Documentation
-
-Each episode branch should include:
-- Code comments explaining decisions
-- Docstrings for all functions/classes
-- Inline comments for complex logic
-- README in relevant directories
-
-### Example: Episode 3 Branch
-
-```
-episode-3/
-├── agent_framework/
-│   ├── models.py          # Well-commented
-│   └── README.md          # Explains models
-└── examples/
-    └── test_models.py     # Example usage
-```
-
----
-
-## File Naming Conventions
-
-- **Python files**: `snake_case.py`
-- **Markdown files**: `UPPER_CASE.md` for episodes, `lowercase.md` for docs
-- **Directories**: `snake_case/`
-- **Tests**: `test_*.py` or `*_test.py`
-
----
-
-## Code Style
-
-- Follow PEP 8
-- Use type hints
-- Document with docstrings
-- Keep functions focused
-- Use meaningful names
-
----
-
-## Release Process
-
-1. Complete episode
-2. Update episode branch
-3. Merge to main
-4. Tag release
-5. Update documentation
-6. Create release notes
-
----
-
-## Community Guidelines
-
-- Be respectful
-- Provide constructive feedback
-- Follow episode structure
-- Test before submitting
-- Document your changes
-
----
-
-## Resources
-
-- [Python Style Guide (PEP 8)](https://peps.python.org/pep-0008/)
-- [Semantic Versioning](https://semver.org/)
-- [Conventional Commits](https://www.conventionalcommits.org/)
-
----
-
-This structure ensures:
-- Clear progression through episodes
-- Easy navigation
-- Good organization
-- Professional presentation
-- Community contribution support
-

misc/tutorials/LANGCHAIN_LANGSERVE_PATTERNS.md

@@ -1,782 +0,0 @@
-# LangChain & LangServe: Advanced Patterns and Nuances
-
-A comprehensive reference for building production-ready agentic systems with LangChain and LangServe.
-
----
-
-## Table of Contents
-
-1. [LangGraph - Stateful Agent Workflows](#1-langgraph---stateful-agent-workflows)
-2. [Agentic RAG Patterns](#2-agentic-rag-patterns)
-3. [Human-in-the-Loop Workflows](#3-human-in-the-loop-workflows)
-4. [Streaming Patterns](#4-streaming-patterns)
-5. [Fallback and Routing Chains](#5-fallback-and-routing-chains)
-6. [Structured Output Patterns](#6-structured-output-patterns)
-7. [Tool Orchestration](#7-tool-orchestration)
-8. [Multi-Agent Patterns](#8-multi-agent-patterns)
-9. [Production Patterns](#9-production-patterns)
-10. [Evaluation Patterns](#10-evaluation-patterns)
-11. [Advanced Memory Patterns](#11-advanced-memory-patterns)
-12. [Advanced Retrieval Patterns](#12-advanced-retrieval-patterns)
-13. [Callbacks and Observability](#13-callbacks-and-observability)
-14. [Dynamic Tool Generation](#14-dynamic-tool-generation)
-15. [Complex Chain Patterns](#15-complex-chain-patterns)
-16. [LangGraph Advanced Patterns](#16-langgraph-advanced-patterns)
-17. [Guardrails and Safety](#17-guardrails-and-safety)
-18. [Advanced Prompting Patterns](#18-advanced-prompting-patterns)
-19. [Testing Patterns](#19-testing-patterns)
-20. [LangServe Deployment Nuances](#20-langserve-deployment-nuances)
-
----
-
-## 1. LangGraph - Stateful Agent Workflows
-
-LangGraph enables complex, stateful workflows with cycles and conditional routing.
-
-### Key Concepts
-- **StateGraph**: Define a graph with typed state that flows between nodes
-- **Nodes**: Functions that process and transform state
-- **Edges**: Connections between nodes (can be conditional)
-- **Cycles**: Loops in the graph for iterative refinement
-- **Checkpointing**: Persist state for resumption
-
-### What to Master
-- State management across nodes
-- Conditional edge routing based on state
-- Implementing cycles for iterative improvement
-- Human-in-the-loop breakpoints
-- State persistence and recovery
-- Subgraphs for modular workflows
-
-### Interview-Worthy Projects
-- Multi-agent research assistant with supervisor coordination
-- Self-correcting RAG with review loop
-- Code generation with test → fix → retry cycles
-
----
-
-## 2. Agentic RAG Patterns
-
-Beyond basic RAG - agents that reason about retrieval.
-
-### Key Patterns
-
-**Self-Correcting RAG**
-- Initial retrieval
-- Generate answer
-- Self-check for hallucinations
-- Re-retrieve with refined query if needed
-
-**Query Transformation**
-- Query expansion (multiple variations)
-- Query decomposition (break into sub-queries)
-- Query refinement based on initial results
-
-**Adaptive Retrieval**
-- Decide when to retrieve vs use knowledge
-- Multi-hop reasoning for complex questions
-- Corrective RAG (re-retrieval on failure)
-
-**HyDE (Hypothetical Document Embeddings)**
-- Generate hypothetical answer first
-- Use it to retrieve similar real documents
-- Better semantic matching
-
-### What to Master
-- When to retrieve vs when to answer directly
-- How to evaluate retrieval quality
-- Multi-step retrieval strategies
-- Combining retrieval with reasoning
-
----
-
-## 3. Human-in-the-Loop Workflows
-
-Real production systems need human oversight.
-
-### Key Patterns
-
-**Interrupts**
-- Pause execution at specific nodes
-- Wait for human approval
-- Resume with modified state if needed
-
-**State Persistence**
-- Save state across sessions
-- Allow humans to review async
-- Resume from any checkpoint
-
-**Approval Workflows**
-- Single approval gates
-- Multi-level approval chains
-- Conditional approval based on risk
-
-**Feedback Incorporation**
-- Collect human corrections
-- Learn from feedback
-- Improve over time
-
-### What to Master
-- Designing breakpoints in workflows
-- State serialization for persistence
-- Multi-turn approval processes
-- Feedback loop architecture
-
----
-
-## 4. Streaming Patterns
-
-Not just streaming text - structured streaming for complex chains.
-
-### Key Patterns
-
-**Event Streaming**
-- Stream events from nested chains
-- Fine-grained control over what to stream
-- Different event types (tool start, LLM chunk, retriever end)
-
-**Progress Updates**
-- Stream status during long operations
-- Partial results as they become available
-- Error events for graceful handling
-
-**Multi-Agent Streaming**
-- Stream from multiple agents simultaneously
-- Coordinate streaming across agents
-- Aggregate and present coherently
-
-### What to Master
-- `astream_events()` for fine-grained control
-- Streaming in multi-agent systems
-- Progress updates during long operations
-- Partial results streaming
-- Error streaming and recovery
-
----
-
-## 5. Fallback and Routing Chains
-
-Build resilient systems with intelligent routing.
-
-### Key Patterns
-
-**Fallback Chains**
-- Primary chain fails → try fallback
-- Multiple fallback levels
-- Graceful degradation
-
-**Semantic Routing**
-- Route based on query meaning
-- Different chains for different intents
-- Dynamic chain selection
-
-**Model Routing**
-- Simple queries → cheap model
-- Complex queries → powerful model
-- Cost-aware routing
-
-**Latency-Based Routing**
-- Fast model for time-sensitive queries
-- Slow model for quality-critical queries
-
-### What to Master
-- Designing fallback hierarchies
-- Semantic similarity for routing
-- Cost vs quality tradeoffs
-- Error handling at each level
-
----
-
-## 6. Structured Output Patterns
-
-Getting reliable, typed outputs from LLMs.
-
-### Key Patterns
-
-**Pydantic Output Parsing**
-- Define schema with Pydantic
-- Parse LLM output into typed objects
-- Validation and error handling
-
-**Nested Structures**
-- Complex nested schemas
-- Lists and optional fields
-- Recursive structures
-
-**Partial Parsing for Streaming**
-- Parse incomplete JSON during streaming
-- Show progress while parsing
-- Handle malformed chunks
-
-**Error Recovery**
-- Retry on parse failure
-- Ask LLM to fix output
-- Fallback to simpler schema
-
-### What to Master
-- Designing robust schemas
-- Handling validation errors
-- Streaming with structured output
-- Combining multiple structured outputs
-
----
-
-## 7. Tool Orchestration
-
-Advanced patterns for tool usage.
-
-### Key Patterns
-
-**Tool Dependencies**
-- Tools that call other tools
-- Sequential tool chains
-- Parallel tool execution
-
-**Conditional Tool Usage**
-- Select tools based on context
-- Skip tools when not needed
-- Dynamic tool availability
-
-**Tool Selection Strategies**
-- Semantic matching to select relevant tools
-- Limit tools based on query type
-- Dynamic tool generation
-
-**Tool Error Handling**
-- Retry failed tools
-- Fallback tools
-- Graceful degradation
-
-### What to Master
-- Designing tool interfaces
-- Managing tool dependencies
-- Error handling and retries
-- Tool result validation
-
----
-
-## 8. Multi-Agent Patterns
-
-Coordinating multiple agents for complex tasks.
-
-### Key Patterns
-
-**Supervisor Pattern**
-- Manager agent coordinates workers
-- Routes tasks to appropriate agents
-- Synthesizes results
-
-**Debate Pattern**
-- Multiple agents discuss/debate
-- Reach consensus
-- Synthesize best answer
-
-**Pipeline Pattern**
-- Sequential agent handoffs
-- Each agent specializes
-- Pass context along
-
-**Hierarchical Teams**
-- Manager decomposes task
-- Workers execute subtasks
-- Manager synthesizes
-
-**Collaborative Agents**
-- Agents work together
-- Shared state
-- Complementary skills
-
-**Competitive Agents**
-- Multiple solutions
-- Evaluate and select best
-- Diverse approaches
-
-### What to Master
-- Agent communication protocols
-- State sharing strategies
-- Conflict resolution
-- Coordination overhead management
-
----
-
-## 9. Production Patterns
-
-Building systems that work in the real world.
-
-### Key Patterns
-
-**Caching**
-- Semantic caching (similar queries → cached result)
-- Exact match caching
-- Cache invalidation strategies
-
-**Rate Limiting**
-- Per-user limits
-- Per-model limits
-- Graceful handling when limited
-
-**Retry Strategies**
-- Exponential backoff
-- Jitter to prevent thundering herd
-- Max retry limits
-
-**Cost Tracking**
-- Token usage per request
-- Cost per user/session
-- Budget enforcement
-
-**Batch Processing**
-- Batch similar requests
-- Efficient API usage
-- Queue management
-
-### What to Master
-- Caching strategies for LLM calls
-- Rate limiting architecture
-- Cost optimization
-- Monitoring and alerting
-
----
-
-## 10. Evaluation Patterns
-
-Measuring and improving agent quality.
-
-### Key Patterns
-
-**LLM-as-Judge**
-- Use LLM to evaluate outputs
-- Define evaluation criteria
-- Score and compare
-
-**Custom Evaluators**
-- Domain-specific metrics
-- Task-specific evaluation
-- Automated scoring
-
-**A/B Testing**
-- Compare different agents
-- Statistical significance
-- User preference tracking
-
-**Regression Testing**
-- Maintain test suite
-- Detect regressions
-- Continuous evaluation
-
-**Human Feedback**
-- Collect user ratings
-- Incorporate corrections
-- Improve over time
-
-### What to Master
-- Designing evaluation criteria
-- Building test datasets
-- Interpreting evaluation results
-- Continuous improvement loops
-
----
-
-## 11. Advanced Memory Patterns
-
-Beyond basic conversation memory.
-
-### Key Patterns
-
-**Cross-Session Memory**
-- Remember across conversations
-- User-specific memory
-- Relevant context retrieval
-
-**Entity Memory**
-- Track entities (people, places, things)
-- Update entity knowledge
-- Retrieve entity context
-
-**Summary + Buffer Hybrid**
-- Recent messages in full
-- Older messages summarized
-- Token-efficient
-
-**Vector Store Memory**
-- All conversations in vector DB
-- Semantic search for relevant context
-- Scalable long-term memory
-
-### What to Master
-- Memory type selection
-- Token budget management
-- Memory persistence
-- Privacy considerations
-
----
-
-## 12. Advanced Retrieval Patterns
-
-Sophisticated retrieval strategies.
-
-### Key Patterns
-
-**Multi-Query Retrieval**
-- Generate multiple query variations
-- Retrieve for all variations
-- Combine results
-
-**Contextual Compression**
-- Retrieve documents
-- Extract only relevant parts
-- Reduce context size
-
-**Parent Document Retrieval**
-- Index small chunks
-- Retrieve full parent documents
-- Best of both worlds
-
-**Ensemble Retrieval**
-- Combine semantic + keyword search
-- Weighted combination
-- Better recall
-
-**Reranking**
-- Initial retrieval
-- Rerank with cross-encoder
-- Better precision
-
-### What to Master
-- Choosing retrieval strategies
-- Combining multiple approaches
-- Evaluating retrieval quality
-- Optimizing for latency vs quality
-
----
-
-## 13. Callbacks and Observability
-
-Understanding what your agents are doing.
-
-### What to Track
-- Token usage (cost)
-- Latency per step
-- Tool execution times
-- Error rates
-- Retrieval quality
-- User satisfaction
-
-### Integration Points
-- LangSmith for tracing
-- Custom logging
-- Metrics systems
-- Alerting
-
-### What to Master
-- Designing callback handlers
-- Async callbacks for non-blocking
-- Aggregating metrics
-- Setting up alerts
-
----
-
-## 14. Dynamic Tool Generation
-
-Tools that create themselves.
-
-### Key Patterns
-
-**API-Based Tools**
-- Generate tools from OpenAPI specs
-- Database schema to tools
-- Dynamic API discovery
-
-**Dynamic Tool Selection**
-- Too many tools → select dynamically
-- Semantic matching to query
-- Limit active tools
-
-**Tool Composition**
-- Combine tools into workflows
-- Meta-tools that orchestrate
-- Adaptive tool creation
-
-### What to Master
-- API spec parsing
-- Dynamic function generation
-- Tool relevance scoring
-- Managing tool explosion
-
----
-
-## 15. Complex Chain Patterns
-
-Advanced chain compositions.
-
-### Key Patterns
-
-**Map-Reduce**
-- Process chunks in parallel (map)
-- Combine results (reduce)
-- Good for large documents
-
-**Refine**
-- Iteratively refine answer
-- Each document improves result
-- Good for synthesis
-
-**Branching**
-- Conditional paths
-- Multiple parallel branches
-- Merge results
-
-### What to Master
-- Choosing the right pattern
-- Handling large inputs
-- Parallel execution
-- Result aggregation
-
----
-
-## 16. LangGraph Advanced Patterns
-
-Deep LangGraph knowledge.
-
-### Key Patterns
-
-**Subgraphs**
-- Nested graphs for modularity
-- Reusable workflow components
-- Clean separation of concerns
-
-**Parallel Execution**
-- Fan out to multiple nodes
-- Process in parallel
-- Fan in to merge
-
-**Time Travel**
-- Replay from any checkpoint
-- Debug by stepping through
-- Modify and replay
-
-**Conditional Cycles**
-- Loop until condition met
-- Self-improvement loops
-- Bounded iteration
-
-### What to Master
-- Graph design patterns
-- State serialization
-- Checkpoint management
-- Debugging complex graphs
-
----
-
-## 17. Guardrails and Safety
-
-Keeping agents safe.
-
-### Key Patterns
-
-**Constitutional AI**
-- Self-critique
-- Revise harmful outputs
-- Principle-based filtering
-
-**Input Validation**
-- Check inputs before processing
-- Reject unsafe requests
-- Log suspicious activity
-
-**Output Filtering**
-- Check outputs before returning
-- Remove sensitive information
-- Ensure policy compliance
-
-**Rate Limiting**
-- Prevent abuse
-- Per-user limits
-- Anomaly detection
-
-### What to Master
-- Designing safety principles
-- Input/output validation
-- PII detection and removal
-- Audit logging
-
----
-
-## 18. Advanced Prompting Patterns
-
-Sophisticated prompt engineering.
-
-### Key Patterns
-
-**Few-Shot Learning**
-- Include examples in prompt
-- Dynamic example selection
-- Semantic similarity for selection
-
-**Chain of Thought**
-- Step-by-step reasoning
-- Show work before answer
-- Better for complex tasks
-
-**Self-Consistency**
-- Generate multiple answers
-- Vote on best
-- Higher reliability
-
-**Role Prompting**
-- Assign specific roles
-- Expert personas
-- Behavior shaping
-
-### What to Master
-- Example selection strategies
-- Prompt templates
-- Dynamic prompt construction
-- Prompt optimization
-
----
-
-## 19. Testing Patterns
-
-Ensuring quality.
-
-### Key Patterns
-
-**Unit Testing**
-- Test individual components
-- Mock LLM responses
-- Fast feedback
-
-**Integration Testing**
-- Test full chains
-- Real LLM calls
-- End-to-end verification
-
-**Regression Testing**
-- Maintain golden dataset
-- Detect quality drops
-- Continuous monitoring
-
-**Load Testing**
-- Test under load
-- Find bottlenecks
-- Capacity planning
-
-### What to Master
-- Mocking LLM calls
-- Test dataset curation
-- Evaluation metrics
-- CI/CD integration
-
----
-
-## 20. LangServe Deployment Nuances
-
-Production deployment details.
-
-### Key Patterns
-
-**Custom Endpoints**
-- Custom input/output schemas
-- Disable playground in production
-- Custom error handling
-
-**Authentication**
-- Middleware for auth
-- Token validation
-- Role-based access
-
-**Batch Endpoints**
-- Automatic batch support
-- Efficient processing
-- Queue management
-
-**Scaling**
-- Horizontal scaling
-- Load balancing
-- Connection pooling
-
-### What to Master
-- FastAPI middleware
-- Authentication patterns
-- Performance tuning
-- Monitoring and logging
-
----
-
-## Key Nuances Summary
-
-| Area | Critical Nuance |
-|------|-----------------|
-| **LangGraph** | State must be serializable; use Pydantic |
-| **Streaming** | Use `astream_events` for fine control |
-| **Memory** | Token counting is crucial for long chats |
-| **RAG** | Chunk size dramatically affects retrieval quality |
-| **Tools** | Too many tools confuses the LLM (keep under 10-15) |
-| **Callbacks** | Use async callbacks for non-blocking |
-| **Caching** | Semantic cache > exact match cache |
-| **Fallbacks** | Order matters; try cheapest/fastest first |
-| **Evaluation** | LLM-as-judge is powerful but needs calibration |
-| **Multi-agent** | Communication overhead can dominate |
-
----
-
-## Interview-Worthy Project Ideas
-
-1. **LangGraph Multi-Agent Research System**
-   - Supervisor coordinates researcher, writer, reviewer agents
-   - Human approval before publishing
-   - Self-correction loop
-
-2. **Self-Correcting RAG System**
-   - Hallucination detection
-   - Automatic re-retrieval
-   - Quality scoring
-
-3. **Production Chatbot**
-   - Memory across sessions
-   - Streaming with progress
-   - Fallback chains
-   - Cost tracking
-
-4. **Code Assistant**
-   - Generate code
-   - Run tests
-   - Fix failures
-   - Iterate until passing
-
-5. **Research Agent**
-   - Web search
-   - Document analysis
-   - Citation tracking
-   - Human-in-the-loop approval
-
----
-
-## What Interviewers Look For
-
-| Question They Ask | What Impresses |
-|-------------------|----------------|
-| "How does it handle failures?" | Fallback chains, retries, graceful degradation |
-| "How do you ensure quality?" | Self-checking, evaluation, human-in-the-loop |
-| "How does it scale?" | Caching, batching, async, connection pooling |
-| "How do agents coordinate?" | LangGraph, state machines, message passing |
-| "How do you monitor it?" | LangSmith, custom callbacks, cost tracking |
-| "How do you test it?" | Unit tests, regression tests, evaluation suites |
-
----
-
-## Learning Path
-
-1. **Start**: Basic chains and prompts
-2. **Add**: Tools and agents
-3. **Upgrade**: RAG with advanced retrieval
-4. **Advanced**: LangGraph for stateful workflows
-5. **Production**: Streaming, caching, monitoring
-6. **Scale**: Multi-agent, human-in-the-loop
-7. **Master**: Evaluation, optimization, safety
-
----
-
-*Last Updated: February 2026*
-

misc/tutorials/NEXT_STEPS.md

@@ -1,442 +0,0 @@
-# Next Steps: Complementary Skills & Learning Path
-
-After building this agent framework from scratch, here's what to learn next to become a complete Agentic AI Engineer.
-
----
-
-## Why This Matters
-
-You've built the fundamentals. But in the real world:
-- Agents need to retrieve knowledge (RAG)
-- Complex tasks need multiple agents
-- Production systems need observability
-- Safety is non-negotiable
-
-This guide helps you add value beyond "I built an agent framework."
-
----
-
-## Priority 1: RAG (Retrieval Augmented Generation)
-
-You have basic embeddings, but production RAG is much deeper.
-
-### Key Concepts
-
-| Concept | Description | Why It Matters |
-|---------|-------------|----------------|
-| **Chunking Strategies** | Fixed-size, semantic, recursive splitting | Affects retrieval quality dramatically |
-| **Hybrid Search** | Combine vector + keyword (BM25) | Better results than vector-only |
-| **Re-ranking** | Cross-encoders to improve top-k | Fixes retriever mistakes |
-| **Vector Databases** | Pinecone, Weaviate, Qdrant, Chroma | Each has different tradeoffs |
-| **Query Transformation** | HyDE, step-back, multi-query | Improve query-document matching |
-| **Agentic RAG** | Agent decides when/what to retrieve | Most flexible approach |
-
-### Add to Your Project
-
-```python
-@tool
-def rag_search(query: str, top_k: int = 5) -> str:
-    """Search knowledge base with hybrid retrieval."""
-    # 1. Vector search
-    vector_results = vector_db.search(embed(query), top_k=top_k*2)
-    
-    # 2. Keyword search (BM25)
-    keyword_results = bm25_search(query, top_k=top_k*2)
-    
-    # 3. Merge and dedupe
-    combined = merge_results(vector_results, keyword_results)
-    
-    # 4. Re-rank with cross-encoder
-    reranked = cross_encoder.rerank(query, combined, top_k=top_k)
-    
-    return format_results(reranked)
-```
-
-### Resources
-- [LlamaIndex](https://docs.llamaindex.ai/) - Best RAG framework
-- [LangChain RAG Tutorial](https://python.langchain.com/docs/tutorials/rag/)
-- Paper: "Retrieval-Augmented Generation for Large Language Models: A Survey"
-
----
-
-## Priority 2: Multi-Agent Systems
-
-Your framework is single-agent. The industry is moving to multi-agent architectures.
-
-### Patterns
-
-| Pattern | Description | Use Case |
-|---------|-------------|----------|
-| **Supervisor** | One agent delegates to specialists | Complex tasks with clear subtasks |
-| **Debate** | Agents argue, synthesize best answer | Reduce hallucination, improve reasoning |
-| **Pipeline** | Agent A -> Agent B -> Agent C | Sequential processing |
-| **Swarm** | Agents coordinate dynamically | Open-ended exploration |
-| **Reflection** | Agent critiques own output | Self-improvement loop |
-
-### Example: Supervisor Pattern
-
-```python
-class SupervisorAgent(Agent):
-    def __init__(self, specialists: List[Agent]):
-        self.specialists = {agent.name: agent for agent in specialists}
-        super().__init__(
-            instructions="""You are a supervisor. 
-            Delegate tasks to specialists:
-            - researcher: for information gathering
-            - coder: for code tasks
-            - writer: for content creation
-            """
-        )
-    
-    async def delegate(self, task: str, specialist_name: str):
-        specialist = self.specialists[specialist_name]
-        return await specialist.run(task)
-```
-
-### Frameworks to Study
-- **LangGraph** - Stateful multi-agent workflows
-- **CrewAI** - Role-based agent teams
-- **AutoGen** - Microsoft's multi-agent framework
-- **Swarm** - OpenAI's experimental framework
-
----
-
-## Priority 3: Observability & Tracing
-
-You have `format_trace`, but production systems need more.
-
-### Tools
-
-| Tool | Type | Best For |
-|------|------|----------|
-| **LangSmith** | SaaS | LangChain users, enterprise |
-| **LangFuse** | Open Source | Self-hosted, privacy-focused |
-| **Weights & Biases** | SaaS | Experiment tracking |
-| **OpenTelemetry** | Standard | Distributed tracing |
-| **Arize Phoenix** | Open Source | LLM observability |
-
-### Key Metrics to Track
-
-```python
-@dataclass
-class AgentMetrics:
-    # Latency
-    total_duration_ms: float
-    llm_call_duration_ms: float
-    tool_execution_duration_ms: float
-    
-    # Token Usage
-    prompt_tokens: int
-    completion_tokens: int
-    total_tokens: int
-    
-    # Cost
-    estimated_cost_usd: float
-    
-    # Quality
-    steps_to_completion: int
-    tool_calls_count: int
-    errors_count: int
-```
-
-### Add to Your Project
-
-```python
-# In agent.py
-class Agent:
-    async def run(self, ...):
-        start_time = time.time()
-        
-        try:
-            result = await self._run_internal(...)
-            
-            # Log metrics
-            self.log_metrics(AgentMetrics(
-                total_duration_ms=(time.time() - start_time) * 1000,
-                steps_to_completion=result.context.current_step,
-                # ... other metrics
-            ))
-            
-            return result
-        except Exception as e:
-            self.log_error(e)
-            raise
-```
-
----
-
-## Priority 4: Evaluation & Benchmarking
-
-You have GAIA. Go deeper with systematic evaluation.
-
-### Evaluation Types
-
-| Type | What It Measures | How |
-|------|------------------|-----|
-| **Task Completion** | Did agent solve the problem? | Binary success/fail |
-| **Accuracy** | Is the answer correct? | Compare to ground truth |
-| **Faithfulness** | Is answer grounded in retrieved context? | LLM-as-Judge |
-| **Relevance** | Is answer relevant to question? | LLM-as-Judge |
-| **Latency** | How fast is the agent? | Time measurement |
-| **Cost** | How much did it cost? | Token tracking |
-
-### LLM-as-Judge Pattern
-
-```python
-JUDGE_PROMPT = """
-You are evaluating an AI agent's response.
-
-Question: {question}
-Agent's Answer: {answer}
-Ground Truth: {ground_truth}
-
-Rate the answer on a scale of 1-5:
-1 = Completely wrong
-2 = Partially wrong
-3 = Partially correct
-4 = Mostly correct
-5 = Completely correct
-
-Provide your rating and reasoning.
-"""
-
-async def evaluate_with_llm(question: str, answer: str, ground_truth: str) -> int:
-    response = await llm.generate(JUDGE_PROMPT.format(...))
-    return extract_rating(response)
-```
-
-### Frameworks
-- **Ragas** - RAG evaluation
-- **DeepEval** - LLM evaluation framework
-- **Promptfoo** - Prompt testing
-- **Evalica** - Comparative evaluation
-
----
-
-## Priority 5: Safety & Guardrails
-
-Production agents need safety layers.
-
-### Input Guardrails
-
-```python
-class InputGuardrails:
-    def __init__(self):
-        self.blocked_patterns = [
-            r"ignore previous instructions",
-            r"you are now",
-            r"pretend to be",
-        ]
-    
-    def check(self, input: str) -> bool:
-        for pattern in self.blocked_patterns:
-            if re.search(pattern, input, re.IGNORECASE):
-                return False
-        return True
-```
-
-### Output Guardrails
-
-```python
-class OutputGuardrails:
-    async def check(self, output: str) -> tuple[bool, str]:
-        # Check for PII
-        if self.contains_pii(output):
-            return False, "Response contains PII"
-        
-        # Check for harmful content
-        if await self.is_harmful(output):
-            return False, "Response contains harmful content"
-        
-        return True, ""
-```
-
-### Integration with Your Framework
-
-```python
-# Add as callbacks
-agent = Agent(
-    model=LlmClient(model="gpt-4o-mini"),
-    tools=[...],
-    before_llm_callback=input_guardrails.check,
-    after_llm_callback=output_guardrails.check,
-)
-```
-
-### Tools
-- **Guardrails AI** - Structured output validation
-- **NeMo Guardrails** - NVIDIA's safety framework
-- **Lakera Guard** - Prompt injection detection
-- **Rebuff** - Self-hardening prompt injection detector
-
----
-
-## Priority 6: LLM Routing & Optimization
-
-### Smart Model Selection
-
-```python
-class ModelRouter:
-    def __init__(self):
-        self.models = {
-            "simple": "gpt-4o-mini",      # Fast, cheap
-            "complex": "gpt-4o",           # Powerful
-            "coding": "claude-sonnet-4-5",    # Best for code
-        }
-    
-    async def route(self, query: str) -> str:
-        # Classify query complexity
-        complexity = await self.classify_complexity(query)
-        
-        if "code" in query.lower():
-            return self.models["coding"]
-        elif complexity == "high":
-            return self.models["complex"]
-        else:
-            return self.models["simple"]
-```
-
-### Semantic Caching
-
-```python
-class SemanticCache:
-    def __init__(self, similarity_threshold: float = 0.95):
-        self.cache = {}
-        self.embeddings = {}
-        self.threshold = similarity_threshold
-    
-    async def get(self, query: str) -> str | None:
-        query_embedding = embed(query)
-        
-        for cached_query, cached_response in self.cache.items():
-            similarity = cosine_similarity(
-                query_embedding, 
-                self.embeddings[cached_query]
-            )
-            if similarity > self.threshold:
-                return cached_response
-        
-        return None
-    
-    async def set(self, query: str, response: str):
-        self.cache[query] = response
-        self.embeddings[query] = embed(query)
-```
-
----
-
-## Suggested Learning Path
-
-### Month 1: RAG Deep Dive
-- [ ] Implement hybrid search (vector + BM25)
-- [ ] Add re-ranking with cross-encoder
-- [ ] Build RAGTool for your agent
-- [ ] Experiment with different chunking strategies
-
-### Month 2: Multi-Agent Systems
-- [ ] Study LangGraph architecture
-- [ ] Implement supervisor pattern
-- [ ] Build debate/reflection agents
-- [ ] Add multi-agent orchestration layer
-
-### Month 3: Production Readiness
-- [ ] Integrate LangFuse for observability
-- [ ] Implement input/output guardrails
-- [ ] Build evaluation suite with LLM-as-Judge
-- [ ] Add cost tracking and alerts
-
-### Month 4: Advanced Topics
-- [ ] Implement smart model routing
-- [ ] Add semantic caching
-- [ ] Experiment with fine-tuning
-- [ ] Build monitoring dashboard
-
----
-
-## Quick Wins to Add Now
-
-These can be added to your framework in a few hours each:
-
-### 1. Semantic Caching
-```python
-# In memory.py
-class SemanticCache:
-    """Cache responses for similar queries."""
-    ...
-```
-
-### 2. Cost Tracker
-```python
-# In agent.py
-PRICING = {
-    "gpt-4o-mini": {"input": 0.15, "output": 0.60},  # per 1M tokens
-    "gpt-4o": {"input": 2.50, "output": 10.00},
-}
-
-def calculate_cost(model: str, input_tokens: int, output_tokens: int) -> float:
-    prices = PRICING.get(model, {"input": 0, "output": 0})
-    return (input_tokens * prices["input"] + output_tokens * prices["output"]) / 1_000_000
-```
-
-### 3. Streaming Support
-```python
-# In llm.py
-async def generate_streaming(self, request: LlmRequest):
-    """Stream tokens as they're generated."""
-    ...
-```
-
-### 4. Simple Guardrails
-```python
-# In callbacks.py
-def prompt_injection_detector(context, request):
-    """Block obvious prompt injection attempts."""
-    ...
-```
-
-### 5. Retry with Exponential Backoff
-```python
-# In llm.py
-async def generate_with_retry(self, request: LlmRequest, max_retries: int = 3):
-    """Retry failed LLM calls with exponential backoff."""
-    ...
-```
-
----
-
-## Resources
-
-### Courses
-- [DeepLearning.AI - Building Agentic RAG with LlamaIndex](https://www.deeplearning.ai/short-courses/building-agentic-rag-with-llamaindex/)
-- [DeepLearning.AI - Multi AI Agent Systems with crewAI](https://www.deeplearning.ai/short-courses/multi-ai-agent-systems-with-crewai/)
-- [LangChain Academy](https://academy.langchain.com/)
-
-### Papers
-- "ReAct: Synergizing Reasoning and Acting in Language Models"
-- "Toolformer: Language Models Can Teach Themselves to Use Tools"
-- "Chain-of-Thought Prompting Elicits Reasoning in Large Language Models"
-- "Retrieval-Augmented Generation for Large Language Models: A Survey"
-
-### Communities
-- [LangChain Discord](https://discord.gg/langchain)
-- [LlamaIndex Discord](https://discord.gg/llamaindex)
-- [Latent Space Podcast](https://www.latent.space/)
-- [AI Engineer Newsletter](https://www.aiengineer.dev/)
-
----
-
-## What Would Make Your Project Stand Out
-
-1. **RAG + Agents** - Agent that retrieves, reasons, and acts
-2. **Multi-Agent Orchestration** - Coordinator + specialists
-3. **Built-in Evaluation** - Self-testing agent framework
-4. **Safety Layer** - Production-grade guardrails
-5. **Observability Dashboard** - Visual trace explorer
-6. **Semantic Caching** - Cost optimization
-7. **Model Routing** - Smart model selection
-
----
-
-**Previous**: [Resume Guide](./RESUME_GUIDE.md)  
-**Back to**: [Tutorial Overview](./README.md)
-

misc/tutorials/README.md

@@ -1,278 +0,0 @@
-# Tutorial Series Materials
-
-This directory contains all materials for the "Building an AI Agent Framework from Scratch" YouTube tutorial series.
-
----
-
-## Documentation
-
-### Core Documentation
-- **[FEATURE_DOCUMENTATION.md](./FEATURE_DOCUMENTATION.md)**: Complete inventory of all framework features
-- **[ARCHITECTURE_DIAGRAMS.md](./ARCHITECTURE_DIAGRAMS.md)**: Visual diagrams using Mermaid syntax
-- **[GITHUB_STRUCTURE.md](./GITHUB_STRUCTURE.md)**: Repository organization and branch strategy
-- **[EXERCISES.md](./EXERCISES.md)**: Exercises and challenges for each episode
-- **[ADDITIONAL_EXERCISES.md](./ADDITIONAL_EXERCISES.md)**: Cross-topic challenges and integration exercises
-
-### Career & Next Steps
-- **[RESUME_GUIDE.md](./RESUME_GUIDE.md)**: How to market this project for AI engineering roles
-- **[NEXT_STEPS.md](./NEXT_STEPS.md)**: Complementary skills & learning path after completion
-
----
-
-## 🎬 Episode Guides
-
-### Episode 1: Introduction & Python Foundations
-**[EPISODE_01_INTRODUCTION.md](./EPISODE_01_INTRODUCTION.md)**
-- Python patterns: Pydantic, dataclasses, async/await
-- Type hints and validation
-- Duration: 30 minutes
-
-### Episode 2: Your First LLM Call
-**[EPISODE_02_LLM_CALL.md](./EPISODE_02_LLM_CALL.md)**
-- Chat completion API format
-- LiteLLM integration
-- Error handling
-- Duration: 25 minutes
-
-### Episode 3: Core Data Models
-**[EPISODE_03_DATA_MODELS.md](./EPISODE_03_DATA_MODELS.md)**
-- Message, ToolCall, ToolResult models
-- Event and ExecutionContext
-- Pydantic vs Dataclass
-- Duration: 30 minutes
-
-### Episode 4: The LLM Client
-**[EPISODE_04_LLM_CLIENT.md](./EPISODE_04_LLM_CLIENT.md)**
-- LlmRequest and LlmResponse models
-- build_messages() function
-- Response parsing
-- Duration: 30 minutes
-
-### Episode 5: The Basic Agent Loop
-**[EPISODE_05_AGENT_LOOP.md](./EPISODE_05_AGENT_LOOP.md)**
-- Think-Act-Observe cycle
-- Agent.run() and Agent.step()
-- Execution tracking
-- Duration: 35 minutes
-
-### Episode 6: Building the Tool System
-**[EPISODE_06_TOOL_SYSTEM.md](./EPISODE_06_TOOL_SYSTEM.md)**
-- BaseTool abstract class
-- FunctionTool wrapper
-- @tool decorator
-- Schema generation
-- Duration: 35 minutes
-
-### Episode 7: Tool Execution & Complete Agent
-**[EPISODE_07_TOOL_EXECUTION.md](./EPISODE_07_TOOL_EXECUTION.md)**
-- Tool execution in agent loop
-- Error handling
-- Complete working agent
-- Duration: 35 minutes
-
-### Episode 8: MCP Integration
-**[EPISODE_08_MCP.md](./EPISODE_08_MCP.md)**
-- Model Context Protocol
-- Tool discovery
-- MCP server integration
-- Duration: 30 minutes
-
-### Episode 9: Session & Memory Management
-**[EPISODE_09_MEMORY.md](./EPISODE_09_MEMORY.md)**
-- Session persistence
-- Token counting
-- Memory optimization strategies
-- Duration: 35 minutes
-
-### Episode 10: Web Deployment
-**[EPISODE_10_WEB_DEPLOYMENT.md](./EPISODE_10_WEB_DEPLOYMENT.md)**
-- FastAPI backend
-- Frontend interface
-- File uploads
-- Session management
-- Duration: 35 minutes
-
----
-
-## 📊 Series Overview
-
-**Total Duration**: ~5.5 hours  
-**Target Audience**: Intermediate Python developers  
-**Teaching Style**: Build from scratch (live coding)  
-**Prerequisites**: Python 3.10+, basic async knowledge
-
----
-
-## 🎯 Learning Path
-
-```
-Episode 1-2: Foundations
-    ↓
-Episode 3-4: Core Components
-    ↓
-Episode 5-7: Agent System
-    ↓
-Episode 8-9: Advanced Features
-    ↓
-Episode 10: Deployment
-```
-
----
-
-## File Structure
-
-```
-misc/tutorials/
-├── README.md (this file)
-│
-├── # Core Documentation
-├── FEATURE_DOCUMENTATION.md
-├── ARCHITECTURE_DIAGRAMS.md
-├── GITHUB_STRUCTURE.md
-│
-├── # Exercises
-├── EXERCISES.md
-├── ADDITIONAL_EXERCISES.md
-│
-├── # Career & Learning
-├── RESUME_GUIDE.md
-├── NEXT_STEPS.md
-│
-├── # Episode Guides
-├── EPISODE_01_INTRODUCTION.md
-├── EPISODE_02_LLM_CALL.md
-├── EPISODE_03_DATA_MODELS.md
-├── EPISODE_04_LLM_CLIENT.md
-├── EPISODE_05_AGENT_LOOP.md
-├── EPISODE_06_TOOL_SYSTEM.md
-├── EPISODE_07_TOOL_EXECUTION.md
-├── EPISODE_08_MCP.md
-├── EPISODE_09_MEMORY.md
-└── EPISODE_10_WEB_DEPLOYMENT.md
-```
-
----
-
-## 🚀 Quick Start
-
-1. **Read the Feature Documentation** to understand what we're building
-2. **Follow episodes in order** - each builds on the previous
-3. **Complete exercises** after each episode
-4. **Check GitHub branches** for episode-specific code
-
----
-
-## 💡 Tips for Teaching
-
-### For Each Episode:
-1. **Hook** (2 min): Show what we'll build
-2. **Problem** (3 min): Why do we need this?
-3. **Concept** (5 min): How does it work?
-4. **Live Coding** (15-20 min): Build it step by step
-5. **Demo** (3 min): Show it working
-6. **Next Steps** (2 min): Preview next episode
-
-### Visual Aids:
-- Use architecture diagrams from `ARCHITECTURE_DIAGRAMS.md`
-- Show code side-by-side with explanations
-- Use terminal output to show execution
-- Display execution traces
-
-### Engagement:
-- Ask rhetorical questions
-- Show "what if" scenarios
-- Compare with alternatives
-- Highlight design decisions
-- Show common mistakes
-
----
-
-## 📝 Episode Checklist
-
-Before recording each episode:
-
-- [ ] Review episode outline
-- [ ] Prepare code examples
-- [ ] Set up development environment
-- [ ] Test all code snippets
-- [ ] Prepare visual aids
-- [ ] Review architecture diagrams
-- [ ] Prepare exercises
-- [ ] Check GitHub branch
-
----
-
-## 🎬 Recording Tips
-
-1. **Start fresh**: Begin each episode with clean files
-2. **Build incrementally**: Test after each major component
-3. **Show errors**: Demonstrate common mistakes and fixes
-4. **Explain decisions**: Why this approach vs alternatives
-5. **Keep it real**: Show actual debugging process
-6. **Engage audience**: Ask questions, pause for thought
-
----
-
-## 📚 Additional Resources
-
-- [Pydantic Documentation](https://docs.pydantic.dev/)
-- [LiteLLM Documentation](https://docs.litellm.ai/)
-- [FastAPI Documentation](https://fastapi.tiangolo.com/)
-- [MCP Specification](https://modelcontextprotocol.io/)
-
----
-
-## 🤝 Contributing
-
-Found an error or want to improve the tutorials?
-
-1. Fork the repository
-2. Make your changes
-3. Submit a pull request
-4. Include explanation of changes
-
----
-
-## 📧 Support
-
-Questions or issues?
-- Open a GitHub issue
-- Check existing documentation
-- Review episode-specific guides
-
----
-
-## Series Completion
-
-After completing all 10 episodes, you will have:
-
-- Built a complete AI agent framework  
-- Understand every component  
-- Created production-ready code  
-- Deployed a web application  
-- Gained deep understanding of agent architecture
-
-**Congratulations on your learning journey!**
-
-### What's Next?
-
-Check out **[NEXT_STEPS.md](./NEXT_STEPS.md)** for:
-- RAG (Retrieval Augmented Generation)
-- Multi-Agent Systems
-- Observability & Tracing
-- Evaluation & Benchmarking
-- Safety & Guardrails
-- LLM Routing & Optimization
-
-### Career Guidance
-
-See **[RESUME_GUIDE.md](./RESUME_GUIDE.md)** for:
-- How to market this project
-- Resume bullet points (STAR method)
-- Interview talking points
-- Portfolio presentation tips
-
----
-
-*Last Updated: 2026*
-

misc/tutorials/RESUME_GUIDE.md

@@ -1,719 +0,0 @@
-# Resume & Interview Guide: Marketing Your Agent Framework
-
-This guide helps you present your AI Agent Framework project effectively for agentic AI engineer roles at top labs (OpenAI, Anthropic, Google DeepMind, etc.).
-
----
-
-## 🎯 Why This Project is Valuable
-
-**This project demonstrates:**
-- ✅ Deep understanding of agent architectures (not just using frameworks)
-- ✅ Ability to build production systems from scratch
-- ✅ Knowledge of core concepts: tool use, memory, sessions, reasoning loops
-- ✅ Full-stack capabilities (backend + frontend + deployment)
-- ✅ Understanding of optimization and scalability
-- ✅ Teaching ability (YouTube series shows communication skills)
-
-**Big labs value:**
-- People who understand internals, not just APIs
-- Ability to build from first principles
-- Production engineering mindset
-- Teaching/communication skills
-
----
-
-## 📝 Resume Project Description
-
-### Option 1: Concise Version (2-3 lines)
-
-```
-AI Agent Framework | Python, FastAPI, LLMs
-Built a production-ready agent framework from scratch implementing multi-step reasoning, 
-tool execution, session management, and memory optimization. Features include MCP integration, 
-token-aware context optimization, and web deployment. Created comprehensive 10-part tutorial 
-series teaching the architecture.
-```
-
-### Option 2: Detailed Version (Bullet Points)
-
-```
-AI Agent Framework - From Scratch Implementation
-• Architected and built a complete agent framework implementing Think-Act-Observe reasoning 
-  loop with tool execution, supporting OpenAI, Anthropic, and local models via LiteLLM
-• Designed extensible tool system with automatic schema generation, MCP protocol integration, 
-  and user confirmation workflows for production safety
-• Implemented session persistence and memory optimization strategies (sliding window, 
-  compaction, summarization) reducing token costs by 60%+ in long conversations
-• Built FastAPI backend with real-time chat interface, file upload handling, and execution 
-  trace visualization for debugging and monitoring
-• Created comprehensive 10-part YouTube tutorial series (5.5 hours) teaching agent architecture 
-  from first principles, demonstrating technical communication skills
-• Technologies: Python, Pydantic, AsyncIO, FastAPI, LiteLLM, MCP, tiktoken, React/HTML/CSS
-```
-
-### Option 3: Skills-Focused Version
-
-```
-AI Agent Framework | Agentic AI | Full-Stack
-Built end-to-end agent framework demonstrating expertise in:
-• Agent Architecture: Multi-step reasoning, tool orchestration, execution loops
-• LLM Integration: Multi-provider support, structured output, streaming
-• Memory Management: Token optimization, context compression, session persistence  
-• Production Engineering: Error handling, monitoring, deployment, scalability
-• Technical Communication: Created educational content reaching 1000+ developers
-```
-
----
-
-## 🎯 Key Skills to Highlight
-
-### Technical Skills (Match Job Descriptions)
-
-**Core Agent Concepts:**
-- Multi-step reasoning and planning
-- Tool use and function calling
-- Agent execution loops
-- Context management
-- Memory optimization
-
-**LLM Integration:**
-- Multi-provider support (OpenAI, Anthropic, local)
-- Structured output (Pydantic)
-- Token management
-- Streaming responses
-- Error handling
-
-**System Design:**
-- Extensible architecture
-- Plugin system (tools)
-- Session management
-- State persistence
-- API design
-
-**Production Engineering:**
-- Performance optimization
-- Cost management
-- Monitoring and debugging
-- Web deployment
-- Scalability considerations
-
-**Communication:**
-- Technical writing
-- Teaching complex concepts
-- Documentation
-- Code organization
-
----
-
-## 💼 Resume Bullet Points by Role
-
-### For Research Roles (OpenAI, Anthropic Research)
-
-```
-• Implemented agent reasoning loop from first principles, demonstrating understanding of 
-  core agentic AI concepts including tool use, memory, and multi-step planning
-• Designed and evaluated memory optimization strategies (sliding window, compaction, 
-  summarization) with quantitative analysis of token reduction and context retention
-• Built extensible framework supporting multiple LLM providers and tool protocols (MCP), 
-  enabling research into cross-provider agent behavior
-• Created educational content teaching agent architecture, contributing to open-source 
-  knowledge and demonstrating ability to communicate complex research concepts
-```
-
-### For Engineering Roles (Applied AI Teams)
-
-```
-• Architected production-ready agent framework handling 1000+ concurrent sessions with 
-  session persistence, error recovery, and cost optimization
-• Implemented tool system with automatic schema generation, user confirmation workflows, 
-  and MCP integration for extensibility
-• Built FastAPI backend with real-time chat, file processing, and execution tracing, 
-  demonstrating full-stack capabilities
-• Optimized token usage by 60%+ through intelligent context management while maintaining 
-  conversation quality
-• Deployed scalable web application with monitoring, logging, and error tracking for 
-  production use
-```
-
-### For Infrastructure Roles (Platform Teams)
-
-```
-• Designed extensible agent framework architecture supporting plugin-based tool system, 
-  multiple LLM providers, and custom memory strategies
-• Implemented session management system with in-memory and database backends, supporting 
-  horizontal scaling
-• Built monitoring and debugging tools including execution trace visualization and 
-  token usage analytics
-• Created comprehensive documentation and tutorial series demonstrating system architecture 
-  and design decisions
-• Optimized system performance through async operations, connection pooling, and intelligent 
-  caching strategies
-```
-
----
-
-## 🎤 Interview Talking Points
-
-### "Tell me about this project"
-
-**Structure:**
-1. **Problem**: "I wanted to deeply understand how agent frameworks work, so I built one from scratch"
-2. **Architecture**: "I implemented the core components: reasoning loop, tool system, memory management"
-3. **Challenges**: "Key challenges were token optimization, session persistence, and tool execution safety"
-4. **Results**: "Built a production-ready system with 60%+ token reduction and comprehensive tool support"
-5. **Learning**: "Created a tutorial series teaching others, which deepened my own understanding"
-
-### Key Technical Details to Mention
-
-**Agent Architecture:**
-- "I implemented a Think-Act-Observe loop where the agent reasons, executes tools, and processes results iteratively"
-- "The ExecutionContext tracks all state, allowing for debugging and session persistence"
-- "I designed an extensible tool system where any Python function can become a tool with automatic schema generation"
-
-**Memory Optimization:**
-- "I implemented three strategies: sliding window for speed, compaction for tool-heavy conversations, and summarization for very long contexts"
-- "Token counting using tiktoken allows optimization to trigger automatically when thresholds are exceeded"
-- "This reduced costs by 60%+ while maintaining conversation quality"
-
-**Production Considerations:**
-- "Error handling at every layer: LLM calls, tool execution, session management"
-- "Session persistence allows conversations to span multiple requests"
-- "Web deployment with FastAPI demonstrates full-stack capabilities"
-
----
-
-## 🎯 Alignment with Big Lab Priorities
-
-### What OpenAI/Anthropic Look For:
-
-**✅ You Have:**
-- Deep understanding of agent internals (not just API usage)
-- Ability to build from first principles
-- Production engineering mindset
-- Teaching/communication ability
-- Full-stack capabilities
-
-**Highlight:**
-- "Built framework from scratch to understand internals"
-- "Implemented memory optimization reducing costs"
-- "Created educational content"
-- "Production-ready deployment"
-
-### What Google DeepMind Looks For:
-
-**✅ You Have:**
-- Research-oriented thinking
-- System design skills
-- Ability to explain complex concepts
-- Open-source contribution mindset
-
-**Highlight:**
-- "Designed extensible architecture"
-- "Evaluated optimization strategies"
-- "Open-source tutorial series"
-- "First-principles implementation"
-
----
-
-## 📊 Quantifiable Achievements
-
-**Add numbers where possible:**
-
-- "Reduced token costs by 60%+ through optimization"
-- "Built framework supporting 10+ tool types"
-- "Created 10-part tutorial series (5.5 hours)"
-- "Implemented 3 memory optimization strategies"
-- "Supports 3+ LLM providers"
-- "Web app handles file uploads, real-time chat, session management"
-- "Framework used in [X] projects" (if applicable)
-
----
-
-## 🔗 GitHub & Portfolio Presentation
-
-### GitHub Repository
-
-**README should highlight:**
-- Clear problem statement
-- Architecture overview
-- Key features
-- Production considerations
-- Tutorial series link
-
-**Code Quality:**
-- Clean, well-documented code
-- Type hints throughout
-- Comprehensive docstrings
-- Example scripts
-- Tests (if you add them)
-
-### Portfolio Website
-
-**Include:**
-- Project overview
-- Architecture diagrams
-- Key features demo
-- Link to tutorial series
-- Technical blog post (optional)
-
----
-
-## 🎓 Interview Preparation
-
-### Technical Questions They Might Ask
-
-**"How does your agent handle tool execution errors?"**
-- Explain error handling in `act()` method
-- ToolResult with error status
-- Agent continues reasoning with error context
-
-**"How do you optimize for long conversations?"**
-- Three strategies: sliding window, compaction, summarization
-- Token counting triggers optimization
-- Trade-offs between strategies
-
-**"How would you scale this to millions of users?"**
-- Database session manager
-- Load balancing
-- Caching strategies
-- Async operations
-- Resource pooling
-
-**"What would you change if rebuilding?"**
-- Streaming support
-- WebSocket communication
-- Database sessions
-- Advanced monitoring
-- Multi-agent support
-
-### System Design Questions
-
-**"Design an agent system for [use case]"**
-- Use your framework as foundation
-- Show understanding of requirements
-- Design tool set
-- Consider scalability
-- Address edge cases
-
----
-
-## 🚀 Making It Stand Out
-
-### Unique Selling Points
-
-1. **Built from Scratch**: Not using LangChain/other frameworks - shows deep understanding
-2. **Production-Ready**: Not just a prototype - has deployment, optimization, error handling
-3. **Educational Content**: Tutorial series shows teaching ability (valuable in research roles)
-4. **Full-Stack**: Backend + frontend + deployment shows versatility
-5. **Well-Documented**: Comprehensive docs show professional standards
-
-### Additional Enhancements (Optional)
-
-**To make it even stronger:**
-- Add comprehensive test suite
-- Deploy to production (AWS/GCP)
-- Add monitoring (Grafana, Prometheus)
-- Write technical blog posts
-- Contribute to open-source agent projects
-- Add more advanced features (streaming, WebSocket)
-
----
-
-## 📝 Cover Letter Snippet
-
-```
-I recently built an AI agent framework from scratch to deepen my understanding of agentic AI 
-architectures. The project implements core concepts including multi-step reasoning, tool 
-execution, memory optimization, and session management. I also created a comprehensive 
-10-part tutorial series teaching the architecture, demonstrating my ability to communicate 
-complex technical concepts.
-
-This project aligns with [Company]'s work on [specific project/area] because [connection]. 
-I'm particularly interested in [specific aspect] and would love to contribute to [team/project].
-```
-
----
-
-## 🎯 Role-Specific Tailoring
-
-### For OpenAI (GPT-4, Function Calling Team)
-- Emphasize: Tool use, function calling, structured output
-- Mention: Understanding of their API design
-- Highlight: Production tool execution patterns
-
-### For Anthropic (Claude, Tool Use)
-- Emphasize: Multi-step reasoning, safety (confirmation system)
-- Mention: Understanding of their approach
-- Highlight: Memory optimization strategies
-
-### For Google DeepMind (Gemini, Agent Research)
-- Emphasize: Research-oriented thinking, system design
-- Mention: Open-source contribution
-- Highlight: Educational content creation
-
----
-
-## ✅ Final Checklist
-
-Before applying:
-
-- [ ] GitHub repo is clean and well-documented
-- [ ] README clearly explains the project
-- [ ] Code has type hints and docstrings
-- [ ] Resume bullet points are quantified
-- [ ] Can explain architecture in 2 minutes
-- [ ] Can discuss design decisions
-- [ ] Can answer "what would you change?" question
-- [ ] Tutorial series is accessible
-- [ ] Portfolio/website is updated (if you have one)
-
----
-
-## 💡 Pro Tips
-
-1. **Be Specific**: Don't say "built an agent" - say "built agent framework with tool execution and memory optimization"
-
-2. **Show Impact**: Quantify results (token reduction, features, tutorial views)
-
-3. **Demonstrate Learning**: Mention what you learned and how it changed your thinking
-
-4. **Connect to Role**: Research their work and connect your project to their needs
-
-5. **Be Honest**: Acknowledge limitations and what you'd improve
-
-6. **Show Growth**: This project shows you can learn and build complex systems
-
----
-
-## 🎓 This Project is Definitely Useful!
-
-**Why:**
-- ✅ Shows deep understanding (not just API usage)
-- ✅ Demonstrates production engineering skills
-- ✅ Proves you can build from first principles
-- ✅ Shows teaching/communication ability
-- ✅ Demonstrates full-stack capabilities
-- ✅ Aligns with what big labs value
-
-**Big labs hire people who:**
-- Understand internals deeply
-- Can build production systems
-- Can communicate complex ideas
-- Think from first principles
-- Have engineering rigor
-
-**Your project demonstrates all of these!**
-
----
-
-## Positioning as an End-to-End Agentic AI Architect
-
-If you want to project yourself as someone who can **architect any type of agentic system for any use case**, you need to demonstrate breadth, depth, and system design thinking.
-
-### Target Positioning
-
-**Current**: "I built an agent framework from scratch"
-
-**Target**: "I architect end-to-end agentic systems - from requirements to production. I've implemented 8+ agent patterns across 10+ domains, with expertise in multi-agent orchestration, RAG integration, and human-in-the-loop safety."
-
----
-
-## Architecture Patterns You Should Master
-
-| Pattern | Description | Use Case | Your Framework |
-|---------|-------------|----------|----------------|
-| **Single Agent** | One agent with tools | Simple tasks, chatbots | Implemented |
-| **Human-in-the-Loop** | Confirmation workflow | Dangerous operations | Implemented |
-| **Supervisor + Specialists** | Coordinator delegates | Complex multi-domain tasks | To add |
-| **Pipeline/Chain** | Sequential agents | Document processing | To add |
-| **Debate/Critique** | Agents challenge each other | High-stakes decisions | To add |
-| **Reflection** | Self-critique loop | Code generation, writing | To add |
-| **Hierarchical** | Multi-level delegation | Enterprise workflows | To add |
-| **Swarm** | Dynamic collaboration | Research, exploration | To add |
-
-### Add These to Your Portfolio
-
-```
-examples/
-├── single_agent/          # What you have
-├── supervisor_agent/      # Coordinator + specialists
-├── pipeline_agent/        # Sequential processing
-├── reflection_agent/      # Self-critique loop
-└── rag_agent/            # Retrieval-augmented
-```
-
----
-
-## Domain Portfolio to Build
-
-Show you can build agents for ANY use case:
-
-| Domain | Agent Type | Key Features |
-|--------|-----------|--------------|
-| **Customer Support** | RAG + Tools | Knowledge base, ticket creation, escalation |
-| **Code Assistant** | Code Gen + Execution | Sandbox execution, testing, debugging |
-| **Research Agent** | Multi-source RAG | Web search, paper analysis, synthesis |
-| **Data Analyst** | SQL + Visualization | Query generation, chart creation |
-| **Content Creator** | Writing + Review | Draft, edit, SEO optimization |
-| **DevOps Agent** | Monitoring + Actions | Alert analysis, auto-remediation |
-| **Sales Agent** | CRM + Email | Lead scoring, outreach, follow-up |
-| **Legal/Compliance** | Document Analysis | Contract review, risk flagging |
-
-### Add Use Case Demos
-
-```
-demos/
-├── customer_support/      # RAG + ticket tools
-├── code_assistant/        # Code execution sandbox
-├── research_agent/        # Multi-source research
-└── data_analyst/          # SQL + visualization
-```
-
----
-
-## Skills to Demonstrate as an Architect
-
-### Technical Architecture
-- **Scalability**: How to handle 1000+ concurrent agent sessions
-- **Reliability**: Retry logic, fallbacks, graceful degradation
-- **Observability**: Tracing, metrics, debugging
-- **Security**: Guardrails, sandboxing, access control
-- **Cost Optimization**: Caching, routing, batching
-
-### System Design Expertise
-- When to use agents vs. deterministic code
-- Choosing between single vs. multi-agent
-- Tool design principles
-- Memory strategies for different use cases
-- Evaluation and testing strategies
-
-### Architecture Decision Records
-
-Add these to your docs:
-```
-docs/
-├── ADR_001_single_vs_multi_agent.md
-├── ADR_002_memory_strategies.md
-├── ADR_003_tool_confirmation.md
-└── ADR_004_session_management.md
-```
-
----
-
-## How to Present Yourself
-
-### Resume Headline
-```
-Agentic AI Architect | End-to-End Agent Systems | LLM Infrastructure
-```
-
-### LinkedIn Summary
-```
-I design and build production-grade AI agent systems from scratch. My expertise 
-spans single-agent assistants to complex multi-agent orchestration, with deep 
-knowledge of tool integration, memory management, and human-in-the-loop safety 
-patterns.
-
-I've architected agent frameworks covering 8+ architecture patterns across 10+ 
-use case domains - from customer support to code generation to research automation.
-
-"Give me any business problem, and I'll architect an agent system to solve it - 
-from requirements to production deployment."
-```
-
-### Portfolio Statement
-```
-"I don't just use agent frameworks - I build them. I understand every layer from 
-LLM API calls to production deployment, and I can architect solutions for any 
-domain."
-```
-
----
-
-## Interview Strategy: "How Would You Build X?"
-
-When asked about designing an agent system, structure your answer:
-
-### Framework (use consistently)
-
-1. **Requirements Analysis**
-   - "First, I'd clarify the task complexity, latency needs, and safety requirements..."
-   - "What are the input/output formats? What tools are needed?"
-
-2. **Architecture Selection**
-   - "For this use case, I'd choose a [pattern] because..."
-   - "Single agent if simple, supervisor pattern if multi-domain..."
-
-3. **Component Design**
-   - "The key components would be: agent loop, tools, memory, guardrails..."
-   - "For tools, I'd implement [specific tools] with these schemas..."
-
-4. **Trade-off Analysis**
-   - "The main trade-offs are cost vs latency, accuracy vs speed..."
-   - "For this use case, I'd prioritize [X] over [Y] because..."
-
-5. **Production Considerations**
-   - "To make this production-ready, I'd add monitoring, error handling..."
-   - "For scaling, I'd implement caching, async operations, load balancing..."
-
-### Example Answers
-
-**"Design a customer support agent"**
-```
-"I'd use a single-agent RAG architecture with these components:
-1. Knowledge base tool with hybrid search (vector + BM25)
-2. Ticket creation tool for escalation
-3. CRM lookup tool for customer context
-4. Session management for conversation continuity
-5. Guardrails to prevent sharing sensitive data
-
-The agent loop would: retrieve context, generate response, escalate if needed.
-For production, I'd add response caching, rate limiting, and quality monitoring."
-```
-
-**"Design a code review agent"**
-```
-"I'd use a reflection pattern - agent critiques its own analysis:
-1. First pass: identify issues (security, style, bugs)
-2. Self-critique: 'Are these issues valid? Did I miss anything?'
-3. Final pass: prioritize and format feedback
-
-Tools: file reader, AST parser, security scanner, style checker.
-I'd add sandboxed execution to verify fixes actually work."
-```
-
-**"Design a multi-agent research system"**
-```
-"I'd use a supervisor pattern:
-1. Coordinator agent: plans research, assigns tasks
-2. Search specialist: web and academic search
-3. Analysis specialist: summarizes and synthesizes
-4. Writing specialist: produces final report
-
-The supervisor tracks progress and handles failures.
-Key challenge: ensuring specialists share context efficiently."
-```
-
----
-
-## Credentials to Build Authority
-
-| Credential | How to Get It | Priority |
-|------------|--------------|----------|
-| **GitHub Stars** | Share on Twitter/LinkedIn, make repo useful | High |
-| **Technical Blog** | Write about architecture decisions | High |
-| **YouTube Series** | Your tutorial series | Done! |
-| **Open Source Contributions** | Contribute to LangChain, LlamaIndex, CrewAI | Medium |
-| **Conference Talks** | Apply to AI meetups, conferences | Medium |
-| **Certifications** | DeepLearning.AI courses | Low |
-
----
-
-## Architecture Examples to Add
-
-### Supervisor Pattern Example
-
-```python
-class SupervisorAgent(Agent):
-    """Coordinator that delegates to specialist agents."""
-    
-    def __init__(self, specialists: List[Agent]):
-        self.specialists = {agent.name: agent for agent in specialists}
-        super().__init__(
-            instructions="""You are a supervisor coordinating specialists:
-            - researcher: for information gathering
-            - coder: for code tasks  
-            - writer: for content creation
-            
-            Analyze tasks and delegate appropriately."""
-        )
-    
-    @tool
-    async def delegate(self, task: str, specialist: str) -> str:
-        """Delegate a task to a specialist agent."""
-        agent = self.specialists.get(specialist)
-        if not agent:
-            return f"Unknown specialist: {specialist}"
-        result = await agent.run(task)
-        return result.output
-```
-
-### Reflection Pattern Example
-
-```python
-class ReflectionAgent(Agent):
-    """Agent that critiques and improves its own output."""
-    
-    async def run_with_reflection(self, task: str, max_reflections: int = 2):
-        # Initial attempt
-        result = await self.run(task)
-        
-        for i in range(max_reflections):
-            # Self-critique
-            critique = await self.run(f"""
-            Review this output and identify issues:
-            {result.output}
-            
-            What could be improved? Be specific.
-            """)
-            
-            # Check if good enough
-            if "no issues" in critique.output.lower():
-                break
-            
-            # Improve based on critique
-            result = await self.run(f"""
-            Original task: {task}
-            Previous attempt: {result.output}
-            Critique: {critique.output}
-            
-            Now provide an improved version.
-            """)
-        
-        return result
-```
-
----
-
-## Quick Wins to Strengthen Your Position
-
-1. **Add architecture diagrams** for each pattern
-2. **Create use case READMEs** explaining design decisions
-3. **Write ADRs** (Architecture Decision Records)
-4. **Add benchmarks** comparing patterns
-5. **Create a "pattern selector" tool** that recommends patterns based on requirements
-
----
-
-## Summary: Your Positioning Statement
-
-```
-"As an Agentic AI Architect, I design and build end-to-end agent systems 
-for any business problem. My expertise includes:
-
-- 8+ agent architecture patterns (single, supervisor, pipeline, reflection, etc.)
-- 10+ domain applications (support, code, research, data analysis, etc.)
-- Production systems with safety, scalability, and observability
-- From-scratch implementation demonstrating deep understanding
-
-I don't just use frameworks - I understand every layer and can architect 
-the right solution for any use case."
-```
-
----
-
-## Next Steps
-
-1. **Polish GitHub**: Clean code, great README, examples
-2. **Update Resume**: Use bullet points from this guide
-3. **Add Architecture Examples**: Supervisor, Pipeline, Reflection patterns
-4. **Add Use Case Demos**: Customer support, code assistant, research agent
-5. **Write ADRs**: Document your design decisions
-6. **Prepare Stories**: Practice explaining architectures
-7. **Research Labs**: Understand their specific work
-8. **Apply Confidently**: This is a strong foundation!
-
----
-
-**You've built the foundation. Now expand it to show you can architect ANY agent system!**
-

my_practice/first_llm_call.ipynb

@@ -1,276 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "f25e9940",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from litellm import completion\n",
-    "\n",
-    "\n",
-    "result = completion(\n",
-    "    model = 'gpt-4o',\n",
-    "    messages = [{'role':'user', 'content' : 'Hello'}]\n",
-    "\n",
-    ")\n",
-    "\n",
-    "\n"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 2,
-   "id": "fba08f3a",
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "'Hello! How can I assist you today?'"
-      ]
-     },
-     "execution_count": 2,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "result.choices[0].message.content"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "c283cf21",
-   "metadata": {},
-   "source": [
-    "Building data models"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "f4a41257",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from typing import Union, Literal\n",
-    "from dataclasses import dataclass, field\n",
-    "from pydantic import BaseModel, Field, List, Dict, Any, Optional, BaseTool\n",
-    "import uuid\n",
-    "from datetime import datetime\n",
-    "import json\n",
-    "\n",
-    "## agent models\n",
-    "\n",
-    "class Message(BaseModel):\n",
-    "\n",
-    "    \"\"\"A text message in the conversation.\"\"\"\n",
-    "    type: Literal[\"message\"] = \"message\"\n",
-    "    role: Literal[\"system\", \"user\", \"assistant\"]\n",
-    "    content: str\n",
-    "\n",
-    "class ToolCall(BaseModel): \n",
-    "    \"\"\"LLM's request to execute a tool.\"\"\"\n",
-    "    type: Literal[\"tool_call\"] = \"tool_call\"\n",
-    "    tool_call_id: str\n",
-    "    name: str\n",
-    "    arguments: dict\n",
-    "    \n",
-    "\n",
-    "class ToolResult(BaseModel):\n",
-    "    \"\"\"Result from tool execution.\"\"\"\n",
-    "    type: Literal[\"tool_result\"] = \"tool_result\"\n",
-    "    tool_call_id: str\n",
-    "    name: str\n",
-    "    status: Literal[\"success\", \"error\"]\n",
-    "    content: list\n",
-    "\n",
-    "class ToolConfirmation(BaseModel): ## this is temperory so not in union (user to agent)\n",
-    "    \"\"\"User's decision on a pending tool call.\"\"\"\n",
-    "    tool_call_id: str\n",
-    "    approved: bool\n",
-    "    modified_arguments: dict | None = None\n",
-    "    reason: str | None = None  # Reason for rejection (if not approved)\n",
-    "\n",
-    "class PendingToolCall(BaseModel): ## this is temperory so not in union(agent to user)\n",
-    "    \"\"\"A tool call awaiting user confirmation.\"\"\"\n",
-    "    \n",
-    "    tool_call: ToolCall\n",
-    "    confirmation_message: str\n",
-    "\n",
-    "## every request returns with these things so union all of them\n",
-    "ContentItem = Union[Message, ToolCall, ToolResult, ToolConfirmation] ## keep adding if there is more\n",
-    "\n",
-    "class Event(BaseModel):\n",
-    "    \"\"\"A recorded occurrence during agent execution.\"\"\"\n",
-    "    id: str = Field(default_factory=lambda: str(uuid.uuid4()))\n",
-    "    execution_id: str\n",
-    "    timestamp: float = Field(default_factory=lambda: datetime.now().timestamp())\n",
-    "    author: str  # \"user\" or agent name\n",
-    "    content: List[ContentItem] = Field(default_factory=list)\n",
-    "\n",
-    "@dataclass\n",
-    "class ExecutionContext: ## there will be frequent modifications to this, so not basemodel\n",
-    "    \"\"\"Central storage for all execution state.\"\"\"\n",
-    "    \n",
-    "    execution_id: str = field(default_factory=lambda: str(uuid.uuid4()))\n",
-    "    events: List[Event] = field(default_factory=list)\n",
-    "    current_step: int = 0\n",
-    "    state: Dict[str, Any] = field(default_factory=dict)\n",
-    "    final_result: Optional[str | BaseModel] = None\n",
-    "    session_id: Optional[str] = None  # Link to session for persistence\n",
-    "\n",
-    "\n",
-    "\n",
-    "### lets do LLM models\n",
-    "\n",
-    "class LlmRequest(BaseModel):\n",
-    "    \"\"\"Request object for LLM calls.\"\"\"\n",
-    "    instructions: List[str] = Field(default_factory=list)\n",
-    "    contents: List[ContentItem] = Field(default_factory=list)\n",
-    "    tools: List[BaseTool] = Field(default_factory=list)\n",
-    "    tool_choice: Optional[str] = 'auto'\n",
-    "\n",
-    "class LlmResponse(BaseModel):\n",
-    "    \"\"\"Response object from LLM calls.\"\"\"\n",
-    "    content: List[ContentItem] = Field(default_factory=list)\n",
-    "    error_message: Optional[str] = None\n",
-    "    usage_metadata: Dict[str, Any] = Field(default_factory=dict)\n",
-    "\n",
-    "class LlmClient(BaseModel):\n",
-    "    def _parse_response(self, response) -> LlmResponse:\n",
-    "        \"\"\"Convert API response to LlmResponse.\"\"\"\n",
-    "        choice = response.choices[0]\n",
-    "        content_items = []\n",
-    "        \n",
-    "        # Parse message content\n",
-    "        if choice.message.content:\n",
-    "            content_items.append(Message(\n",
-    "                role=\"assistant\",\n",
-    "                content=choice.message.content\n",
-    "            ))\n",
-    "\n",
-    "        # Parse tool calls\n",
-    "        if choice.message.tool_calls:\n",
-    "            for tc in choice.message.tool_calls:\n",
-    "                content_items.append(ToolCall(\n",
-    "                    tool_call_id=tc.id,\n",
-    "                    name=tc.function.name,\n",
-    "                    arguments=json.loads(tc.function.arguments)\n",
-    "                ))\n",
-    "        \n",
-    "        return LlmResponse(\n",
-    "            content=content_items,\n",
-    "            usage_metadata={\n",
-    "                \"input_tokens\": response.usage.prompt_tokens,\n",
-    "                \"output_tokens\": response.usage.completion_tokens,\n",
-    "            }\n",
-    "        )   ## this is internal method to parse toolcalls, reasoning, message content\n",
-    "        \n",
-    "\n",
-    "def build_messages(request: LlmRequest) -> List[dict]: ## will be reused everywhere\n",
-    "    \"\"\"Convert LlmRequest to API message format.\"\"\"\n",
-    "    messages = []\n",
-    "    \n",
-    "    # Add system instructions\n",
-    "    for instruction in request.instructions:\n",
-    "        messages.append({\"role\": \"system\", \"content\": instruction})\n",
-    "    \n",
-    "    # Convert content items\n",
-    "    for item in request.contents:\n",
-    "        if isinstance(item, Message):\n",
-    "            messages.append({\"role\": item.role, \"content\": item.content})\n",
-    "            \n",
-    "        elif isinstance(item, ToolCall):\n",
-    "            tool_call_dict = {\n",
-    "                \"id\": item.tool_call_id,\n",
-    "                \"type\": \"function\",\n",
-    "                \"function\": {\n",
-    "                    \"name\": item.name,\n",
-    "                    \"arguments\": json.dumps(item.arguments)\n",
-    "                }\n",
-    "            }\n",
-    "            # Append to previous assistant message if exists\n",
-    "            if messages and messages[-1][\"role\"] == \"assistant\":\n",
-    "                messages[-1].setdefault(\"tool_calls\", []).append(tool_call_dict)\n",
-    "            else:\n",
-    "                messages.append({\n",
-    "                    \"role\": \"assistant\",\n",
-    "                    \"content\": None,\n",
-    "                    \"tool_calls\": [tool_call_dict]\n",
-    "                })\n",
-    "                \n",
-    "        elif isinstance(item, ToolResult):\n",
-    "            messages.append({\n",
-    "                \"role\": \"tool\",\n",
-    "                \"tool_call_id\": item.tool_call_id,\n",
-    "                \"content\": str(item.content[0]) if item.content else \"\"\n",
-    "            })\n",
-    "    \n",
-    "    return messages\n",
-    "\n"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "d4b6afba",
-   "metadata": {},
-   "source": [
-    "Building our Agent"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "2d7d0140",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from dataclasses import dataclass\n",
-    "from typing import List, Optional\n",
-    "from .llm import LlmClient\n",
-    "from .models import ExecutionContext\n",
-    "\n",
-    "class Agent:\n",
-    "    \"\"\"Agent that can reason and use tools to solve tasks.\"\"\"\n",
-    "    \n",
-    "    def __init__(\n",
-    "        self,\n",
-    "        model: LlmClient,\n",
-    "        tools: List[BaseTool] = None,\n",
-    "        instructions: str = \"\",\n",
-    "        max_steps: int = 5,\n",
-    "        name: str = \"agent\"\n",
-    "    ):\n",
-    "        self.model = model\n",
-    "        self.instructions = instructions\n",
-    "        self.max_steps = max_steps\n",
-    "        self.name = name\n",
-    "        self.tools = tools or []"
-   ]
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": ".venv",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.12.11"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 5
-}

my_practice/pydantic.ipynb

@@ -1,255 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "code",
-   "execution_count": 16,
-   "id": "ff3b1200",
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "msg1.role: user\n",
-      "msg2.role: assistant\n",
-      "msg3.role: system\n",
-      "\n",
-      "Validation error: 1 validation error for Message\n",
-      "role\n",
-      "  Input should be 'user', 'assistant' or 'system' [type=literal_error, input_value='admin', input_type=str]\n",
-      "    For further information visit https://errors.pydantic.dev/2.11/v/literal_error\n",
-      "\n",
-      "Missing field error: 1 validation error for Message\n",
-      "content\n",
-      "  Field required [type=missing, input_value={'role': 'user'}, input_type=dict]\n",
-      "    For further information visit https://errors.pydantic.dev/2.11/v/missing\n"
-     ]
-    }
-   ],
-   "source": [
-    "from pydantic import BaseModel, ValidationError\n",
-    "from typing import Literal\n",
-    "\n",
-    "# Create a Message model like in your framework\n",
-    "class Message(BaseModel):\n",
-    "    role: Literal[\"user\", \"assistant\", \"system\"]\n",
-    "    content: str\n",
-    "\n",
-    "# Test 1: Valid messages\n",
-    "msg1 = Message(role=\"user\", content=\"Hello\")\n",
-    "msg2 = Message(role=\"assistant\", content=\"Hi there!\")\n",
-    "msg3 = Message(role=\"system\", content=\"You are helpful\")\n",
-    "\n",
-    "print(f\"msg1.role: {msg1.role}\")\n",
-    "print(f\"msg2.role: {msg2.role}\")\n",
-    "print(f\"msg3.role: {msg3.role}\")\n",
-    "\n",
-    "# Test 2: What happens with invalid role?\n",
-    "try:\n",
-    "    bad_msg = Message(role=\"admin\", content=\"test\")\n",
-    "except ValidationError as e:\n",
-    "    print(f\"\\nValidation error: {e}\")\n",
-    "\n",
-    "# Test 3: What happens with missing content?\n",
-    "try:\n",
-    "    incomplete = Message(role=\"user\")\n",
-    "except ValidationError as e:\n",
-    "    print(f\"\\nMissing field error: {e}\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 27,
-   "id": "811107f4",
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "{\"role\":\"user\",\"content\":\"My Name is Akhil\",\"timestamp\":1769878310.697898}\n",
-      "{'role': 'user', 'content': 'My Name is Akhil', 'timestamp': 1769878310.697898}\n",
-      "user\n"
-     ]
-    }
-   ],
-   "source": [
-    "import datetime\n",
-    "from typing import Optional, List, Any, Dict\n",
-    "import uuid\n",
-    "from pydantic import Field\n",
-    "\n",
-    "class ChatMessage(BaseModel):\n",
-    "    role : Literal[\"user\", \"assistant\", \"system\"]\n",
-    "    content : str \n",
-    "    timestamp : float = Field(default_factory=lambda: datetime.datetime.now().timestamp())\n",
-    "\n",
-    "class ChatSession(BaseModel):\n",
-    "    session_id: str = Field(default_factory=lambda: str(uuid.uuid4()))\n",
-    "    user_name : str\n",
-    "    messages : List[ChatMessage] = Field(default_factory=list)\n",
-    "    metadata : Dict[str, Any] = Field(default_factory=dict)\n",
-    "\n",
-    "    def add_message(self, role: Literal[\"user\", \"assistant\", \"system\"], content: str):\n",
-    "        self.messages.append(ChatMessage(role = role, content = content))\n",
-    "\n",
-    "\n",
-    "\n",
-    "chat = ChatMessage(role = \"user\", content = \"My Name is Akhil\")\n",
-    "\n",
-    "print(chat.model_dump_json())\n",
-    "print(chat.model_dump())\n",
-    "\n",
-    "msg2 = ChatMessage.model_validate({\"role\": \"user\", \"content\": \"hi\"})\n",
-    "print(msg2.role)\n",
-    "\n",
-    "\n",
-    "\n"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 28,
-   "id": "a38ac16e",
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Starting API 1...\n",
-      "Finished API 1\n",
-      "Starting API 2...\n",
-      "Finished API 2\n",
-      "Starting API 3...\n",
-      "Finished API 3\n",
-      "\n",
-      "Total time: 6.0 seconds\n",
-      "Results: Result from API 1, Result from API 2, Result from API 3\n"
-     ]
-    }
-   ],
-   "source": [
-    "import time\n",
-    "\n",
-    "def slow_api_call(name: str) -> str:\n",
-    "    \"\"\"Simulate a slow API call (like calling OpenAI)\"\"\"\n",
-    "    print(f\"Starting {name}...\")\n",
-    "    time.sleep(2)  # Blocks for 2 seconds\n",
-    "    print(f\"Finished {name}\")\n",
-    "    return f\"Result from {name}\"\n",
-    "\n",
-    "# Sequential calls - takes 6 seconds total\n",
-    "start = time.time()\n",
-    "\n",
-    "result1 = slow_api_call(\"API 1\")\n",
-    "result2 = slow_api_call(\"API 2\")\n",
-    "result3 = slow_api_call(\"API 3\")\n",
-    "\n",
-    "print(f\"\\nTotal time: {time.time() - start:.1f} seconds\")\n",
-    "print(f\"Results: {result1}, {result2}, {result3}\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 32,
-   "id": "afc59f41",
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Starting API 1...\n",
-      "Starting API 2...\n",
-      "Starting API 3...\n",
-      "Finished API 1\n",
-      "Finished API 2\n",
-      "Finished API 3\n",
-      "\n",
-      "Total time: 2.0 seconds\n",
-      "Results: ['Result from API 1', 'Result from API 2', 'Result from API 3'], Result from API 2, Result from API 3\n"
-     ]
-    }
-   ],
-   "source": [
-    "import time\n",
-    "import asyncio\n",
-    "\n",
-    "async def slow_api_call(name: str) -> str:\n",
-    "    \"\"\"Simulate a slow API call (like calling OpenAI)\"\"\"\n",
-    "    print(f\"Starting {name}...\")\n",
-    "    await asyncio.sleep(2)  # Blocks for 2 seconds\n",
-    "    print(f\"Finished {name}\")\n",
-    "    return f\"Result from {name}\"\n",
-    "\n",
-    "# Sequential calls - takes 6 seconds total\n",
-    "start = time.time()\n",
-    "\n",
-    "result1 = await asyncio.gather(\n",
-    "    slow_api_call(\"API 1\"),\n",
-    "slow_api_call(\"API 2\"),\n",
-    "slow_api_call(\"API 3\")\n",
-    ")\n",
-    "\n",
-    "print(f\"\\nTotal time: {time.time() - start:.1f} seconds\")\n",
-    "print(f\"Results: {result1}, {result2}, {result3}\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 34,
-   "id": "144c73f9",
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "['hi', 'hi', 'hi']\n"
-     ]
-    }
-   ],
-   "source": [
-    "async def fetch_weather(city: str) -> str:\n",
-    "    await asyncio.sleep(2)\n",
-    "    return \"hi\"\n",
-    "\n",
-    "async def fetch_news(news: str) -> str:\n",
-    "    await asyncio.sleep(1.5)\n",
-    "    return \"hi\"\n",
-    "\n",
-    "async def fetch_stock(symbool: str) -> str:\n",
-    "    await asyncio.sleep(1)\n",
-    "    return \"hi\"\n",
-    "\n",
-    "\n",
-    "results = await asyncio.gather(\n",
-    "         fetch_weather(\"hyd\"), fetch_news(\"hyd\"), fetch_stock(\"hyd\")\n",
-    "    )\n",
-    "print(results)\n"
-   ]
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": ".venv",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.12.11"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 5
-}

rag/__init__.py

@@ -0,0 +1,10 @@
+"""RAG (Retrieval-Augmented Generation) module."""
+
+from .embeddings import get_embeddings, vector_search
+from .chunking import fixed_length_chunking
+
+__all__ = [
+    "get_embeddings",
+    "vector_search",
+    "fixed_length_chunking",
+]

rag/embeddings.py

@@ -1,5 +1,8 @@
+"""Embedding and vector search utilities."""
+
 from openai import OpenAI
 import numpy as np
+from sklearn.metrics.pairwise import cosine_similarity
 from dotenv import load_dotenv
 import os
 
@@ -8,21 +11,21 @@ load_dotenv()
 
 # Initialize OpenAI client with API key from environment
 client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
- 
+
 def get_embeddings(texts, model="text-embedding-3-small"):
     """Convert text to embedding vectors."""
     if isinstance(texts, str):
         texts = [texts]
-    
+
     response = client.embeddings.create(input=texts, model=model)
     return np.array([item.embedding for item in response.data])
- 
+
 def vector_search(query, chunks, chunk_embeddings, top_k=3):
     """Find the most similar chunks to the query."""
     query_embedding = get_embeddings(query)
     similarities = cosine_similarity(query_embedding, chunk_embeddings)[0]
     top_indices = similarities.argsort()[::-1][:top_k]
-    
+
     results = []
     for idx in top_indices:
         results.append({
@@ -30,15 +33,3 @@ def vector_search(query, chunks, chunk_embeddings, top_k=3):
             'similarity': similarities[idx]
         })
     return results
-
-from sklearn.metrics.pairwise import cosine_similarity
- 
-sentences = [
-    "The cat is sleeping on the couch",
-    "A kitten is playing with a toy", 
-    "The dog is running in the park"
-]
-embeddings = get_embeddings(sentences)
- 
-cat_kitten = cosine_similarity([embeddings[0]], [embeddings[1]])[0][0]
-cat_dog = cosine_similarity([embeddings[0]], [embeddings[2]])[0][0]

rag/example.py

@@ -1,27 +0,0 @@
-from embeddings import get_embeddings, cosine_similarity
-def vector_search(query, chunks, chunk_embeddings, top_k=3):
-    """Find the most similar chunks to the query."""
-    query_embedding = get_embeddings(query)
-    similarities = cosine_similarity(query_embedding, chunk_embeddings)[0]
-    top_indices = similarities.argsort()[::-1][:top_k]
-    
-    results = []
-    for idx in top_indices:
-        results.append({
-            'chunk': chunks[idx],
-            'similarity': similarities[idx]
-        })
-    return results
-
-documents = [
-    "Python is a programming language",
-    "Machine learning uses Python extensively", 
-    "Cats are popular pets",
-    "Deep learning is a subset of machine learning"
-]
- 
-doc_embeddings = get_embeddings(documents)
- 
-results = vector_search("Artificial Intelligence", documents, doc_embeddings, top_k=4)
-for r in results:
-    print(f"{r['similarity']:.3f}: {r['chunk']}")

rag/example2.py

@@ -1,84 +0,0 @@
-from tavily import TavilyClient
-import os 
-from dotenv import load_dotenv
-from chunking import fixed_length_chunking
-from embeddings import get_embeddings
-from sklearn.metrics.pairwise import cosine_similarity
-import numpy as np
-
-
-load_dotenv()
-tavily = TavilyClient(api_key=os.getenv("TAVILY_API_KEY"))
-
-
-response = tavily.search(
-    "2025 Nobel Prize winners",
-    max_results=10,
-    include_raw_content=True
-)
- 
-search_results = []
-for result in response['results']:
-    if result.get('raw_content'):
-        search_results.append({
-            'title': result['title'],
-            'content': result['raw_content'],
-            'url': result['url']
-        })
-all_chunks = []
-for result in search_results:
-    text = f"Title: {result['title']}\n{result['content']}"
-    chunks = fixed_length_chunking(text, chunk_size=500, overlap=50)
-    for chunk in chunks:
-        all_chunks.append({
-            'text': chunk,
-            'title': result['title'],
-            'url': result['url']
-        })
- 
-print(f"Total chunks: {len(all_chunks)}")
- 
-chunk_texts = [c['text'] for c in all_chunks]
-chunk_embeddings = get_embeddings(chunk_texts)
-
-def vector_search(query, chunks, chunk_embeddings, top_k=3):
-    """Find the most similar chunks to the query."""
-    query_embedding = get_embeddings(query)
-    similarities = cosine_similarity(query_embedding, chunk_embeddings)[0]
-    top_indices = similarities.argsort()[::-1][:top_k]
-    
-    results = []
-    for idx in top_indices:
-        results.append({
-            'chunk': chunks[idx],
-            'similarity': similarities[idx],
-            'title': all_chunks[idx]['title'],
-            'url': all_chunks[idx]['url']
-        })
-    return results
-
-query = "quantum computing"
-results = vector_search(query, chunk_texts, chunk_embeddings, top_k=3)
- 
-print(f"Query: '{query}'\n")
-print("=" * 60)
-for i, r in enumerate(results, 1):
-    print(f"\n[{i}] Similarity: {r['similarity']:.3f}")
-    print(f"Title: {r['title']}")
-    print(f"URL: {r['url']}")
-    print(f"Chunk: {r['chunk'][:300]}...")
-
-total_tokens = 17000
-import tiktoken
- 
-# token savings effect
-
-enc = tiktoken.get_encoding("cl100k_base")  # Used by GPT-4, GPT-4-turbo, etc.
-# Alternative: enc = tiktoken.encoding_for_model("gpt-4")  # If you want to use a specific model
-top_chunks = [r['chunk'] for r in results]
-selected_text = "\n\n".join(top_chunks)
-selected_tokens = len(enc.encode(selected_text))
- 
-print(f"Total tokens: {total_tokens}")
-print(f"Selected tokens: {selected_tokens}")
-print(f"Savings rate: {(1 - selected_tokens/total_tokens)*100:.1f}%")