diff --git a/research/state.py b/research/state.py new file mode 100644 index 000000000..8b16cb159 --- /dev/null +++ b/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 diff --git a/tutorials/CrewAI/README.md b/tutorials/CrewAI/README.md new file mode 100644 index 000000000..7c4a0a0a9 --- /dev/null +++ b/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. \ No newline at end of file