Enhance workshop chapters with teaching notes and collapsible code

NiallJoeMaher · NiallJoeMaher · commit b76863128ee3 · 2025-11-26T06:01:37.000Z
Added to all CHAPTER-*.md files:
- Branch checkout instructions at the top
- Teaching Notes for Presenters section with:
  - React Parallels table (maps AI SDK concepts to familiar React patterns)
  - Key Talking Points for live presentation
  - Live Demo Tips for demonstrating features
  - Common Questions with answers
- Collapsible code snippets using &lt;details&gt;&lt;summary&gt; HTML
- React Parallel callout boxes explaining concepts

Target audience: Mid-level React developers learning AI/LLM concepts
diff --git a/CHAPTER-0.md b/CHAPTER-0.md
@@ -2,6 +2,49 @@
 
 Welcome to the AI Chatbot Workshop! In this chapter, we'll explore the foundation of our application - a basic chat interface powered by Next.js and the AI SDK.
 
+> **Branch**: `workshop/chapter-00-starting-point`
+> ```bash
+> git checkout workshop/chapter-00-starting-point
+> ```
+
+---
+
+## Teaching Notes for Presenters
+
+### React Parallels
+
+| AI SDK Concept | React Equivalent | Key Insight |
+|----------------|------------------|-------------|
+| `useChat` hook | `useState` + `useEffect` | Manages message state + side effects in one hook |
+| `streamText` | Server Action with streaming | Similar to `generateStaticParams` but for runtime AI |
+| Message history | Component state array | Just like managing a list of items in React state |
+| Data streaming | React Suspense boundaries | Progressive loading, but for tokens instead of components |
+
+### Key Talking Points
+
+1. **"The AI SDK is just React patterns applied to AI"**
+   - `useChat` is essentially `useSWR` or `useQuery` specialized for chat
+   - Streaming is like Progressive Hydration but for text generation
+   - The chat API route is a standard Next.js Route Handler
+
+2. **"Tokens, not characters"**
+   - LLMs generate tokens (word pieces), not individual characters
+   - This is why text appears in chunks, not letter-by-letter
+   - Cost is measured in tokens (~4 chars/token for English)
+
+3. **"Messages are immutable"**
+   - Just like React state, we never mutate message arrays
+   - Each message gets a unique ID (like React keys)
+   - History grows by adding, never modifying
+
+### Common Questions
+
+- **"Why streaming?"** - UX feels faster (first token in ~200ms vs 5s for complete response)
+- **"What's the system prompt?"** - Like a component's defaultProps, but for AI behavior
+- **"Can I use a different AI?"** - Yes! Just change the provider in `lib/ai/providers.ts`
+
+---
+
 ## Learning Objectives
 
 By the end of this chapter, you'll understand:
@@ -41,6 +84,9 @@ The heart of the application is `/app/(chat)/api/chat/route.ts`. This is where m
 
 ### Basic Chat Flow
 
+<details>
+<summary>📄 <strong>Code: Basic Chat API Route</strong> (click to expand)</summary>
+
 ```typescript
 // app/(chat)/api/chat/route.ts (simplified)
 import { streamText } from "ai";
@@ -61,6 +107,8 @@ export async function POST(request: Request) {
 }
 ```
 
+</details>
+
 ### Key Concepts
 
 1. **`streamText`**: The AI SDK function that sends messages to the model and streams the response token by token.
@@ -92,6 +140,9 @@ When you send a message:
 
 The frontend uses `useChat` from the AI SDK React package:
 
+<details>
+<summary>📄 <strong>Code: useChat Hook Usage</strong> (click to expand)</summary>
+
 ```typescript
 // Simplified usage in a chat component
 import { useChat } from "@ai-sdk/react";
@@ -115,6 +166,10 @@ export function Chat() {
 }
 ```
 
+</details>
+
+> 💡 **React Parallel**: `useChat` is like combining `useState` for messages, `useReducer` for state transitions, and `useSWR` for the API call - all in one hook.
+
 The `useChat` hook handles:
 - Managing message history
 - Sending messages to the API
@@ -139,6 +194,9 @@ type Message = {
 
 The system prompt shapes the AI's personality and behavior:
 
+<details>
+<summary>📄 <strong>Code: System Prompt</strong> (click to expand)</summary>
+
 ```typescript
 // lib/ai/prompts.ts
 export const systemPrompt = () => `
@@ -147,6 +205,10 @@ Today's date is ${new Date().toLocaleDateString()}.
 `;
 ```
 
+</details>
+
+> 💡 **React Parallel**: Think of the system prompt as `defaultProps` or the initial context value - it sets the baseline behavior that all messages inherit.
+
 ## Exercise: Trace a Message
 
 1. Start the development server: `npm run dev`
diff --git a/CHAPTER-1.md b/CHAPTER-1.md
@@ -2,6 +2,55 @@
 
 In this chapter, we'll give the AI the ability to **do things** beyond just responding with text. We'll add a weather tool that demonstrates how AI can call functions to retrieve real-time information.
 
+> **Branch**: `workshop/chapter-01-first-tool`
+> ```bash
+> git checkout workshop/chapter-01-first-tool
+> ```
+
+---
+
+## Teaching Notes for Presenters
+
+### React Parallels
+
+| AI SDK Concept | React Equivalent | Key Insight |
+|----------------|------------------|-------------|
+| `tool()` function | Custom hook definition | Encapsulates reusable logic with a defined interface |
+| `inputSchema` (Zod) | PropTypes / TypeScript props | Validates inputs before execution |
+| `execute` function | Event handler callback | Runs when the AI decides to use the tool |
+| Tool description | JSDoc / component documentation | Helps the AI "read" when to use it |
+
+### Key Talking Points
+
+1. **"Tools are just functions with extra metadata"**
+   - The AI reads the `description` to decide when to call
+   - Zod schemas ensure type-safe inputs (like TypeScript for AI)
+   - `execute` is async - can fetch APIs, query DBs, anything
+
+2. **"The AI decides, not you"**
+   - You define WHAT the tool does, the AI decides WHEN
+   - Good descriptions = accurate tool selection
+   - Bad descriptions = confused AI, wrong tool calls
+
+3. **"Tools don't break the chat"**
+   - Tool results flow back into the conversation
+   - The AI synthesizes results into natural language
+   - Users see a seamless experience
+
+### Live Demo Tips
+
+- Show the Network tab to see tool calls as separate events
+- Intentionally ask something the tool can't handle ("What's the weather on Mars?")
+- Compare with/without tools: same question, different capabilities
+
+### Common Questions
+
+- **"Why Zod?"** - Runtime validation + TypeScript types in one schema
+- **"Can tools call other tools?"** - Not directly, but the AI can chain multiple tool calls
+- **"What if the API fails?"** - Handle errors gracefully in `execute`, return user-friendly messages
+
+---
+
 ## Learning Objectives
 
 By the end of this chapter, you'll understand:
@@ -25,6 +74,9 @@ When you ask "What's the weather in London?", instead of guessing, the AI can **
 
 Every tool has three parts:
 
+<details>
+<summary>📄 <strong>Code: Tool Anatomy</strong> (click to expand)</summary>
+
 ```typescript
 import { tool } from "ai";
 import { z } from "zod";
@@ -46,12 +98,19 @@ const myTool = tool({
 });
 ```
 
+</details>
+
+> 💡 **React Parallel**: This is like defining a custom hook with TypeScript props - the schema is your prop types, the execute is your hook logic, and the description is your JSDoc comment.
+
 ## The Weather Tool
 
 Here's the complete weather tool implementation:
 
 ### File: `lib/ai/tools/get-weather.ts`
 
+<details>
+<summary>📄 <strong>Code: Complete Weather Tool</strong> (click to expand)</summary>
+
 ```typescript
 import { tool } from "ai";
 import { z } from "zod";
@@ -80,12 +139,17 @@ export const getWeather = tool({
 });
 ```
 
+</details>
+
 ## Wiring Tools into the Chat Route
 
 Add the tool to your chat route:
 
 ### File: `app/(chat)/api/chat/route.ts`
 
+<details>
+<summary>📄 <strong>Code: Add Tool to Route</strong> (click to expand)</summary>
+
 ```typescript
 import { streamText } from "ai";
 import { myProvider } from "@/lib/ai/providers";
@@ -111,6 +175,10 @@ export async function POST(request: Request) {
 }
 ```
 
+</details>
+
+> 💡 **Key Insight**: `maxSteps: 5` allows the AI to make multiple tool calls in sequence - like calling `getWeather` for two cities to compare them.
+
 ## How Tool Calling Works
 
 ```
diff --git a/CHAPTER-2.md b/CHAPTER-2.md
@@ -2,6 +2,55 @@
 
 In this chapter, we'll create our first **agent** - a specialized AI that can make its own decisions and generate rich responses. We'll build a Tutor agent that explains concepts with different teaching approaches.
 
+> **Branch**: `workshop/chapter-02-tutor-agent`
+> ```bash
+> git checkout workshop/chapter-02-tutor-agent
+> ```
+
+---
+
+## Teaching Notes for Presenters
+
+### React Parallels
+
+| AI SDK Concept | React Equivalent | Key Insight |
+|----------------|------------------|-------------|
+| Agent as tool | Higher-order component (HOC) | Wraps additional logic around a base component |
+| `generateText` | Async `fetch` in useEffect | Awaits a result, doesn't stream |
+| `CreateAgentProps` | React Context value | Passes session and dataStream to all agents |
+| `AgentResult` | Custom hook return type | Standardized shape for all agent outputs |
+
+### Key Talking Points
+
+1. **"Agents are tools that think"**
+   - Regular tools: fetch data, return it
+   - Agents: make their own AI call, generate content
+   - The orchestrator decides WHICH agent, the agent decides HOW to respond
+
+2. **"The tool-as-agent pattern"**
+   - Agents ARE tools (same interface)
+   - But they have a brain (call `generateText` internally)
+   - Think: React component that fetches its own data
+
+3. **"Why not just use the main model?"**
+   - Separation of concerns (each agent has focused expertise)
+   - Different prompts for different tasks
+   - Can use different models per agent (fast for routing, smart for generation)
+
+### Live Demo Tips
+
+- Ask for the same explanation with different approaches ("explain like I'm 5" vs "technical deep-dive")
+- Show the console logs to trace the agent flow
+- Demonstrate that the orchestrator still responds naturally after the agent
+
+### Common Questions
+
+- **"Can agents call other agents?"** - Not directly in this pattern, but the orchestrator can chain them
+- **"Why `generateText` not `streamText`?"** - Agents return complete results; streaming happens at orchestrator level
+- **"What's the session for?"** - Personalization, rate limiting, saving user progress
+
+---
+
 ## Learning Objectives
 
 By the end of this chapter, you'll understand:
@@ -52,6 +101,9 @@ First, let's define the structure for our agents:
 
 ### File: `lib/ai/agents/types.ts`
 
+<details>
+<summary>📄 <strong>Code: Agent Type Definitions</strong> (click to expand)</summary>
+
 ```typescript
 import type { Session } from "next-auth";
 import type { DataStreamWriter } from "ai";
@@ -71,6 +123,10 @@ export type AgentResult = {
 };
 ```
 
+</details>
+
+> 💡 **React Parallel**: `CreateAgentProps` is like a Context value - it's the same data passed to every agent, just like how React Context provides the same value to all consumers.
+
 ## Model Configuration
 
 Before building agents, understand what `"chat-model"` means. The app uses named models configured in `lib/ai/providers.ts`:
diff --git a/CHAPTER-3.md b/CHAPTER-3.md
@@ -2,6 +2,55 @@
 
 In this chapter, we'll add multiple specialized agents and see how they work together. We'll create a Quiz Master that tests knowledge and a Planner that creates study schedules.
 
+> **Branch**: `workshop/chapter-03-multi-agent`
+> ```bash
+> git checkout workshop/chapter-03-multi-agent
+> ```
+
+---
+
+## Teaching Notes for Presenters
+
+### React Parallels
+
+| AI SDK Concept | React Equivalent | Key Insight |
+|----------------|------------------|-------------|
+| Multiple agents | Multiple context providers | Each provides specialized functionality |
+| Orchestrator routing | React Router | Picks the right component based on input |
+| `generateObject` | Form state with Zod | Returns typed, validated data structures |
+| Agent descriptions | Route matching patterns | AI matches intent to description, like URL patterns |
+
+### Key Talking Points
+
+1. **"The AI is your router"**
+   - Just like React Router matches URLs to components
+   - The orchestrator matches user intent to agents
+   - Good descriptions = accurate routing
+
+2. **"`generateObject` is like a smart form submission"**
+   - You define the schema (like form fields)
+   - AI fills it in with valid data
+   - Returns typed JSON, not free-form text
+
+3. **"Agents should be single-purpose"**
+   - One agent = one job (Single Responsibility)
+   - Overlapping descriptions = confused routing
+   - Clear triggers = predictable behavior
+
+### Live Demo Tips
+
+- Ask for a quiz, then a study plan, then an explanation - show all three agents
+- Try chained requests: "Explain React hooks, then quiz me on them"
+- Show the Zod schema and how it enforces structure
+
+### Common Questions
+
+- **"What if two agents could handle the request?"** - Most specific description wins
+- **"Can I have too many agents?"** - Yes! Each adds complexity. Start with 3-5
+- **"Why `generateObject` for quiz but `generateText` for tutor?"** - Quiz needs structured data; tutor needs free-form text
+
+---
+
 ## Learning Objectives
 
 By the end of this chapter, you'll understand:
diff --git a/CHAPTER-4.md b/CHAPTER-4.md
diff --git a/CHAPTER-5.md b/CHAPTER-5.md
