Clean up tutorial CrewAI

tutorials/CrewAI/README.md

@@ -0,0 +1,153 @@
+# Learn CrewAI in 60 Minutes
+## Structured Multi Agent AI Systems with Planning, Execution, and Critique
+
+---
+
+# 1. Goal
+
+This tutorial shows how to move from single LLM calls to a structured multi agent loop using CrewAI.  You will build and run a simple Planner -> Worker -> Critic system and understand the pattern better.  This folder also contains the setup for running AutoGen tutorials within a containerized environment.
+
+CrewAI is a framework for building **collaborative multiagent AI systems** where agents with specialized roles plan, execute, critique, and refine tasks iteratively.
+
+---
+
+# 2. What This Tutorial Provides
+
+## Hands on Experience
+
+- Working Docker container
+- Reproducible notebook (`tutorial_crewai.ipynb`)
+- End to end runnable example
+- Multiagent planning loop
+
+## Conceptual Understanding
+
+You will understand:
+
+- What CrewAI is
+- What problem it solves
+- Native API structure
+- When to use multiagent systems
+- Alternatives and trade-offs
+
+## Practical Application
+
+You can:
+
+- Build a Planner -> Worker -> Critic loop
+- Execute notebook code through agents
+- Implement retry logic
+- Track explicit state
+
+## Reproducibility
+
+- Notebook runs end to end
+- Dependencies are managed via the container environment
+
+---
+
+# 3. Structure
+
+## Quick Start
+- From the root of the repository, change your directory to the CrewAI tutorial
+  folder:
+  ```bash
+  > cd tutorials/CrewAI
+  ```
+
+- Once the location has been changed to the repo run the command to build the
+  image to run dockers:
+  ```bash
+  > ./docker_build.sh
+  ```
+
+- Once the docker has been built you can then go ahead and run the container and
+  launch jupyter notebook using the created image using the command:
+  ```bash
+  > ./docker_jupyter.sh
+  ```
+
+- Once the `./docker_jupyter.sh` script is running, follow this sequence to
+  explore the tutorials:
+  1. **`tutorial_crewai.ipynb`**: Start here to master the fundamental commands and more about creating agents, defining tasks, running a crew, how to give an agent tools and how an agent calls Python functions.
+  2. **`Autogen.example.ipynb`**: Proceed to this notebook to explore more
+     complex, multi-agent scenarios and advanced problem-solving techniques.
+
+- For more informations on the Docker build system refer to [Project template
+  readme](https://github.com/gpsaggese/umd_classes/blob/master/class_project/project_template/README.md)
+
+
+# 4. What is CrewAI?
+
+CrewAI is a Python framework for building structured multi agent AI systems.
+
+Instead of:
+
+```bash
+prompt -> response
+```
+
+CrewAI enables:
+
+```bash
+Planner -> Worker -> Critic -> Update -> Repeat
+```
+It supports role specialization, task delegation, tool usage, explicit coordination, iterative refinement
+
+# 5. What Problem Does It Solve?
+
+Single LLM calls lack iterative correction, error recovery, explicit state, structured decomposition, and deterministic ochestration.
+
+CrewAI introduces modular agents, explicit tasks, structured workflows, and observable state transitions.
+
+# 6. API Overview
+Core abstractions: 
+Agent -> defines behavior and role 
+
+```bash
+Agent(
+    role="Planner",
+    goal="Plan next notebook step",
+    backstory="Expert AI planner"
+)
+```
+
+Task -> binds work to an agent
+
+```bash
+Task(
+    description="Execute notebook cell",
+    agent=worker
+)
+```
+
+Crew -> orchestrates execution
+
+```bash
+Crew(
+    agents=[planner, worker, critic],
+    tasks=task
+)
+```
+
+# 7. Real Example
+
+Example: Executing a Notebook Task
+- Planner decides which cell to run next
+- Worker executes the code
+- Critic checks correctness (errors, output validity)
+- System retries or moves forward
+
+# 8. When Not to Use CrewAI
+- If a single prompt works reliably
+- If latency matters
+- If you don't need iterative correction
+
+
+# 9. State Management
+
+State includes: Objective, Execution history, Notebook outputs, Error traces, Completion flag
+
+Explicit state ensures: Reproducibility, Debuggability, Deterministic behavior, Observability
+
+Avoid hidden memory.

tutorials/CrewAI/crewai.API.py

@@ -14,7 +14,7 @@
 # ---
 
 # %% [markdown]
-# # CrewAI API Overview
+# # CrewAI API
 #
 # CrewAI is an open-source Python framework for building **role-playing,
 # autonomous AI agent crews**. Each agent has a defined role, goal, and
@@ -29,7 +29,7 @@
 # - **Process** – sequential vs. hierarchical execution
 
 # %% [markdown]
-# ## Setup
+# ## Imports
 
 # %%
 import logging
@@ -64,7 +64,18 @@
     temperature=0.2,
 )
 print(f"LLM model: {llm.model}")
+# %% [markdown]
+# ## Notebook Structure
+#
+# This notebook follows a basic progression:
+# - Configure LLM
+# - Define agents
+# - Assign tasks
+# - Execute a crew
+# - Extend with tools
+# - Understand how to build multi-step workflows
 
+# %%
 # %% [markdown]
 # ## Agents
 #
@@ -253,4 +264,4 @@ def word_count(text: str) -> str:
     memory=True,  # enables short-term shared memory
     verbose=False,
 )
-print("Memory crew created with memory=True")
+print("Memory crew created with memory=True")

tutorials/CrewAI/tutorial_crewai.py

@@ -15,7 +15,13 @@
 
 # %% [markdown]
 # # Crew AI Agents, Local LLMs (Ollama: Qwen, Gemma)
-
+#
+# ## Notebook Structure
+# Part 1 of this notebook introduces the minimal CrewAI workflow:
+# - Configure a local LLM (Ollama)
+# - Define a simple agent
+# - Create a task
+# - Execute a crew
 # %%
 from crewai import Agent, Task, Crew, Process, LLM
 
@@ -38,6 +44,7 @@
 with open("data/sample.txt") as f:
     doc_text = f.read()
 
+# Define a task
 task = Task(
     description=(
         f"Summarize the following text into exactly 3 concise bullet points:\n\n{doc_text}"
@@ -46,6 +53,7 @@
     agent=summarizer,
 )
 
+# Execute a crew
 crew = Crew(
     agents=[summarizer],
     tasks=[task],
@@ -59,7 +67,12 @@
 
 # %% [markdown]
 # ## Agentic EDA Demo
-
+# Part 2 of this notebook introduces a use of CrewAI with Agentic EDA
+# demonstrating the following:
+# - Why tools matter
+# - Define tools
+# - Attach to agent
+# - Run multi-step task
 # %%
 # main.py
 import os