Clean up CrewAI Tutorial

research/state.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import List, Dict, Optional, Tuple
+from pydantic import BaseModel, Field
+
+#Supporting Schemas
+
+class DataFrameInfo(BaseModel):
+    shape: Tuple[int, int]
+    columns: List[str]
+    dtypes: Dict[str, str]
+    null_counts: Dict[str, int]
+    sample_rows: List[Dict]
+    detected_time_column: Optional[str] = None
+
+
+class ColumnInfo(BaseModel):
+    name: str
+    dtype: str
+    statistics: Dict[str, float] = Field(default_factory=dict)
+    detected_issues: List[str] = Field(default_factory=list)
+
+
+class NotebookCell(BaseModel):
+    id: str
+    cell_type: str
+    content: str
+
+    result_text: Optional[str] = None
+    result_tables: Optional[List[Dict]] = None
+    result_images: Optional[List[str]] = None
+
+    error: Optional[str] = None
+    executed_at: Optional[datetime] = None
+
+
+#Core Agent State Tracking
+
+class AgentState(BaseModel):
+    #Metadata
+    version: str = "1.0.0"
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    last_updated: datetime = Field(default_factory=datetime.utcnow)
+
+    #Conversation
+    conversation_history: List[Dict[str, str]] = Field(default_factory=list)
+
+    #Dataset Understanding
+    dataset_info: Optional[DataFrameInfo] = None
+    columns: List[ColumnInfo] = Field(default_factory=list)
+
+    #Notebook Tracking
+    notebook_path: Optional[str] = None
+    executed_cells: List[NotebookCell] = Field(default_factory=list)
+
+    #Analysis Progress
+    current_phase: str = "INITIALIZATION"
+    phase_progress: Dict[str, str] = Field(default_factory=dict)
+
+    #Process Control
+    retry_count: int = 0
+    max_retries: int = 3
+    should_continue: bool = True
+
+    #Error tracking
+    errors: List[str] = Field(default_factory=list)
+    warnings: List[str] = Field(default_factory=list)
+
+#Utility Methods
+
+    def update_timestamp(self):
+        self.last_updated = datetime.utcnow()
+
+    def add_error(self, message: str):
+        self.errors.append(message)
+        self.retry_count += 1
+        self.update_timestamp()
+
+        if self.retry_count >= self.max_retries:
+            self.should_continue = False
+
+    def add_warning(self, message: str):
+        self.warnings.append(message)
+        self.update_timestamp()
+
+    def advance_phase(self, next_phase: str):
+        self.phase_progress[self.current_phase] = "done"
+        self.current_phase = next_phase
+        self.phase_progress[next_phase] = "running"
+        self.retry_count = 0
+        self.update_timestamp()
+
+    def fail_phase(self):
+        self.phase_progress[self.current_phase] = "failed"
+        self.should_continue = False
+        self.update_timestamp()
+
+#Serialization Utilities
+
+def save_state(state: AgentState, path: str):
+    with open(path, "w") as f:
+        f.write(state.model_dump_json(indent=2))
+
+
+def load_state(path: str) -> AgentState:
+    with open(path, "r") as f:
+        raw = json.load(f)
+
+    raw = migrate_state(raw)
+    return AgentState.model_validate(raw)
+
+
+#Migration Strategy
+
+def migrate_state(data: dict) -> dict:
+    version = data.get("version", "0.0.0")
+
+    if version == "0.0.0":
+        data["version"] = "1.0.0"
+        data.setdefault("retry_count", 0)
+        data.setdefault("max_retries", 3)
+
+    return data

tutorials/CrewAI/README.md

@@ -0,0 +1,143 @@
+# Learn CrewAI in 60 Minutes
+## Structured Multi Agent AI Systems with Planning, Execution, and Critique
+
+---
+
+# 1. Goal
+
+This tutorial provides everything needed to become familiar with CrewAI in 60 minutes.  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.
+
+By the end, you will move from:
+
+Single LLM prompts → Structured autonomous AI systems
+
+---
+
+# 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)
+
+
+# 5. 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
+
+# 6. 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.
+
+# 7. Native API Overview
+Core abstractions: 
+Agent: 
+
+```bash
+Agent(
+    role="Planner",
+    goal="Plan next notebook step",
+    backstory="Expert AI planner"
+)
+```
+
+Task:
+
+```bash
+Task(
+    description="Execute notebook cell",
+    agent=worker
+)
+```
+
+Crew:
+
+```bash
+Crew(
+    agents=[planner, worker, critic],
+    tasks=[task]
+)
+```
+
+# 8. State Management
+
+State includes: Objective, Execution history, Notebook outputs, Error traces, Completion flag
+
+Explicit state ensures: Reproducibility, Debuggability, Deterministic behavior, Observability
+
+Avoid hidden memory.