clean up and reorganize

Author: retroryan

SLIDES.md

@@ -0,0 +1,151 @@
+# Slides Sync Proposal
+
+The slide decks in `graphacademy/slides/` were written against an earlier lab numbering. The labs have since been reorganized and three new labs added (5, 6, 7). This proposal brings the slides in sync with the current lab structure without deleting any existing content.
+
+## Current State
+
+### Slide folders → Lab mapping
+
+| Slide Folder | Covers | Current Lab(s) |
+|---|---|---|
+| `lab-1-neo4j-aura` (slides 01-07) | Neo4j Aura, GenAI limits, RAG, GraphRAG, SEC filings, Aura Agents, Fabric Workload | Lab 0, Lab 1, Lab 2 |
+| `lab-2-foundry` (slides 01-03) | What is an Agent, MCP, Microsoft Foundry | Lab 3 |
+| _(no slides)_ | — | Lab 4 (Start Codespace — setup only, no slides needed) |
+| _(no slides)_ | — | **Lab 5 (Foundry Agents — MAF basics, tools, context providers)** |
+| _(no slides)_ | — | **Lab 6 (Context Providers — Neo4j context providers)** |
+| _(no slides)_ | — | **Lab 7 (Agent Memory — neo4j-agent-memory)** |
+| `lab-5-knowledge-graph` (slides 01-07) | GenAI, RAG, KG pipeline, schema, chunking, entity resolution, vectors | Lab 8 |
+| `lab-6-retrievers` (slides 01-04) | Retrievers overview, vector, vector+cypher, text2cypher | Lab 10, Lab 11 |
+| `lab-7-agents` (slides 01-05) | Retrievers→agents, MAF, building agent, design patterns, congratulations | Lab 9 |
+
+### Gaps
+
+1. **Labs 5, 6, 7 have no slides.** These are the new MAF hands-on labs.
+2. **Slide folder names don't match current lab numbers.** `lab-5-knowledge-graph` is actually Lab 8, etc.
+3. **The "Microsoft Agent Framework" slide (`lab-7-agents/02`)** uses an older API surface (`AzureAIClient`, `ChatAgent`, `create_agent`, threads) that doesn't match the current MAF API (`AzureOpenAIResponsesClient`, `as_agent()`, `run_stream()`, sessions, context providers).
+4. **No slides cover context providers or agent memory** — the two key concepts introduced in the new labs.
+
+## Proposed Changes
+
+### 1. Add new slide folder: `lab-5-foundry-agents` (2 decks)
+
+Covers Lab 5 — introduces MAF with hands-on tools and context providers.
+
+**01-microsoft-agent-framework-slides.md** (~8 slides)
+- What is the Microsoft Agent Framework and why it exists (LLMs are stateless)
+- Core concepts: Agents, Tools, Context Providers, Sessions, Middleware
+- The agent lifecycle: context providers `before_run()` → LLM invocation → `after_run()`
+- Tools vs context providers (when each runs, best for)
+- Key API: `AzureOpenAIResponsesClient`, `as_agent()`, `run_stream()`
+- Architecture diagram (same as Lab 5 README)
+
+**02-tools-and-context-providers-slides.md** (~6 slides)
+- Defining tools: Python functions with `Annotated` + `Field` type annotations
+- How the agent reads function name + docstring to decide tool selection
+- Context providers: `BaseContextProvider` with `before_run()` / `after_run()`
+- `SessionContext`: `extend_instructions()` and `extend_messages()`
+- `AgentSession` and persistent state across turns
+- Extracting structured data with Pydantic in `after_run()`
+
+### 2. Add new slide folder: `lab-6-context-providers` (2 decks)
+
+Covers Lab 6 — Neo4j context providers from `agent-framework-neo4j`.
+
+**01-neo4j-context-provider-slides.md** (~8 slides)
+- What is `Neo4jContextProvider` (from `agent-framework-neo4j`)
+- How `before_run()` works: recent messages → concatenate → search index → format results → inject
+- Three search modes: vector (cosine similarity), fulltext (BM25), hybrid (combined)
+- Comparison table of search modes (when to use each)
+- Graph enrichment: `retrieval_query` parameter for Cypher traversal after index match
+- Retriever selection logic table (index_type × retrieval_query → retriever class)
+- Result formatting: `[Score: 0.892] [company: Apple Inc] ...`
+- Configuration: `top_k`, `message_history_count`, `context_prompt`, `filter_stop_words`
+
+**02-graph-enrichment-slides.md** (~5 slides)
+- Why vector search alone isn't enough (returns chunks, not knowledge)
+- The two-step process: index search finds nodes → Cypher traversal enriches with relationships
+- Example retrieval query: match company → optional match risks, products → return enriched context
+- Before/after comparison: plain chunk text vs graph-enriched context with company, ticker, risks, products
+- Connecting it to Lab 5: context providers inject this automatically — no tool calls needed
+
+### 3. Add new slide folder: `lab-7-agent-memory` (2 decks)
+
+Covers Lab 7 — persistent agent memory from `neo4j-agent-memory`.
+
+**01-agent-memory-overview-slides.md** (~8 slides)
+- The problem: agents forget everything between sessions
+- What is `neo4j-agent-memory` — graph-native persistent memory
+- Three memory types:
+  - **Short-term**: conversation messages with embeddings (semantic search over past messages)
+  - **Long-term**: entities, facts (SPO triples), preferences (extracted from conversations)
+  - **Reasoning**: traces of past tool calls, success/failure, duration (learn from experience)
+- Memory types comparison table (what it stores, how it helps)
+- Neo4j graph model: Conversation → Message, Entity, Preference, Fact, ReasoningTrace → ReasoningStep → ToolCall
+- How memory differs from Lab 6 context providers: static knowledge graph vs dynamic memory that grows
+
+**02-memory-tools-slides.md** (~6 slides)
+- Memory context provider: `before_run()` retrieves from all three types, `after_run()` stores + extracts entities
+- Memory tools: the six callable tools (`search_memory`, `remember_preference`, `recall_preferences`, `search_knowledge`, `remember_fact`, `find_similar_tasks`)
+- Context provider vs memory tools: automatic background recall vs explicit agent-controlled operations
+- Combining both: context provider for passive recall + tools for active memory management
+- Entity extraction: automatic identification of people, organizations, concepts from messages
+- Entity deduplication: configurable strategies (exact, fuzzy, semantic, composite)
+
+### 4. Rename slide folders to match current lab numbers
+
+Rename the existing folders so the slide directory names align with the lab numbers:
+
+| Current Folder | New Folder | Lab |
+|---|---|---|
+| `lab-1-neo4j-aura` | `lab-1-neo4j-aura` | Labs 0-2 (no change) |
+| `lab-2-foundry` | `lab-3-foundry` | Lab 3 |
+| _(new)_ | `lab-5-foundry-agents` | Lab 5 |
+| _(new)_ | `lab-6-context-providers` | Lab 6 |
+| _(new)_ | `lab-7-agent-memory` | Lab 7 |
+| `lab-5-knowledge-graph` | `lab-8-knowledge-graph` | Lab 8 |
+| `lab-6-retrievers` | `lab-10-retrievers` | Lab 10 |
+| `lab-7-agents` | `lab-9-agents` | Lab 9 |
+
+### 5. Update existing `lab-7-agents/02-microsoft-agent-framework-slides.md`
+
+The current slide uses an older API surface that no longer matches the workshop code:
+
+| Current (old API) | Should Be (current API) |
+|---|---|
+| `AzureAIClient` | `AzureOpenAIResponsesClient` |
+| `client.create_agent()` | `client.as_agent()` |
+| `ChatAgent` | Agent created via `as_agent()` |
+| Threads (`get_new_thread()`, `thread=thread`) | Sessions (`AgentSession`, `session.state`) |
+
+This slide should be updated to match the API used in Lab 5 notebooks. The conceptual content (tool selection, docstrings, ReAct loop, instructions, streaming) is all still correct — only the code examples and API names need updating.
+
+### 6. Update `graphacademy/slides/README.md`
+
+Update the README to:
+- Add the three new slide sections (Lab 5, Lab 6, Lab 7)
+- Update folder references if renamed
+- Update the presentation order to include the new decks
+- Update slide statistics (total count)
+
+**No existing content in the README should be deleted** — only additions and reference updates.
+
+## What Is NOT Changing
+
+- All existing slide content is preserved (no deletions)
+- Lab 1 slides (01-07) stay as-is
+- Lab 2/Foundry slides (01-03) stay as-is
+- Lab 5/Knowledge Graph slides (01-07) stay as-is
+- Lab 6/Retrievers slides (01-04) stay as-is
+- Lab 7/Agents slides (01, 03, 04, 05) stay as-is
+- Lab 7/Agents slide 02 gets API updates only (conceptual content unchanged)
+- The `clean-html.sh` script and `images/` directory are untouched
+
+## Summary
+
+| Action | Count |
+|---|---|
+| New slide decks to write | 6 |
+| Folders to rename | 3 |
+| Existing slides to update | 1 (API names only) |
+| Existing slides deleted | 0 |
+| README updates | 1 |

graphacademy/slides/README.md

@@ -51,7 +51,7 @@ All slides are organized by lab module for easy navigation.
    - Testing and Deployment
    - Bridge to Code-Based Implementation
 
-### Lab 2: Microsoft Foundry & MCP (Slides 1-3)
+### Lab 3: Microsoft Foundry & MCP (Slides 1-3)
 
 **01. What is an AI Agent** (4.0 KB)
    - Evolution of AI Assistants
@@ -74,7 +74,62 @@ All slides are organized by lab module for easy navigation.
    - MCP Tool Catalogue
    - Enterprise Governance (Control Plane)
 
-### Lab 5: Building Knowledge Graphs (Slides 1-7)
+### Lab 5: Foundry Agents (Slides 1-2)
+
+**01. The Microsoft Agent Framework**
+   - Why Agents Need a Framework (LLMs Are Stateless)
+   - Core Concepts: Agents, Tools, Context Providers, Sessions, Middleware
+   - The Agent Lifecycle (before_run → LLM → after_run)
+   - Tools vs Context Providers Comparison
+   - Key API: AzureOpenAIResponsesClient, as_agent(), run_stream()
+   - Sessions and Persistent State
+
+**02. Tools and Context Providers**
+   - Defining Tools with Type Annotations
+   - Annotated + Field for Parameter Descriptions
+   - How Tool Selection Works (Docstrings)
+   - BaseContextProvider Lifecycle Hooks
+   - before_run(): Injecting Instructions and Messages
+   - after_run(): Extracting Structured Data with Pydantic
+   - Session State Persistence
+
+### Lab 6: Neo4j Context Providers (Slides 1-2)
+
+**01. Neo4j Context Providers**
+   - What is Neo4jContextProvider (agent-framework-neo4j)
+   - How before_run() Works (Messages → Search → Format → Inject)
+   - Three Search Modes: Vector, Fulltext, Hybrid
+   - Configuration Options (top_k, message_history_count, context_prompt)
+   - Result Formatting with Scores and Metadata
+   - Retriever Selection Logic
+
+**02. Graph-Enriched Context**
+   - Why Vector Search Alone Isn't Enough
+   - The retrieval_query Parameter
+   - Two-Step Process: Index Search → Cypher Traversal
+   - Example Retrieval Query (Company → Risks, Products)
+   - Before/After: Plain Chunk vs Graph-Enriched Context
+
+### Lab 7: Agent Memory (Slides 1-2)
+
+**01. Neo4j Agent Memory**
+   - The Problem: Agents Forget Between Sessions
+   - What is neo4j-agent-memory
+   - Short-Term Memory: Messages with Embeddings
+   - Long-Term Memory: Entities, Facts (SPO Triples), Preferences
+   - Reasoning Memory: Tool Call Traces and Outcomes
+   - Graph Data Model
+   - How Memory Differs from Knowledge Graph Context
+
+**02. Memory Context Provider and Tools**
+   - Memory Context Provider: before_run() and after_run()
+   - What Gets Injected from Each Memory Type
+   - The Six Memory Tools
+   - Context Provider vs Memory Tools
+   - Combining Both Approaches
+   - Entity Extraction and Deduplication
+
+### Lab 8: Building Knowledge Graphs (Slides 1-7)
 
 **01. The GenAI Promise and Its Limits** (4.2 KB)
    - What Generative AI Does Well
@@ -124,7 +179,7 @@ All slides are organized by lab module for easy navigation.
    - Vector Search in Neo4j
    - Document Chunking
 
-### Lab 6: GraphRAG Retrievers (Slides 1-4)
+### Lab 10: GraphRAG Retrievers (Slides 1-4)
 
 **01. Retrievers Overview** (5.2 KB)
    - What is GraphRAG?
@@ -152,7 +207,7 @@ All slides are organized by lab module for easy navigation.
    - Modern Cypher Syntax Best Practices
    - Complex Query Handling
 
-### Lab 7: Intelligent Agents (Slides 1-5)
+### Lab 9: Intelligent Agents (Slides 1-5)
 
 **01. From Retrievers to Agents** (3.7 KB)
    - What are Agents?
@@ -161,7 +216,7 @@ All slides are organized by lab module for easy navigation.
 
 **02. Microsoft Agent Framework** (3.6 KB)
    - Building Agents with Microsoft Agent Framework
-   - AzureAIClient Setup
+   - AzureOpenAIResponsesClient Setup
    - Schema Tools
    - Agent Architecture
    - Tool Definition as Python Functions
@@ -420,22 +475,31 @@ marp 01-what-is-genai-slides.md --server
 
 ## 📈 Slide Statistics
 
-**Total Presentations:** 25
-**Total Slide Pages:** ~300 individual slides
+**Total Presentations:** 31
+**Total Slide Pages:** ~360 individual slides
 **Format:** Marp Markdown
 **Status:** ✅ Ready to present
 
 ### Lab Breakdown
 - **Lab 1:** 6 presentations (Neo4j Aura, GenAI Limits, Traditional RAG, GraphRAG Limits, SEC Filings Graph, Aura Agents)
-- **Lab 2:** 3 presentations (What is an Agent, MCP, Microsoft Foundry)
-- **Lab 5:** 7 presentations (GenAI Fundamentals, Knowledge Graphs)
-- **Lab 6:** 4 presentations (GraphRAG Retrievers)
-- **Lab 7:** 5 presentations (Intelligent Agents)
-
-### New Slides Added (December 3, 2025)
-- 01: What is an AI Agent (lab-2-foundry)
-- 02: What is MCP (lab-2-foundry)
-- 03: Microsoft Foundry (lab-2-foundry)
-
-**Latest Update:** Added Lab 2 slides covering AI Agents, MCP, and Microsoft Foundry
-**Version:** 2.2 (December 3, 2025)
+- **Lab 3:** 3 presentations (What is an Agent, MCP, Microsoft Foundry)
+- **Lab 5:** 2 presentations (Microsoft Agent Framework, Tools and Context Providers)
+- **Lab 6:** 2 presentations (Neo4j Context Providers, Graph-Enriched Context)
+- **Lab 7:** 2 presentations (Agent Memory Overview, Memory Tools)
+- **Lab 8:** 7 presentations (GenAI Fundamentals, Knowledge Graphs)
+- **Lab 9:** 5 presentations (Intelligent Agents)
+- **Lab 10:** 4 presentations (GraphRAG Retrievers)
+
+### New Slides Added (February 27, 2026)
+- 01: The Microsoft Agent Framework (lab-5-foundry-agents)
+- 02: Tools and Context Providers (lab-5-foundry-agents)
+- 01: Neo4j Context Providers (lab-6-context-providers)
+- 02: Graph-Enriched Context (lab-6-context-providers)
+- 01: Neo4j Agent Memory (lab-7-agent-memory)
+- 02: Memory Context Provider and Tools (lab-7-agent-memory)
+
+### Previous Updates
+- December 3, 2025: Added Lab 3 slides covering AI Agents, MCP, and Microsoft Foundry
+
+**Latest Update:** Added Lab 5, 6, 7 slides; renamed folders to match current lab numbers; updated Lab 9 MAF slide API references
+**Version:** 3.0 (February 27, 2026)