Cleanup content, demos, and README outline

SETUP.md

@@ -1,6 +1,6 @@
-# Setup Guide for Context Engineering Course
+# Setup Guide for Context Engineering Workshop
 
-This guide will help you set up everything you need to run the Context Engineering notebooks and progressive agents.
+This guide will help you set up everything you need to run the workshop notebooks (`workshop/`) and the staged agent demos (`demos/`).
 
 ## Prerequisites
 
@@ -70,8 +70,8 @@ pip install -e .
 ### Step 4: Load Course Data
 
 ```bash
-# Load hierarchical courses into Redis (required for notebooks and progressive agents)
-uv run python -m redis_context_course.scripts.load_hierarchical_courses \
+# Load hierarchical courses into Redis (required for workshop and demos)
+uv run load-hierarchical-courses \
   -i src/redis_context_course/data/hierarchical/hierarchical_courses.json \
   --force
 
@@ -84,13 +84,10 @@ uv run python -m redis_context_course.scripts.ingest_courses \
 
 **Note:** Use `--force` to clear and reload data if you've regenerated the course catalog or if you're seeing duplicate courses.
 
-### Step 5: Run the Notebooks
+### Step 5: Run the Workshop Notebooks
 
 ```bash
-# Start Jupyter
-uv run jupyter notebook notebooks/
-
-# Or for the workshop
+# Start Jupyter for the workshop
 uv run jupyter notebook workshop/
 ```
 
@@ -204,22 +201,15 @@ If you already have Redis running or want to use Redis Cloud:
 
 Once setup is complete:
 
-**For the Workshop (condensed, ~6 hours):**
+**For the Workshop (condensed):**
 1. Start with **Module 1** (Introduction) to understand context types
 2. Work through **Module 2** (RAG Essentials) for vector search fundamentals
 3. Complete **Module 3** (Data Engineering) for data pipeline patterns
 4. Master **Module 4** (Memory Systems) for working and long-term memory
-5. Build agents in **Module 5** and compare in **Module 6**
-
-**For the Full Course (comprehensive, 15-20 hours):**
-1. Start with **Section 1** notebooks to understand core concepts
-2. Work through **Section 2** to learn RAG and context engineering
-3. Complete **Section 3** to master memory management (requires Agent Memory Server)
-4. Explore **Section 4** for tools and agent development
+5. Explore the staged demos in `demos/` to see the same ideas evolve into increasingly capable agents
 
 ## Getting Help
 
 - Check the main [README.md](README.md) for course structure and learning path
-- Review [workshop/README.md](workshop/README.md) for the condensed workshop
-- Open an issue if you encounter problems with the setup
+- Review the **Workshop Outline** and **Agent Demos (CLI)** sections in the main [README.md](README.md)
 

progressive_agents/CONTENT_COVERAGE_GAP_ANALYSIS.md → demos/CONTENT_COVERAGE_GAP_ANALYSIS.md

@@ -38,7 +38,7 @@ LONG_TERM_MEMORY=true            # Enable long-term memory extraction
 
 **Evidence from codebase:**
 ```python
-# From progressive_agents/stage6_full_memory/agent/nodes.py (lines 148-156)
+# From demos/stage6_full_memory/agent/nodes.py (lines 148-156)
 async def save_working_memory_node(state: WorkflowState) -> WorkflowState:
     """
     Save working memory to Agent Memory Server.
@@ -280,7 +280,7 @@ The following notebook concepts are **intentionally not demonstrated** in progre
 
 ### Priority 4: Main README Update (Low Effort, Medium Value)
 
-Add to main `progressive_agents/README.md`:
+Add to main `README.md`:
 
 ```markdown
 ## Automatic Features (Handled by Infrastructure)

demos/__init__.py

@@ -0,0 +1 @@
+# Agent demo stages

demos/stage1_baseline_rag/__init__.py

@@ -0,0 +1 @@
+# Stage 1: Baseline RAG Agent

progressive_agents/stage1_baseline_rag/cli.py → demos/stage1_baseline_rag/cli.py

@@ -37,17 +37,20 @@
 
 logger = logging.getLogger("stage1-cli")
 
-# Add parent directory to path for imports
-sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
-
 # Load environment variables from project root
 from dotenv import load_dotenv
 
-env_path = Path(__file__).parent.parent / "src" / ".env"
+env_path = Path(__file__).resolve().parents[2] / ".env"
 load_dotenv(env_path)
 
-from agent import cleanup_courses, initialize_state, setup_agent
-from agent.workflow import create_workflow
+# Import agent module - try relative import first (when running as package),
+# fall back to direct import (when running python cli.py from this directory)
+try:
+    from .agent import cleanup_courses, initialize_state, setup_agent
+    from .agent.workflow import create_workflow
+except ImportError:
+    from agent import cleanup_courses, initialize_state, setup_agent
+    from agent.workflow import create_workflow
 
 
 class BaselineRAGCLI:

demos/stage2_context_engineered/__init__.py

@@ -0,0 +1 @@
+# Stage 2: Context-Engineered Agent

progressive_agents/stage2_context_engineered/cli.py → demos/stage2_context_engineered/cli.py

@@ -37,17 +37,20 @@
 
 logger = logging.getLogger("stage2-cli")
 
-# Add parent directory to path for imports
-sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
-
 # Load environment variables from project root
 from dotenv import load_dotenv
 
-env_path = Path(__file__).parent.parent / "src" / ".env"
+env_path = Path(__file__).resolve().parents[2] / ".env"
 load_dotenv(env_path)
 
-from agent import cleanup_courses, initialize_state, setup_agent
-from agent.workflow import create_workflow
+# Import agent module - try relative import first (when running as package),
+# fall back to direct import (when running python cli.py from this directory)
+try:
+    from .agent import cleanup_courses, initialize_state, setup_agent
+    from .agent.workflow import create_workflow
+except ImportError:
+    from agent import cleanup_courses, initialize_state, setup_agent
+    from agent.workflow import create_workflow
 
 
 class ContextEngineeredCLI:

demos/stage3_full_agent_without_memory/__init__.py

@@ -0,0 +1 @@
+# Stage 3: Full Agent Without Memory

progressive_agents/stage3_full_agent_without_memory/cli.py → demos/stage3_full_agent_without_memory/cli.py

@@ -30,11 +30,14 @@
             break
         current = current.parent
 
-# Add agent module to path
-sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
-
-from agent import create_workflow, run_agent, setup_agent
-from agent.setup import cleanup_courses
+# Import agent module - try relative import first (when running as package),
+# fall back to direct import (when running python cli.py from this directory)
+try:
+    from .agent import create_workflow, run_agent, setup_agent
+    from .agent.setup import cleanup_courses
+except ImportError:
+    from agent import create_workflow, run_agent, setup_agent
+    from agent.setup import cleanup_courses
 
 
 class CourseQACLI:
@@ -321,5 +324,10 @@ async def main():
         await cli.interactive_mode()
 
 
-if __name__ == "__main__":
+def run():
+    """Sync entry point for uv scripts."""
     asyncio.run(main())
+
+
+if __name__ == "__main__":
+    run()

progressive_agents/stage3_full_agent_without_memory/debug_search.py → demos/stage3_full_agent_without_memory/debug_search.py

@@ -14,7 +14,7 @@
 load_dotenv(env_path)
 
 # Add agent module to path
-sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "src"))
 
 from agent.setup import setup_agent
 from agent.tools import search_courses

progressive_agents/stage3_full_agent_without_memory/test_linear_algebra.py → demos/stage3_full_agent_without_memory/test_linear_algebra.py

@@ -12,13 +12,11 @@
 from pathlib import Path
 
 # Add parent directory to path
-sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "src"))
 
 from redis_context_course import CourseManager
 
-from progressive_agents.stage3_full_agent_without_memory.agent.workflow import (
-    create_workflow,
-)
+from agent.workflow import create_workflow
 
 # Configure logging
 logging.basicConfig(

progressive_agents/stage3_full_agent_without_memory/test_simple.py → demos/stage3_full_agent_without_memory/test_simple.py

@@ -10,13 +10,11 @@
 from pathlib import Path
 
 # Add parent directory to path
-sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "src"))
 
 from redis_context_course import CourseManager
 
-from progressive_agents.stage3_full_agent_without_memory.agent.workflow import (
-    create_workflow,
-)
+from agent.workflow import create_workflow
 
 # Configure logging
 logging.basicConfig(

demos/stage4_hybrid_search/__init__.py

@@ -0,0 +1 @@
+# Stage 4: Hybrid Search with ReAct

progressive_agents/stage4_hybrid_search/cli.py → demos/stage4_hybrid_search/cli.py

@@ -40,11 +40,14 @@
             break
         current = current.parent
 
-# Add agent module to path
-sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
-
-from agent import create_workflow, run_agent_async, setup_agent
-from agent.setup import cleanup_courses
+# Import agent module - try relative import first (when running as package),
+# fall back to direct import (when running python cli.py from this directory)
+try:
+    from .agent import create_workflow, run_agent_async, setup_agent
+    from .agent.setup import cleanup_courses
+except ImportError:
+    from agent import create_workflow, run_agent_async, setup_agent
+    from agent.setup import cleanup_courses
 
 # If quiet mode, ensure all loggers are suppressed after imports
 if _quiet_mode:
@@ -243,6 +246,11 @@ async def main():
         await cli.interactive_mode()
 
 
-if __name__ == "__main__":
+def run():
+    """Sync entry point for uv scripts."""
     asyncio.run(main())
 
+
+if __name__ == "__main__":
+    run()
+

demos/stage5_working_memory/__init__.py

@@ -0,0 +1 @@
+# Stage 5: Working Memory

progressive_agents/stage5_working_memory/cli.py → demos/stage5_working_memory/cli.py

@@ -43,11 +43,14 @@
             break
         current = current.parent
 
-# Add agent module to path
-sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
-
-from agent import create_workflow, run_agent_async, setup_agent
-from agent.setup import cleanup_courses
+# Import agent module - try relative import first (when running as package),
+# fall back to direct import (when running python cli.py from this directory)
+try:
+    from .agent import create_workflow, run_agent_async, setup_agent
+    from .agent.setup import cleanup_courses
+except ImportError:
+    from agent import create_workflow, run_agent_async, setup_agent
+    from agent.setup import cleanup_courses
 
 # If quiet mode, ensure all loggers are suppressed after imports
 if _quiet_mode:
@@ -435,5 +438,10 @@ async def main():
         await cli.interactive_mode()
 
 
-if __name__ == "__main__":
+def run():
+    """Sync entry point for uv scripts."""
     asyncio.run(main())
+
+
+if __name__ == "__main__":
+    run()

progressive_agents/stage5_working_memory/debug_search.py → demos/stage5_working_memory/debug_search.py

@@ -14,7 +14,7 @@
 load_dotenv(env_path)
 
 # Add agent module to path
-sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "src"))
 
 from agent.setup import setup_agent
 from agent.tools import search_courses

progressive_agents/stage6_full_memory/test_agent_intents.py → demos/stage5_working_memory/test_agent_intents.py

@@ -14,14 +14,11 @@
 from pathlib import Path
 
 # Add parent directory to path
-sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "src"))
 
 from redis_context_course import CourseManager
 
-from progressive_agents.stage6_full_memory.agent.workflow import (
-    create_workflow,
-    run_agent_async,
-)
+from agent.workflow import create_workflow, run_agent_async
 
 # Configure logging
 logging.basicConfig(

progressive_agents/stage5_working_memory/test_exact_match_react.py → demos/stage5_working_memory/test_exact_match_react.py

@@ -8,8 +8,8 @@
 from langchain_openai import ChatOpenAI
 from redis_context_course import CourseManager
 
-from progressive_agents.stage5_working_memory.agent.react_agent import run_react_agent
-from progressive_agents.stage5_working_memory.agent.tools import initialize_tools
+from agent.react_agent import run_react_agent
+from agent.tools import initialize_tools
 
 logging.basicConfig(
     level=logging.INFO,

progressive_agents/stage6_full_memory/test_linear_algebra.py → demos/stage5_working_memory/test_linear_algebra.py

@@ -10,14 +10,11 @@
 from pathlib import Path
 
 # Add parent directory to path
-sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "src"))
 
 from redis_context_course import CourseManager
 
-from progressive_agents.stage6_full_memory.agent.workflow import (
-    create_workflow,
-    run_agent_async,
-)
+from agent.workflow import create_workflow, run_agent_async
 
 # Configure logging to show tool calls
 logging.basicConfig(

progressive_agents/stage5_working_memory/test_react_multi_turn.py → demos/stage5_working_memory/test_react_multi_turn.py

@@ -13,8 +13,8 @@
 from langchain_openai import ChatOpenAI
 from redis_context_course import CourseManager
 
-from progressive_agents.stage5_working_memory.agent.react_agent import run_react_agent
-from progressive_agents.stage5_working_memory.agent.tools import initialize_tools
+from agent.react_agent import run_react_agent
+from agent.tools import initialize_tools
 
 # Configure logging
 logging.basicConfig(

progressive_agents/stage5_working_memory/test_react_simple.py → demos/stage5_working_memory/test_react_simple.py

@@ -12,8 +12,8 @@
 from langchain_openai import ChatOpenAI
 from redis_context_course import CourseManager
 
-from progressive_agents.stage5_working_memory.agent.react_agent import run_react_agent
-from progressive_agents.stage5_working_memory.agent.tools import initialize_tools
+from agent.react_agent import run_react_agent
+from agent.tools import initialize_tools
 
 # Configure logging
 logging.basicConfig(

progressive_agents/stage6_full_memory/test_simple.py → demos/stage5_working_memory/test_simple.py

@@ -8,14 +8,11 @@
 from pathlib import Path
 
 # Add parent directory to path
-sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "src"))
 
 from redis_context_course import CourseManager
 
-from progressive_agents.stage6_full_memory.agent.workflow import (
-    create_workflow,
-    run_agent_async,
-)
+from agent.workflow import create_workflow, run_agent_async
 
 # Configure logging
 logging.basicConfig(

demos/stage6_full_memory/__init__.py

@@ -0,0 +1 @@
+# Stage 6: Full Memory (Working + Long-term)

progressive_agents/stage6_full_memory/agent/tools.py → demos/stage6_full_memory/agent/tools.py

@@ -49,7 +49,7 @@ def initialize_tools(manager: CourseManager):
 
     # Load hierarchical courses with full syllabi
     try:
-        # OLD PATH (incorrect - looked in progressive_agents/stage7_react_loop/src/...):
+        # OLD PATH (incorrect - looked in demos/stage7_react_loop/src/...):
         # data_path = (
         #     Path(__file__).parent.parent / "src"
         #     / "redis_context_course"