Clean repository with latest todo-agent code and article

- All agent code (storage.py, todo_agent.py) up to date
- Latest article: 'Out-of-the-Box Observability: OpenAI, Phoenix, and Weave Compared'
- Complete test suite and documentation
- No binary files - HF compatible

.env.example

@@ -0,0 +1,16 @@
+# Example .env for todo-agent
+
+# Required for OpenAI Agents SDK
+OPENAI_API_KEY=sk-...
+
+# Optional: Enable OpenAI Platform tracing
+OPENAI_TRACING_ENABLED=1
+
+# Optional: Weights & Biases Weave
+# WANDB_API_KEY=your-wandb-api-key
+
+# Optional: Arize Phoenix
+# PHOENIX_API_KEY=your-arize-api-key
+# PHOENIX_PROJECT=your-arize-project
+# PHOENIX_CLIENT_HEADERS=...
+# PHOENIX_COLLECTOR_ENDPOINT=...

.gitattributes

@@ -0,0 +1 @@
+*.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,143 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to an official Pipenv poll, the Pipfile.lock file should not be
+#   ignored: https://github.com/pypa/pipenv/pull/2607
+#Pipfile.lock
+
+# PEP 582; __pypackages__
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# User-specific data files
+data/todos.json
+data/session_default.json
+
+# Test logs and reports
+tests/logs/
+
+# Cursor editor files
+.cursor/
+.DS_Store
+instructional_docs/images/

README.md

@@ -0,0 +1,175 @@
+---
+title: To-Do Agent
+emoji: ✅
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+python_version: 3.12
+app_file: todo_gradio/gradio_app.py
+---
+
+# todo-agent
+
+A minimal OpenAI Agents SDK to-do list app with a full CRUD toolset and built-in web search. This project includes tracing/observation integrations for:
+- OpenAI Platform Tracing
+- Arize Phoenix Cloud
+- Weights & Biases Weave
+- A Gradio web UI for interactive use
+
+This project demonstrates a 101-level AI engineering workflow: building a modular agent, observing traces, and following best practices for Python project management.
+
+---
+
+## Project Structure
+
+```
+todo-agent/
+├── main.py                  # Entry point for the CLI app
+├── manage.py                # CLI for managing data (reset, seed)
+├── agent/
+│   ├── __init__.py
+│   ├── todo_agent.py        # Defines the agent, its tools, and prompt
+│   └── storage.py           # Data access layer for todos.json
+├── todo_gradio/
+│   └── gradio_app.py        # Gradio web UI application
+├── tests/
+│   ├── run_demo_tests.py    # Test runner for demo scenarios
+│   ├── test_basic_operations.py
+│   └── test_web_search_demo.py
+├── data/
+│   ├── todos.json           # User-specific to-do items (auto-created, gitignored)
+│   ├── session_default.json # Conversation history (auto-created, gitignored)
+│   └── seed_todos.json      # Example data for the `manage.py seed` command
+├── .gitignore
+├── .python-version
+├── pyproject.toml
+├── README.md
+└── uv.lock
+```
+
+---
+
+## Agent Capabilities
+
+The agent has access to a suite of tools to be a proactive assistant:
+
+- **`create_todo`**: Adds a new task to the list.
+- **`read_todos`**: Lists all tasks or filters by project.
+- **`update_todo`**: Modifies an existing task (e.g., renames it or marks it as complete).
+- **`delete_todo`**: Removes a task.
+- **`web_search`**: Searches the web to find information and clarify tasks. For example, if you ask it to "plan a trip," it will offer to research destinations for you.
+
+---
+
+## Setup
+
+1. **Install [uv](https://github.com/astral-sh/uv)**
+2. **Install dependencies:**
+   ```sh
+   uv pip install
+   ```
+3. **Environment variables:**
+   - Copy `.env.example` to `.env` and fill in your API keys and secrets. All required and optional variables are documented in `.env.example`.
+
+---
+
+## Environment Variables
+
+All required and optional environment variables are documented in the `.env.example` file. Copy this file to `.env` and update the values as needed for your environment and integrations.
+
+---
+
+## Running the App
+
+You can run the agent in two ways:
+
+### 1. Interactive Web UI (Gradio)
+
+This is the recommended way to use the agent.
+```sh
+uv run todo_gradio/gradio_app.py
+```
+The app will be available at a local URL (e.g., `http://127.0.0.1:7860`).
+
+### 2. Command-Line Interface (CLI)
+```sh
+uv run main.py
+```
+- Interact with the agent in natural language.
+- Type `exit` or `quit` to end the session.
+
+---
+
+## Managing Data for Testing
+
+This project includes a `manage.py` script with commands to help you reset or seed your data, which is useful for testing or running evaluations.
+
+-   **Resetting Data**: To clear all to-do items and conversation history, run:
+    ```sh
+    uv run manage.py reset --yes
+    ```
+-   **Seeding Data**: To load a specific set of to-dos for a test, run:
+    ```sh
+    uv run manage.py seed
+    ```
+    This command uses `data/seed_todos.json` by default, but you can provide a path to a different file.
+
+## Test Suite
+
+The project includes a comprehensive test suite for automated testing and demonstration. See `tests/README.md` for detailed documentation.
+
+```sh
+# Run all demo tests
+uv run tests/run_demo_tests.py all
+
+# Run individual demos
+uv run tests/run_demo_tests.py basic
+uv run tests/run_demo_tests.py websearch
+```
+
+The test suite demonstrates:
+- **Basic Operations**: AI Engineers 101 article creation workflow with technical content planning, status progression, and multi-project organization.
+- **Web Search Demo**: AI engineering research and technical writing with web search integration, knowledge synthesis, and research-driven task creation.
+
+Each test includes minimal validation and educational comments, using the same tracing setup as the main application for clean trace separation. **Use the observability dashboards to evaluate test quality and agent performance.**
+
+---
+
+## Data Files
+
+The `data/` directory holds both user-generated data and example data:
+
+- **`todos.json` & `session_default.json`**: These files are created automatically when you first run the app. They are listed in the `.gitignore` file, so your local conversation history and to-do items will not be committed to the repository.
+- **`seed_todos.json`**: This file is included in the repository and provides a default set of to-dos that you can load using the `uv run manage.py seed` command. It serves as a good starting point for testing.
+
+---
+
+## Tracing Integrations
+
+All tracing integrations are enabled by default in `main.py`:
+- **OpenAI Platform**: Native support, see [OpenAI docs](https://platform.openai.com/docs/observability/overview)
+- **Arize Phoenix Cloud**: See [Phoenix Otel Python SDK](https://arize.com/docs/phoenix/sdk-api-reference/python-pacakges/arize-phoenix-otel)
+- **Weights & Biases Weave**: See [W&B Weave docs](https://docs.wandb.ai/guides/weave)
+
+You can view traces in each provider's dashboard after running the agent.
+
+---
+
+## Development Standards
+
+- Use Python 3.12+
+- Use `uv` for all dependency and environment management
+- Only add dependencies with `uv add ...` or `uv pip install ...`
+- Never edit `pyproject.toml` directly
+- Use `python-dotenv` for environment variables
+- Follow PEP 8 and use type hints
+- Modular, reusable, and well-documented code
+- Comment complex logic and include Google-style docstrings
+- Implement proper error handling
+- Focus on security and performance
+
+---
+
+## License
+
+MIT

agent/__init__.py

@@ -0,0 +1 @@
+ 

agent/storage.py

@@ -0,0 +1,229 @@
+"""
+Data access layer for the to-do list.
+
+Provides abstract base class and concrete implementations:
+- JsonTodoStorage: Persists to local JSON file
+- InMemoryTodoStorage: Memory-based storage for transient sessions
+
+This separation allows different app entry points to use appropriate storage.
+"""
+
+import os
+import json
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import List, Optional, Dict, Any
+from datetime import datetime, timezone
+from pydantic import BaseModel, Field
+
+DATA_PATH = os.path.join(os.path.dirname(os.path.dirname(__file__)), "data", "todos.json")
+
+class TodoStatus(str, Enum):
+    """Status enumeration, inherits from str for JSON serialization."""
+    NOT_STARTED = "Not Started"
+    IN_PROGRESS = "In Progress"
+    COMPLETED = "Completed"
+
+class TodoItem(BaseModel):
+    """Represents a single to-do item."""
+    id: int
+    name: str = Field(..., description="Short, clear task name")
+    description: Optional[str] = Field(default=None, description="Optional detailed description")
+    project: Optional[str] = Field(default=None, description="Optional project name for grouping")
+    status: TodoStatus = Field(default=TodoStatus.NOT_STARTED, description="Current status")
+    created_at: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat(), description="Creation timestamp (UTC ISO 8601)")
+    updated_at: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat(), description="Last update timestamp (UTC ISO 8601)")
+
+# =============================================================================
+# Storage Interface
+# =============================================================================
+
+class AbstractTodoStorage(ABC):
+    """Abstract base class defining the contract for to-do storage."""
+
+    @abstractmethod
+    def create(self, name: str, description: Optional[str], project: Optional[str]) -> TodoItem:
+        """Creates a new to-do item and saves it."""
+        pass
+
+    @abstractmethod
+    def read_all(self) -> List[TodoItem]:
+        """Returns all to-do items."""
+        pass
+
+    @abstractmethod
+    def read_by_id(self, item_id: int) -> Optional[TodoItem]:
+        """Finds a single to-do item by its ID."""
+        pass
+
+    @abstractmethod
+    def read_by_project(self, project: str) -> List[TodoItem]:
+        """Finds all to-do items belonging to a specific project."""
+        pass
+
+    @abstractmethod
+    def update(self, item_id: int, update_data: Dict[str, Any]) -> Optional[TodoItem]:
+        """Updates an existing to-do item and saves the list."""
+        pass
+
+    @abstractmethod
+    def delete(self, item_id: int) -> bool:
+        """Deletes a to-do item by its ID and saves the list."""
+        pass
+
+# =============================================================================
+# JSON File Storage
+# =============================================================================
+
+class JsonTodoStorage(AbstractTodoStorage):
+    """Handles persistence using a JSON file."""
+    def __init__(self, path: str = DATA_PATH):
+        self._path = path
+        self._ensure_data_file()
+
+    def _ensure_data_file(self):
+        """Ensure the todos.json file exists."""
+        if not os.path.exists(self._path):
+            os.makedirs(os.path.dirname(self._path), exist_ok=True)
+            with open(self._path, "w") as f:
+                json.dump([], f)
+
+    def _load_todos(self) -> List[TodoItem]:
+        """Load all todos from JSON file and validate with Pydantic."""
+        with open(self._path, "r") as f:
+            data = json.load(f)
+        return [TodoItem(**item) for item in data]
+
+    def _save_todos(self, todos: List[TodoItem]):
+        """Save all todos to JSON file."""
+        with open(self._path, "w") as f:
+            json.dump([item.model_dump() for item in todos], f, indent=2)
+
+    def _get_next_id(self, todos: List[TodoItem]) -> int:
+        """Get the next available ID for a new to-do item."""
+        return max([t.id for t in todos], default=0) + 1
+
+    def create(self, name: str, description: Optional[str], project: Optional[str]) -> TodoItem:
+        """Creates a new to-do item and saves it."""
+        todos = self._load_todos()
+        now = datetime.now(timezone.utc).isoformat()
+        new_item = TodoItem(
+            id=self._get_next_id(todos),
+            name=name,
+            description=description,
+            project=project,
+            created_at=now,
+            updated_at=now,
+        )
+        todos.append(new_item)
+        self._save_todos(todos)
+        return new_item
+
+    def read_all(self) -> List[TodoItem]:
+        """Returns all to-do items."""
+        return self._load_todos()
+
+    def read_by_id(self, item_id: int) -> Optional[TodoItem]:
+        """Finds a single to-do item by its ID."""
+        todos = self.read_all()
+        return next((t for t in todos if t.id == item_id), None)
+
+    def read_by_project(self, project: str) -> List[TodoItem]:
+        """Finds all to-do items belonging to a specific project."""
+        todos = self.read_all()
+        return [t for t in todos if t.project and t.project.lower() == project.lower()]
+
+    def update(self, item_id: int, update_data: Dict[str, Any]) -> Optional[TodoItem]:
+        """Updates an existing to-do item and saves the list."""
+        todos = self.read_all()
+        
+        for i, item in enumerate(todos):
+            if item.id == item_id:
+                # Convert status string to enum if needed
+                if "status" in update_data and isinstance(update_data["status"], str):
+                    try:
+                        update_data["status"] = TodoStatus(update_data["status"])
+                    except ValueError:
+                        pass
+                
+                update_data["updated_at"] = datetime.now(timezone.utc).isoformat()
+                updated_item = todos[i].model_copy(update=update_data)
+                todos[i] = updated_item
+                self._save_todos(todos)
+                return updated_item
+        
+        return None
+
+    def delete(self, item_id: int) -> bool:
+        """Deletes a to-do item by its ID and saves the list."""
+        todos = self._load_todos()
+        original_count = len(todos)
+        new_todos = [t for t in todos if t.id != item_id]
+        
+        if len(new_todos) == original_count:
+            return False
+        
+        self._save_todos(new_todos)
+        return True
+
+# =============================================================================
+# In-Memory Storage
+# =============================================================================
+
+class InMemoryTodoStorage(AbstractTodoStorage):
+    """Handles persistence in memory for transient sessions."""
+    def __init__(self):
+        self._todos: List[TodoItem] = []
+        self._next_id = 1
+
+    def _get_next_id(self) -> int:
+        """Get the next available ID for a new to-do item."""
+        current_id = self._next_id
+        self._next_id += 1
+        return current_id
+
+    def create(self, name: str, description: Optional[str], project: Optional[str]) -> TodoItem:
+        now = datetime.now(timezone.utc).isoformat()
+        new_item = TodoItem(
+            id=self._get_next_id(),
+            name=name,
+            description=description,
+            project=project,
+            created_at=now,
+            updated_at=now,
+        )
+        self._todos.append(new_item)
+        return new_item
+
+    def read_all(self) -> List[TodoItem]:
+        return self._todos
+
+    def read_by_id(self, item_id: int) -> Optional[TodoItem]:
+        return next((t for t in self._todos if t.id == item_id), None)
+
+    def read_by_project(self, project: str) -> List[TodoItem]:
+        return [t for t in self._todos if t.project and t.project.lower() == project.lower()]
+
+    def update(self, item_id: int, update_data: dict) -> Optional[TodoItem]:
+        item_to_update = self.read_by_id(item_id)
+        if not item_to_update:
+            return None
+
+        # Convert status string to enum if needed
+        if "status" in update_data and isinstance(update_data["status"], str):
+            try:
+                update_data["status"] = TodoStatus(update_data["status"])
+            except ValueError:
+                pass
+
+        for key, value in update_data.items():
+            if hasattr(item_to_update, key):
+                setattr(item_to_update, key, value)
+        
+        item_to_update.updated_at = datetime.now(timezone.utc).isoformat()
+        return item_to_update
+
+    def delete(self, item_id: int) -> bool:
+        original_count = len(self._todos)
+        self._todos = [t for t in self._todos if t.id != item_id]
+        return len(self._todos) < original_count 

agent/todo_agent.py

@@ -0,0 +1,233 @@
+"""
+Agent identity, instructions, and tools.
+
+Tools bridge agent reasoning with the data layer in storage.py.
+"""
+
+import json
+from typing import Optional, Any
+from agents import Agent, function_tool, WebSearchTool
+from agent.storage import AbstractTodoStorage, JsonTodoStorage, TodoStatus
+
+# =============================================================================
+# Tool Definitions
+# =============================================================================
+
+# Factory uses closure to inject storage dependency, keeping tool signatures clean for LLM
+def get_tools(storage: AbstractTodoStorage):
+    """Factory to create tool functions with a specific storage backend."""
+
+    @function_tool
+    def create_todo(
+        name: str,
+        description: Optional[str] = None,
+        project: Optional[str] = None
+    ) -> str:
+        """Creates a new to-do item.
+        
+        Use when users ask to add, create, or remember tasks.
+        Be proactive about organizing tasks into projects.
+        
+        Args:
+            name: Brief, clear task title
+            description: Optional details or subtasks
+            project: Optional project/category for organization
+        
+        Returns:
+            Confirmation message with the created item's ID and details.
+        """
+        try:
+            item = storage.create(name, description, project)
+            return f"Created to-do item {item.id} ('{item.name}') in project '{item.project or 'None'}' with status '{item.status.value}'."
+        except Exception as e:
+            return f"Error creating to-do: {e}"
+
+    @function_tool
+    def read_todos(
+        item_id: Optional[int] = None,
+        project: Optional[str] = None
+    ) -> str:
+        """Reads all to-do items, or filters by ID/project.
+        
+        Use without parameters to see everything, or filter to find specific items.
+        Always check the list before updating or deleting items.
+        
+        Args:
+            item_id: Optional - specific todo item ID to retrieve
+            project: Optional - filter by project name (case-insensitive)
+        
+        Returns:
+            JSON formatted list of todos or specific todo details.
+        """
+        try:
+            if item_id is not None:
+                item = storage.read_by_id(item_id)
+                return item.model_dump_json(indent=2) if item else f"To-do item with ID {item_id} not found."
+            
+            if project:
+                project_todos = storage.read_by_project(project)
+                if not project_todos:
+                    return f"No to-do items found for project '{project}'."
+                return '[\n' + ',\n'.join([t.model_dump_json(indent=2) for t in project_todos]) + '\n]'
+            
+            all_todos = storage.read_all()
+            return '[\n' + ',\n'.join([t.model_dump_json(indent=2) for t in all_todos]) + '\n]'
+        except Exception as e:
+            return f"Error reading to-dos: {e}"
+
+    @function_tool
+    def update_todo(
+        item_id: int,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        project: Optional[str] = None,
+        status: Optional[str] = None
+    ) -> str:
+        """Updates an existing to-do item's attributes.
+        
+        Use to modify tasks or mark them complete. Pay attention to user's
+        language - past tense usually means update status to "Completed".
+        
+        Args:
+            item_id: The ID of the to-do item to update (required)
+            name: The new name of the to-do item
+            description: The new description of the to-do item
+            project: The new project name for the to-do item
+            status: Use exact status values: "Not Started", "In Progress", or "Completed" (case-sensitive)
+        
+        Returns:
+            Confirmation of update or error message if item not found.
+        """
+        try:
+            # Validate status against enum values to prevent hallucination
+            if status and status not in [s.value for s in TodoStatus]:
+                return f"Error: Invalid status '{status}'. Please use one of: {[s.value for s in TodoStatus]}."
+
+            update_data = {'name': name, 'description': description, 'project': project, 'status': status}
+            update_fields = {k: v for k, v in update_data.items() if v is not None}
+
+            if not update_fields:
+                return "Error: No fields to update were provided."
+            
+            updated_item = storage.update(item_id, update_fields)
+            return f"Updated to-do item {item_id}." if updated_item else f"To-do item with id {item_id} not found."
+        except Exception as e:
+            return f"Error updating to-do: {e}"
+
+    @function_tool
+    def delete_todo(
+        item_id: int
+    ) -> str:
+        """Deletes a to-do item from the list by its ID.
+        
+        Use to remove completed or cancelled tasks. Best practice:
+        always confirm with the user before deleting.
+        
+        Args:
+            item_id: The ID of the to-do item to delete (required)
+            
+        Returns:
+            Confirmation of deletion or error if item not found.
+        """
+        try:
+            if storage.delete(item_id):
+                return f"Deleted to-do item {item_id}."
+            else:
+                return f"To-do item with id {item_id} not found."
+        except Exception as e:
+            return f"Error deleting to-do: {e}"
+
+    return [create_todo, read_todos, update_todo, delete_todo, WebSearchTool()]
+
+# =============================================================================
+# Agent Configuration
+# =============================================================================
+
+AGENT_PROMPT = """
+You are a professional Executive Assistant. Your sole responsibility is to manage the user's to-do list with precision and initiative.
+
+You have a set of office supplies (tools) to manage the to-do list:
+- `create_todo`: Use this to add a new task.
+- `read_todos`: Use this to review existing tasks. You can view all tasks, or filter by a specific project.
+- `update_todo`: Use this to modify an existing task, such as changing its name or marking it as complete.
+- `delete_todo`: Use this to remove a task from the list.
+
+You also have a `web_search` tool for research. Use it proactively to help the user clarify vague tasks. Your goal is to turn ambiguous requests into actionable to-do items.
+
+**Your Capabilities & Boundaries:**
+- Primary focus: Managing and organizing the user's to-do list
+- Supporting capabilities: Use web search, basic math, and logical reasoning to help users create better, more actionable tasks
+- Always ground your help in task creation or organization - if a user asks something unrelated, acknowledge it briefly then guide them back to their task list
+
+**Communication Principles:**
+- Be concise but thorough - provide the right amount of detail for the task
+- Confirm actions before asking follow-ups: "I've added X to your list. Would you like..."
+- Use formatting for clarity (bullets for lists, bold for emphasis)
+- Show your reasoning when it helps: "Based on my research, I suggest breaking this into 3 tasks..."
+- When assigning projects, use consistent naming (e.g., "Writing" not "writing" or "WRITING")
+
+**Your Professional Workflow:**
+- When a user adds tasks, think about how they could be grouped. If a user adds "Buy milk" and later "Buy bread," assign both to a "Groceries" project. Be proactive in organizing the user's life.
+- When a user gives a vague task (e.g., "plan a trip"), don't just add it. Confirm the entry, then immediately offer to perform web research to gather necessary details.
+- After research, propose specific, actionable to-do items. For example, after researching Mexico, suggest creating tasks like "Book flights to Mexico" and "Reserve hotel in Cancun."
+- Always confirm actions with the user and use the precise tool for each operation. Maintain a professional and helpful tone.
+
+**Interpreting User Updates:**
+- When a user provides an update about an existing task, pay close attention to their phrasing.
+- If the user uses past-tense language (e.g., "I just finished the report," "I already bought the groceries," "I joined the gym"), it's a strong signal that the task is complete. First, find the relevant task ID, then confirm with the user before calling `update_todo` with `status='Completed'`.
+- If the user describes a change to the task's requirements (e.g., "add X to the shopping list," "change the meeting to 3 PM"), update the task's name or description using `update_todo`.
+
+**When Things Go Wrong:**
+- If a tool operation fails, explain clearly and suggest alternatives
+- If you can't find a todo item, offer to show the full list or search by keywords
+- If web search returns no results, acknowledge this and ask for clarification
+
+**Example Interaction Flow:**
+- **User**: "Add 'plan my trip' to my list."
+- **Assistant**: (Calls `create_todo` with name="plan my trip"). "Of course. I've added 'plan my trip' to your list. To make this more actionable, may I research potential destinations for you?"
+- **User**: "I'm not sure, maybe somewhere warm in December. Can you look up some ideas?"
+- **Assistant**: (Calls `web_search`). "My research shows that popular warm destinations in December include Hawaii, Mexico, and the Caribbean. Do any of these appeal to you?"
+- **User**: "Mexico sounds great."
+- **Assistant**: "Excellent. I will update the task to 'Plan trip to Mexico'." (Calls `update_todo` to change name). "Shall I also add 'Book flights to Mexico' and 'Book hotel in Mexico' to your to-do list?"
+
+**Example - Multi-Task Efficiency:**
+- **User**: "Add these three tasks: draft report, schedule meeting, and buy coffee"
+- **Assistant**: "I'll add all three tasks for you." (Calls `create_todo` three times efficiently). "I've added 'draft report', 'schedule meeting', and 'buy coffee' to your list. Should I group these under a specific project like 'Work' or 'Weekly Tasks'?"
+
+**Example - Using Math for Better Tasks:**
+- **User**: "I need to save money for a $3,000 vacation in 10 months"
+- **Assistant**: "Let me help you plan this. You'll need to save $300/month to reach $3,000 in 10 months. I'll create a task 'Set aside $300 for vacation fund' with a monthly recurrence. Would you also like me to research ways to reduce expenses or find side income opportunities?"
+
+Your objective is to be a proactive partner who adds value, not just a passive note-taker.
+"""
+
+# =============================================================================
+# Agent Factory
+# =============================================================================
+
+def create_agent(
+    storage: AbstractTodoStorage,
+    agent_name: str = "To-Do Agent"
+):
+    """Factory function to create a new To-Do Agent instance.
+    
+    This centralizes agent configuration and makes it easy to create
+    consistent instances across different parts of the application.
+
+    Args:
+        storage: An instance of a storage class (e.g., JsonTodoStorage).
+        agent_name: The name for the agent instance.
+    """
+    # OpenAI: Add minimal metadata that appears in OpenAI Platform traces
+    import os
+    os.environ.setdefault("OPENAI_TRACE_TAGS", f"app-name:todo-agent,environment:production,agent-type:conversational")
+    
+    return Agent(
+        name=agent_name,
+        model="gpt-4.1-mini",
+        instructions=AGENT_PROMPT,
+        tools=get_tools(storage),
+    )
+
+# Default agent instance using file-based storage for CLI usage
+agent = create_agent(JsonTodoStorage()) 

data/seed_todos.json

@@ -0,0 +1,20 @@
+[
+  {
+    "id": 1,
+    "name": "Plan a vacation",
+    "description": "Need to decide on a destination.",
+    "project": "Travel",
+    "completed": false,
+    "created_at": "2025-07-01T12:00:00+00:00",
+    "updated_at": "2025-07-01T12:00:00+00:00"
+  },
+  {
+    "id": 2,
+    "name": "Buy a new laptop",
+    "description": "Current one is getting slow. Need to research models.",
+    "project": "Personal Tech",
+    "completed": false,
+    "created_at": "2025-07-01T12:01:00+00:00",
+    "updated_at": "2025-07-01T12:01:00+00:00"
+  }
+] 

instructional_docs/agent_mermaid_diagram.md

@@ -0,0 +1,14 @@
+```mermaid
+graph TD;
+    UserInput["User Input<br/>e.g., 'add buy milk'"] --> MainLoop["main.py: Main Loop"];
+    MainLoop -- "Captures input &<br/>manages history" --> Runner["main.py: Agent Runner"];
+    Runner -- "Invokes agent" --> Agent["agent/todo_agent.py: Agent (LLM + Prompt)"];
+    Agent -- "Decides to use a tool" --> ToolSelection["agent/todo_agent.py: Tool Selection<br/>e.g., create_todo"];
+    ToolSelection -- "Executes function" --> ToolFunction["agent/todo_agent.py: Tool Function<br/>create_todo(...)"];
+    ToolFunction -- "Calls storage layer" --> Storage["agent/storage.py: TodoStorage"];
+    Storage -- "Reads/writes file" --> Data["data/todos.json"];
+    ToolFunction -- "Returns result" --> Agent;
+    Agent -- "Formulates final response" --> Runner;
+    Runner -- "Returns output" --> MainLoop;
+    MainLoop -- "Prints to console" --> AgentOutput["Agent Output<br/>e.g., 'Created to-do...'"];
+```

instructional_docs/article_draft.md

@@ -0,0 +1,178 @@
+
+# Out-of-the-Box Observability: OpenAI, Phoenix, and Weave Compared
+
+Hey fellow MLOps practitioners, here's the reality: when you're working with foundation models, you're essentially flying blind unless you have proper observability. The catch? Most teams think they need to build complex custom tracking from scratch. **Plot twist: you don't.**
+
+Three major platforms—OpenAI's native tracing, Arize Phoenix, and W&B Weave—give you powerful observability capabilities right out of the box. With just a few lines of setup code, you get detailed traces, spans, and metrics that would take weeks to build yourself. But here's the question: which platform gives you the best default experience?
+
+I spent time testing all three with a simple multi-tool agent, and the results surprised me. Each platform has a distinct personality when it comes to out-of-the-box observability—from OpenAI's clean simplicity to Phoenix's analytics depth to Weave's collaboration focus. In this post, I'll show you exactly what each platform gives you by default, so you can pick the right one for your workflow without reinventing the wheel.
+
+Let's dive into what you actually get for free (or nearly free) when it comes to foundation model observability.
+
+---
+
+## Part 1: Test Case - Multi-Tool Agent Architecture
+
+I built this simple CRUD to-do agent to mimic the kind of multi-tool workflows we see in production—like an overworked intern juggling database ops and quick web searches. It's powered by `gpt-4.1-mini`, with a detailed prompt for reasoning, tools for task management, and persistent storage.
+
+### Quick-Start: Run the Agent
+
+Get it running locally in minutes:
+
+```bash
+git clone https://github.com/leowalker89/todo-agent.git
+cd todo-agent
+uv sync # Install deps with uv
+cp .env.example .env # Add your API keys
+uv run main.py
+```
+
+Now you're ready to test commands like 'Add a task to research MLOps tools.'
+
+### Why This Makes a Good Test Case
+
+This agent combines LLM reasoning, tool selection, and multi-step execution—perfect for evaluating what each platform shows you by default. In production terms, it's like a lightweight RAG system: vague user input → tool calls → refined output.
+
+### Core Components
+
+- **Model**: `gpt-4.1-mini` for cost-effective intelligence.
+- **Prompt**: Guides proactive task management.
+- **Tools**:
+  - `create_todo`: Add tasks.
+  - `read_todos`: List or filter tasks.
+  - `update_todo`: Modify tasks (e.g., mark complete).
+  - `delete_todo`: Remove tasks.
+  - `web_search`: Research to clarify vague requests.
+
+### Execution Flow
+
+The agent interprets your request, selects tools, executes them, and responds—mirroring real MLOps pipelines where observability becomes crucial for understanding what's happening under the hood.
+
+---
+
+## Part 2: Traces & Spans: The Building Blocks
+
+Before we dive into what each platform gives you, let's quickly cover the fundamentals. Understanding traces and spans is key to appreciating what these platforms deliver out-of-the-box.
+
+### What is a Trace?
+
+A trace is the full execution record of a single workflow, documenting every step from input to output. Think of it as your AI's 'flight recorder'—essential for understanding what happened when things go sideways.
+
+### Breaking It Down: Spans
+
+Each trace consists of spans, which are isolated steps in the process. For our agent, a typical trace might include:
+1. **Input Processing**: The LLM interprets the user's request.
+2. **Tool Selection & Execution**: Calling tools like `web_search` or `update_todo`.
+3. **Output Generation**: Formulating the final response.
+
+### Key Metadata You Get For Free
+
+Here's what all three platforms capture automatically:
+- **Latency**: Time per step (in ms)—crucial for spotting bottlenecks.
+- **Tokens**: Usage and cost—helps with budget tracking.
+- **Input/Output**: Exact data flowing through—perfect for debugging.
+- **Status**: Success or error—basic but expandable.
+- **Tool Calls**: Which tools were selected and their parameters.
+
+The beauty? You don't have to manually instrument any of this. These platforms capture it all with minimal setup.
+
+---
+
+## Part 3: Platform Comparison - What You Get Out of the Box
+
+To test these platforms, I ran the agent's built-in demos—things like article planning and web research—that simulate real MLOps workflows. Here's what each platform delivered with minimal configuration:
+
+### OpenAI Platform
+
+- **Out-of-Box Strengths:** Native integration with OpenAI Agent SDK with zero dependencies. Clean UI optimized for tool call debugging. Real-time trace streaming.
+- **Default Metadata:** Latency, tool calls (input/output), model, tokens (input/output/total), timestamps, request IDs.
+- **Parent/Child Structure:** Clickable trace hierarchy shows agent → tool sequences with clear flow visualization.
+- **Setup:** ~1 line of code
+
+### Arize Phoenix
+
+- **Out-of-Box Strengths:** Model-agnostic platform with waterfall timeline views and automatic bottleneck detection. Built-in cost analytics and session grouping.
+- **Default Metadata:** Workflow names, detailed timings, token counts, cost calculations, span relationships, LLM parameters.
+- **Parent/Child Structure:** Hierarchical waterfall view with automatic parent/child span linking and performance insights.
+- **Setup:** ~2 lines of code
+
+### W&B Weave
+
+- **Out-of-Box Strengths:** Framework-agnostic platform with trace trees and built-in feedback collection systems. Automatic experiment grouping and versioning.
+- **Default Metadata:** Full inputs/outputs, execution status, automatic run grouping, model versions, experiment metadata.
+- **Parent/Child Structure:** Interactive tree view tracking complete workflow → operation → sub-call hierarchies.
+- **Setup:** ~2 lines of code
+
+### Comparison Summary
+
+| Platform | Default Visualization | Key Auto-Captured Metadata | Built-in Collaboration | Setup Lines |
+| --- | --- | --- | --- | --- |
+| OpenAI | Chronological span log | Latency, cost, tool calls | No | ~1 line |
+| Phoenix | Waterfall timeline | Latency, tokens, cost, analytics | No | ~2 lines |
+| W&B Weave | Hierarchical tree view | Inputs, outputs, feedback, experiments | Yes | ~2 lines |
+
+**The Bottom Line:** All three capture core metadata automatically. The differences lie in visualization style, analytics depth, and collaboration features.
+
+---
+
+## Part 4: When to Use What - Out-of-the-Box Recommendations
+
+Based on my experiments, here's when each platform's default capabilities shine:
+
+### For Quick Debugging: OpenAI Platform
+
+- **Why:** Requires no additional dependencies if you're already using the OpenAI Python SDK.
+- **Best Default Feature:** Clean, readable tool call traces.
+- **Trade-off:** Limited analytics depth, but sometimes simple is better.
+- **Perfect When:** You need to quickly verify your agent is working correctly.
+
+### For Rich Analytics: Arize Phoenix
+
+- **Why:** Gives you professional-grade analytics dashboards with minimal configuration.
+- **Best Default Feature:** Automatic waterfall charts that immediately show performance bottlenecks.
+- **Trade-off:** Slightly more setup, but the payoff in insights is immediate.
+- **Perfect When:** You want to understand performance patterns without building custom dashboards.
+
+### For Team Collaboration: W&B Weave
+
+- **Why:** Built-in experiment tracking and team features from day one.
+- **Best Default Feature:** Automatic experiment organization and sharing capabilities.
+- **Trade-off:** More complex interface, but scales with team needs.
+- **Perfect When:** Multiple people need to review and compare agent performance.
+
+### The Hybrid Approach
+
+Here's what I actually do in practice:
+1. **Start with OpenAI** for immediate validation
+2. **Add Phoenix** when I need deeper performance analysis
+3. **Layer in Weave** when working with a team or running experiments
+
+The beauty is that all three have generous free tiers, so you can test their default capabilities without commitment.
+
+---
+
+## When You Outgrow the Defaults
+
+While these out-of-the-box capabilities are impressive, there are scenarios where you'll need custom instrumentation:
+
+- **Custom Metrics**: Domain-specific KPIs like task completion rates or user satisfaction scores
+- **Advanced Analytics**: Complex performance analysis, A/B testing, or custom dashboards  
+- **Specialized Workflows**: Multi-model pipelines, custom evaluation frameworks, or integration with existing monitoring systems
+- **Compliance Requirements**: Specific logging formats, data retention policies, or audit trails
+
+The good news? Starting with these default capabilities gives you a solid foundation to build upon. You'll understand your observability needs better before investing in custom solutions.
+
+---
+
+## Conclusion: The Power of Defaults
+
+Here's the key insight: **you don't need to build observability from scratch**. These platforms give you professional-grade tracing capabilities with just a few lines of setup code. The question isn't whether you should instrument your foundation models—it's which platform's defaults best match your workflow.
+
+Key takeaways:
+- **Start Simple**: OpenAI's built-in tracing gets you 80% of what you need with zero overhead.
+- **Scale Smart**: Phoenix and Weave offer more sophisticated defaults when you need deeper insights.
+- **Mix and Match**: There's no rule saying you can't use multiple platforms—they complement each other well.
+
+The real power here is speed to insight. Instead of spending weeks building custom observability, you can have professional-grade tracing running in minutes. That's time better spent on what actually matters: building better AI.
+
+What's your experience with out-of-the-box observability? Have you found any hidden gems in these platforms' default features? 

instructional_docs/community_voice.md

@@ -0,0 +1,82 @@
+Of course\! Here is a unified guide for your blog post, combining the best of both opinions into a single, actionable reference.
+
+# The Ultimate MLOps Blog Post Guide: Audience, Voice, and Structure
+
+This guide synthesizes key strategies to help you write a compelling and effective blog post for the MLOps community. Use it as a checklist to ensure your content resonates with practitioners and drives engagement.
+
+-----
+
+## 1\. Your Target Audience: The MLOps Practitioner
+
+This profile details who you're writing for, what they care about, and why it matters for your post.
+
+| Dimension | Details | Why It Matters for Your Post |
+| :--- | :--- | :--- |
+| **Primary Roles** | • **ML/MLOps Engineers & Platform Owners** \<br\> • Data Scientists shipping models \<br\> • DevOps/SREs moving into ML \<br\> • Staff/Principal Engineers & Tech Leads | Ground your advice in real-world pipeline challenges and deployment pain points. They've been "paged at 3 a.m." and appreciate solutions that prevent it. |
+| **Experience Level** | **Intermediate to Senior (3-10 years)**. They are "advanced beginners" and up—proficient but not all-knowing. They can `pip install` anything but value guidance on tricky implementations and "gotchas." | Provide a simple on-ramp for context, then dive deep into the technical details. Don't over-explain basics, but don't skip the "why" behind a specific command or parameter. |
+| **Organizational Context** | Start-ups, scale-ups, and cloud-first enterprise teams. They often run on Kubernetes or managed cloud services. | **Show examples that work both locally AND in a CI/CD pipeline.** This duality is crucial for credibility and practical application. |
+| **Geography** | **Global, with hubs in the US & EU.** Think San Francisco, New York, London, Berlin, etc. | Use globally available, open-source tooling. Avoid region-locked services and consider time-zone-friendly collaboration (e.g., linking to a global Slack/Discord). |
+| **Core Motivations** | • **Ship reliable models to production.** This is their primary goal. \<br\> • Keep up with the fast-moving tooling landscape. \<br\> • Learn from peers and share war stories about what works (and what doesn't). | Focus on **actionable patterns** and battle-tested solutions. Frame your post as a shared learning experience. |
+
+-----
+
+## 2\. Voice and Tone: Your Expert-Peer Persona
+
+Speak to your audience like a knowledgeable colleague you'd chat with on Slack—not like a stuffy academic.
+
+  * **Be Conversational, Not Corporate:** Use a witty, direct, and authentic tone. It's okay to use humor and personality, but do it sparingly. **One smart quip per section is plenty.**
+  * **Be Pragmatic, Not Hype-Driven:** Acknowledge trade-offs, limitations, and dependencies. Honesty builds trust. Avoid marketing fluff and overselling your solution as a silver bullet.
+  * **Be Code-First:** Show, don't just tell. Let runnable code snippets do most of the talking. Your prose should provide context, explain the *why* behind the code, and highlight key takeaways.
+  * **Empathize with Shared Pains:** Use relatable scenarios. Phrases like *"We've all been there"* or *"Ever tried explaining to your PM why..."* create an immediate connection.
+
+-----
+
+## 3\. The Perfect Blog Post Structure
+
+Organize your post for maximum clarity and skimmability. Your reader is busy and wants to get to the good stuff—fast.
+
+1.  **The Hook (1-2 Sentences):** Start with a catchy, relatable one-liner that references a common pain point.
+
+      * *Example: "Ever tried explaining to your PM why the 'simple' model update broke prod at 3am? (Spoiler: it's never simple when feature schemas drift.)"*
+
+2.  **The Problem & Solution (1 Paragraph):** Briefly state the problem you're solving in plain English. Then, introduce your solution and what it accomplishes.
+
+      * *Example: "Here's how we built a feature validation pipeline that catches schema changes before they wake you up."*
+
+3.  **The Quick-Start (Code Block):** Give them an immediate win. Provide a copy-pasteable code block that gets them set up in under two minutes.
+
+      * *Example:*
+        ```bash
+        # Quick start
+        pip install feature-guardian
+        feature-guardian init --prod-schema=s3://your-bucket/schema.json
+        ```
+
+4.  **The Implementation Deep-Dive (Bulleted Steps & Code):** This is the core of your post.
+
+      * Use bullet points, numbered lists, and subheadings.
+      * Embed heavily commented code blocks (Python, YAML, Shell).
+      * Use emojis (like ✅) and **bolding** to guide the reader's eye.
+      * Explain the *why* for each key parameter or step.
+
+5.  **Pros, Cons, and Limitations (Bulleted List):** Honestly assess your solution. What are the trade-offs? Where is it still maturing?
+
+6.  **The Call to Action (CTA):** Invite readers to continue the conversation and try it themselves.
+
+      * Link to the full GitHub repo, further tutorials, or a relevant Slack/Discord channel.
+      * Ask for feedback, stories of their own failures, or pull requests.
+
+-----
+
+## 4\. Content & Style Cheat-Sheet
+
+Use this final checklist to polish your post.
+
+| ✅ DO | ❌ DON'T |
+| :--- | :--- |
+| **Provide working code** for specific versions (`Python 3.10+`, etc.). | **Oversell or use marketing hype.** |
+| **Explain the "why"** behind each parameter and decision. | **Write long, fluffy introductions.** Get to the point. |
+| **Share both successes and failures.** Be honest about limitations. | **Assume unlimited budgets or resources.** |
+| **Reference real-world scenarios** and production pain points. | **Use region-locked or proprietary services** without an open-source alternative. |
+| **Add personality** and humor sparingly. | **Over-explain programming basics.** |
+| **Invite community feedback** and discussion. | **Write a "white-paper."** Keep it practical. |

main.py

@@ -0,0 +1,137 @@
+"""
+Entry point for the command-line interface (CLI) of the todo-agent.
+
+This script demonstrates a typical setup for a stateful, conversational agent:
+- Loads environment variables for API keys and configuration.
+- Initializes tracing and observability integrations (Phoenix, Weave).
+- Manages conversation history by saving and loading it from a JSON file.
+- Creates an agent with a file-based storage backend (`JsonTodoStorage`).
+- Runs a loop to interact with the user via the command line.
+"""
+
+# Standard library imports
+import os
+import asyncio
+import json
+
+# Third-party imports
+from dotenv import load_dotenv
+from phoenix.otel import register
+import weave
+from agents import Runner, Agent
+
+# Local application imports
+from agent.todo_agent import create_agent
+from agent.storage import JsonTodoStorage
+
+# --- Initial Setup ---
+# Load environment variables from a .env file. This is a best practice for
+# managing secrets and configuration without hardcoding them in the source code.
+load_dotenv()
+
+# --- Tracing & Observation Setup ---
+# Initialize integrations to observe and debug the agent's behavior.
+# This is crucial for understanding the agent's decision-making process.
+
+def initialize_tracing():
+    """Initialize tracing with graceful error handling."""
+    os.environ["OPENAI_TRACING_ENABLED"] = "1"
+    os.environ["WEAVE_PRINT_CALL_LINK"] = "false"
+    
+    # Phoenix: Add minimal custom resource attributes via environment variable
+    os.environ["OTEL_RESOURCE_ATTRIBUTES"] = "app.name=todo-agent,tutorial.type=production,environment=production,interface=cli"
+    
+    try:
+        register(project_name="todo-agent-cli", auto_instrument=True)
+        print("✅ Phoenix tracing initialized for: todo-agent-cli")
+    except Exception as e:
+        print(f"⚠️  Phoenix tracing failed: {e}")
+    
+    if not weave.get_client():
+        try:
+            weave.init("todo-agent-cli")
+            print("✅ Weave tracing initialized for: todo-agent-cli")
+        except Exception as e:
+            print(f"⚠️  Weave tracing failed (continuing without Weave): {e}")
+
+initialize_tracing()
+
+# -----------------------------------------------------------------------------
+# Session Management
+#
+# To create a stateful conversation, we save/load the message history
+# to a JSON file, allowing the agent to "remember" past interactions.
+# -----------------------------------------------------------------------------
+SESSION_FILE = "data/session_default.json"
+MAX_TURNS = 12 # Max *user* turns to keep in history to prevent token overflow.
+
+def load_session() -> list:
+    """Loads the message history from the session file."""
+    try:
+        with open(SESSION_FILE, "r") as f:
+            data = json.load(f)
+        # Return the history if it exists, otherwise an empty list.
+        return data.get("history", [])
+    except (FileNotFoundError, json.JSONDecodeError):
+        # If the file doesn't exist or is empty/corrupt, start a new session.
+        return []
+
+def save_session(history: list):
+    """Saves the message history to the session file."""
+    # Ensure the 'data' directory exists.
+    os.makedirs(os.path.dirname(SESSION_FILE), exist_ok=True)
+    with open(SESSION_FILE, "w") as f:
+        # Save the history in a structured format.
+        json.dump({"history": history}, f, indent=2)
+
+async def main():
+    # Load the previous conversation history to maintain context.
+    history = load_session()
+    
+    # Create the agent instance using the central factory,
+    # providing it with the file-based storage system.
+    agent = create_agent(
+        storage=JsonTodoStorage(),
+        agent_name="To-Do Agent (CLI)"
+    )
+    print("To-Do Agent (CLI) is ready. Tracing is enabled. Type 'exit' to quit.")
+    
+    # Start the main interaction loop.
+    while True:
+        user_input = input("\nYou: ")
+        if user_input.strip().lower() in ("exit", "quit"):
+            print("Goodbye!")
+            break
+        
+        # Add the new user message to the history.
+        history.append({"role": "user", "content": user_input})
+
+        # --- Context Window Management ---
+        # To prevent token overflow, we trim the history to the last `MAX_TURNS`.
+        user_message_indices = [i for i, msg in enumerate(history) if msg.get("role") == "user"]
+        if len(user_message_indices) > MAX_TURNS:
+            # Find the index of the oldest user message to keep.
+            start_index = user_message_indices[-MAX_TURNS]
+            print(f"(Trimming conversation history to the last {MAX_TURNS} turns...)")
+            history = history[start_index:]
+
+        # --- Agent Execution ---
+        # The Runner handles the conversation turn, calling tools and the LLM.
+        result = await Runner.run(
+            agent,
+            input=history,
+        )
+        print("----"*10)
+        print(f"Agent: {result.final_output}")
+        print("===="*10)
+        
+        # The agent's result contains the full, updated history (user, assistant, tools).
+        # We replace our local history with this to prepare for the next turn.
+        history = result.to_input_list()
+        
+        # Save the updated history to disk to maintain state for the next session.
+        save_session(history)
+
+if __name__ == "__main__":
+    # Run the asynchronous main function.
+    asyncio.run(main()) 

manage.py

@@ -0,0 +1,74 @@
+# Main entry point for data management tasks.
+
+"""
+Management script for the todo-agent project.
+
+Provides CLI commands for common administrative tasks like resetting data,
+seeding the database, and running evaluations.
+"""
+
+import typer
+import json
+import os
+
+app = typer.Typer(
+    help="A CLI for managing the to-do agent application.",
+    add_completion=False
+)
+
+TODOS_PATH = os.path.join("data", "todos.json")
+SESSION_PATH = os.path.join("data", "session_default.json")
+DEFAULT_SEED_PATH = os.path.join("data", "seed_todos.json")
+
+@app.command()
+def reset(
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt.")
+):
+    """
+    Resets the to-do list and session history to a clean state.
+    """
+    if not yes:
+        confirm = typer.confirm("Are you sure you want to delete all to-dos and session history?")
+        if not confirm:
+            print("Aborting.")
+            raise typer.Abort()
+    
+    # Reset todos.json to an empty list
+    with open(TODOS_PATH, "w") as f:
+        json.dump([], f)
+    
+    # Reset session_default.json to an empty history
+    with open(SESSION_PATH, "w") as f:
+        json.dump({"history": []}, f)
+        
+    print("✅ To-do list and session history have been reset.")
+
+
+@app.command()
+def seed(
+    file_path: str = typer.Argument(DEFAULT_SEED_PATH, help="Path to the seed JSON file.")
+):
+    """
+    Seeds the to-do list with data from a JSON file.
+    
+    This command will overwrite the current to-do list.
+    """
+    # If a filename is provided without a directory, assume it's in the data/ directory.
+    if not os.path.dirname(file_path):
+        file_path = os.path.join("data", file_path)
+
+    if not os.path.exists(file_path):
+        print(f"Error: Seed file not found at '{file_path}'")
+        raise typer.Exit(code=1)
+        
+    with open(file_path, "r") as f:
+        seed_data = json.load(f)
+    
+    with open(TODOS_PATH, "w") as f:
+        json.dump(seed_data, f, indent=2)
+    
+    print(f"✅ To-do list has been seeded from '{file_path}'.")
+
+
+if __name__ == "__main__":
+    app() 

pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "todo-agent"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "arize-phoenix-otel>=0.12.1",
+    "openai-agents>=0.1.0",
+    "openai>=1.93.0",
+    "pydantic>=2.11.7",
+    "python-dotenv>=1.1.1",
+    "weave>=0.51.54",
+    "arize-phoenix>=11.2.0",
+    "openinference-instrumentation-openai-agents>=0.1.14",
+    "typer[all]>=0.16.0",
+    "gradio>=5.35.0",
+    "pandas>=2.3.0",
+]

requirements.txt

@@ -0,0 +1,140 @@
+aiofiles==24.1.0
+aiohappyeyeballs==2.6.1
+aiohttp==3.12.13
+aioitertools==0.12.0
+aiosignal==1.3.2
+aiosqlite==0.21.0
+alembic==1.16.2
+annotated-types==0.7.0
+anyio==4.9.0
+arize-phoenix==11.2.0
+arize-phoenix-client==1.11.0
+arize-phoenix-evals==0.21.0
+arize-phoenix-otel==0.12.1
+attrs==25.3.0
+authlib==1.6.0
+backoff==2.2.1
+cachetools==6.1.0
+certifi==2025.6.15
+cffi==1.17.1
+charset-normalizer==3.4.2
+click==8.2.1
+colorama==0.4.6
+cryptography==45.0.4
+diskcache==5.6.3
+distro==1.9.0
+dnspython==2.7.0
+email-validator==2.2.0
+emoji==2.14.1
+fastapi==0.115.14
+ffmpy==0.6.0
+filelock==3.18.0
+frozenlist==1.7.0
+fsspec==2025.5.1
+gitdb==4.0.12
+gitpython==3.1.44
+googleapis-common-protos==1.70.0
+gql==3.5.3
+gradio==5.35.0
+gradio-client==1.10.4
+graphql-core==3.2.6
+greenlet==3.2.3
+griffe==1.7.3
+groovy==0.1.2
+grpc-interceptor==0.15.4
+grpcio==1.73.1
+h11==0.16.0
+hf-xet==1.1.5
+httpcore==1.0.9
+httpx==0.28.1
+httpx-sse==0.4.1
+huggingface-hub==0.33.2
+idna==3.10
+importlib-metadata==8.7.0
+jinja2==3.1.6
+jiter==0.10.0
+joblib==1.5.1
+jsonschema==4.24.0
+jsonschema-specifications==2025.4.1
+mako==1.3.10
+markdown-it-py==3.0.0
+markupsafe==3.0.2
+mcp==1.10.1
+mdurl==0.1.2
+multidict==6.6.3
+nest-asyncio==1.6.0
+numpy==2.3.1
+openai==1.93.0
+openai-agents==0.1.0
+openinference-instrumentation==0.1.34
+openinference-instrumentation-openai-agents==0.1.14
+openinference-semantic-conventions==0.1.21
+opentelemetry-api==1.34.1
+opentelemetry-exporter-otlp==1.34.1
+opentelemetry-exporter-otlp-proto-common==1.34.1
+opentelemetry-exporter-otlp-proto-grpc==1.34.1
+opentelemetry-exporter-otlp-proto-http==1.34.1
+opentelemetry-instrumentation==0.55b1
+opentelemetry-proto==1.34.1
+opentelemetry-sdk==1.34.1
+opentelemetry-semantic-conventions==0.55b1
+orjson==3.10.18
+packaging==25.0
+pandas==2.3.0
+pandas-stubs==2.3.0.250703
+pillow==11.3.0
+platformdirs==4.3.8
+propcache==0.3.2
+protobuf==5.29.5
+psutil==7.0.0
+pyarrow==20.0.0
+pycparser==2.22
+pydantic==2.11.7
+pydantic-core==2.33.2
+pydantic-settings==2.10.1
+pydub==0.25.1
+pygments==2.19.2
+python-dateutil==2.9.0.post0
+python-dotenv==1.1.1
+python-multipart==0.0.20
+pytz==2025.2
+pyyaml==6.0.2
+referencing==0.36.2
+requests==2.32.4
+requests-toolbelt==1.0.0
+rich==14.0.0
+rpds-py==0.25.1
+ruff==0.12.2
+safehttpx==0.1.6
+scikit-learn==1.7.0
+scipy==1.16.0
+semantic-version==2.10.0
+sentry-sdk==2.32.0
+setproctitle==1.3.6
+shellingham==1.5.4
+six==1.17.0
+smmap==5.0.2
+sniffio==1.3.1
+sqlalchemy==2.0.41
+sqlean-py==3.49.1
+sse-starlette==2.3.6
+starlette==0.46.2
+strawberry-graphql==0.270.1
+tenacity==9.1.2
+threadpoolctl==3.6.0
+tomlkit==0.13.3
+tqdm==4.67.1
+typer==0.16.0
+types-pytz==2025.2.0.20250516
+types-requests==2.32.4.20250611
+typing-extensions==4.14.0
+typing-inspection==0.4.1
+tzdata==2025.2
+urllib3==2.5.0
+uvicorn==0.35.0
+wandb==0.20.1
+weave==0.51.54
+websockets==15.0.1
+wrapt==1.17.2
+yarl==1.20.1
+zipp==3.23.0

tests/README.md

@@ -0,0 +1,146 @@
+# Todo-Agent Tutorial Series
+
+Progressive tutorial series for mastering AI agent workflows through realistic article planning.
+
+## 🎓 Tutorial Series
+
+| Tutorial | Description | What You Learn |
+|----------|-------------|----------------|
+| `test_basic_crud.py` | **Article Foundation Setup** | Essential CRUD operations while planning observability article structure |
+| `test_web_search_brainstorming.py` | **Platform Research & Planning** | Web search integration for researching observability platforms |
+| `test_natural_language.py` | **Project Completion Prep** | Natural language flexibility for finishing article tasks |
+
+## 🚀 Running the Tutorials
+
+### Complete Tutorial Series (Recommended)
+```bash
+uv run tests/run_demo_tests.py
+```
+
+### Individual Tutorials
+```bash
+# 1. Basic CRUD Tutorial - Learn essential operations
+uv run tests/run_demo_tests.py basic
+
+# 2. Platform Research Tutorial - Web search workflow
+uv run tests/run_demo_tests.py research
+
+# 3. Natural Language Tutorial - Casual conversation
+uv run tests/run_demo_tests.py language
+```
+
+### Additional Options
+```bash
+# Generate tutorial report from existing logs
+uv run tests/run_demo_tests.py --report
+```
+
+### Direct Tutorial Execution
+```bash
+uv run tests/test_basic_crud.py
+uv run tests/test_web_search_brainstorming.py
+uv run tests/test_natural_language.py
+```
+
+## 📚 Tutorial Learning Progression
+
+### 1. Basic CRUD Tutorial (4 turns)
+**Goal**: Learn essential todo operations while setting up article structure
+- Create structured writing tasks with descriptions
+- Organize tasks by project for better workflow  
+- Update task status and add progress notes
+- Build article foundations systematically
+
+**Focus**: Observability platforms comparison article planning
+
+### 2. Platform Research Tutorial (4 turns)
+**Goal**: Research workflow → structured task creation
+- **Turn 1**: Search "Arize Phoenix Cloud main benefits" → 2 paragraph summary
+- **Turn 2**: Search "Weights & Biases Weave main benefits" → 2 paragraph summary  
+- **Turn 3**: Search "OpenAI platform observability features" → 2 paragraph summary
+- **Turn 4**: Convert research into structured writing tasks
+
+**Focus**: Research stays in chat history, todos become actionable writing tasks
+
+### 3. Natural Language Tutorial (4 turns)
+**Goal**: Project completion with casual, natural conversation
+- Handle typos gracefully ('everthing' → 'everything')
+- Process casual language: 'hey', 'lemme see', 'gotta make sure'
+- Context understanding: 'that proofreading task' references previous todo
+- Natural conversation flow with task modifications
+
+**Focus**: Finishing article with editing and publishing tasks
+
+## 📊 Tutorial Logging & Reporting
+
+Each tutorial automatically logs structured results with:
+- Tutorial execution time and duration
+- Turn-by-turn conversation tracking
+- Learning objectives and outcomes
+- Pass/fail status with detailed error reporting
+- Automatic tutorial report generation
+
+### Tutorial Logs Location
+- `tests/logs/test_results.jsonl` - Individual tutorial results
+- `tests/logs/test_suite_results.jsonl` - Tutorial series summaries
+- `tests/logs/test_report.md` - Human-readable tutorial report
+
+### Understanding Tutorial Results
+Each tutorial includes minimal validation (basic sanity checks):
+- All tutorials: Simply verify that some todos were created during the conversation
+- **Real evaluation happens in your tracing dashboards** - use the observability tools to assess quality and performance
+
+## 🔄 Data Management
+
+### When Data Gets Reset
+- All tutorials: Each tutorial automatically resets data before running for clean results
+- Individual tutorials: Run with fresh data every time
+- Tutorial series: Each tutorial in the series gets fresh data
+
+### Data Persistence
+- During tutorials: Data accumulates naturally through the tutorial conversation
+- After tutorials: Data persists in `data/` directory for inspection
+- Logs: Tutorial results and reports are preserved in `tests/logs/`
+
+### Manual Data Control
+```bash
+uv run python -c "
+import os, json
+os.makedirs('data', exist_ok=True)
+with open('data/todos.json', 'w') as f: json.dump([], f)
+with open('data/session_default.json', 'w') as f: json.dump({'history': []}, f)
+"
+```
+
+## 🔍 Observability & Tracing
+
+Each tutorial uses separate tracing projects for clean observation:
+- OpenAI Platform: Native tracing enabled
+- Arize Phoenix Cloud: Projects `todo-agent-crud-tutorial`, `todo-agent-research-tutorial`, `todo-agent-language-tutorial`
+- W&B Weave: Individual tracking for each tutorial
+
+Check your tracing dashboards to see:
+- Agent decision-making process and tool usage patterns
+- Web search API calls and response processing
+- Natural language interpretation and normalization
+- Performance metrics across different conversation styles
+
+## 🎯 Learning Objectives
+
+This tutorial series teaches core AI engineering concepts through realistic workflows:
+
+1. **Agent Architecture**: How to build conversational AI for content creation and project management
+2. **Tool Design Patterns**: CRUD operations, web search integration, and schema validation
+3. ****Observability First**: Use tracing dashboards to evaluate agent quality, not hardcoded validation
+4. **Workflow Management**: Multi-project organization and realistic task progression patterns
+5. **Natural Language Processing**: Handling casual input, typos, and collaborative interactions
+
+## 💡 Key Takeaways
+
+- **Progressive Learning**: Each tutorial builds on the previous, from basic operations to advanced workflows
+- **Realistic Scenarios**: Actually plan an observability article while learning agent capabilities
+- **Observability Over Validation**: Use tracing dashboards to evaluate agent quality, not rigid programmatic checks
+- **Natural Language Robustness**: Agents handle casual input, typos, and informal language gracefully  
+- **Research Integration**: Web search becomes structured task planning, not information dumping
+- **Educational Value**: Learn AI engineering concepts through practical, hands-on tutorials
+

tests/run_demo_tests.py

@@ -0,0 +1,146 @@
+"""
+Test Runner for Todo Agent Tutorials
+Runs the progressive AI agent tutorial series with console-based reporting.
+"""
+
+import os
+import json
+import asyncio
+import argparse
+from datetime import datetime
+from pathlib import Path
+from test_basic_crud import run_basic_crud_test
+from test_web_search_brainstorming import run_web_search_test
+from test_natural_language import run_natural_language_test
+from opentelemetry import trace
+
+
+def reset_data():
+    """Reset todos and session data for clean test runs."""
+    os.makedirs("data", exist_ok=True)
+    
+    with open("data/todos.json", "w") as f:
+        json.dump([], f)
+    
+    with open("data/session_default.json", "w") as f:
+        json.dump({"history": []}, f)
+    
+    print("🔄 Data reset - starting with clean slate")
+
+
+async def run_tutorial(tutorial_name):
+    """Run a specific tutorial with timing."""
+    start_time = datetime.now()
+    
+    print(f"\n🔄 Starting {tutorial_name.replace('_', ' ').title()}")
+    print("-" * 40)
+    
+    try:
+        if tutorial_name == "basic":
+            success = await run_basic_crud_test()
+        elif tutorial_name == "research":
+            success = await run_web_search_test()
+        elif tutorial_name == "language":
+            success = await run_natural_language_test()
+        else:
+            print(f"❌ Unknown tutorial: {tutorial_name}")
+            print("Available tutorials: basic, research, language, all")
+            return False
+            
+        end_time = datetime.now()
+        duration = (end_time - start_time).total_seconds()
+        
+        status = "✅ PASSED" if success else "❌ FAILED"
+        print(f"{status} {tutorial_name.replace('_', ' ').title()} ({duration:.1f}s)")
+        
+        return success
+        
+    except Exception as e:
+        end_time = datetime.now()
+        duration = (end_time - start_time).total_seconds()
+        print(f"❌ {tutorial_name.replace('_', ' ').title()} failed with error: {e} ({duration:.1f}s)")
+        return False
+
+
+async def run_all_tutorials():
+    """Run all tutorials in sequence with timing."""
+    suite_start_time = datetime.now()
+    
+    print("🚀 Running All Todo Agent Tutorials")
+    print("=" * 60)
+    print("🎓 Progressive tutorial series for AI agent mastery:")
+    print("• Writing Article Foundation: Essential CRUD operations")
+    print("• Observability Platform Research: Web search workflow")
+    print("• Finishing Article Project: Natural language conversation")
+    print("=" * 60)
+    
+    tutorials = [
+        ("basic", "Writing Article Foundation"),
+        ("research", "Observability Platform Research"),
+        ("language", "Finishing Article Project")
+    ]
+    
+    results = []
+    
+    for tutorial_name, tutorial_description in tutorials:
+        try:
+            success = await run_tutorial(tutorial_name)
+            results.append({"name": tutorial_name, "description": tutorial_description, "success": success})
+                
+        except Exception as e:
+            print(f"❌ {tutorial_description} failed with error: {e}")
+            results.append({"name": tutorial_name, "description": tutorial_description, "success": False})
+        
+        # Shutdown tracer for re-initialization
+        trace.get_tracer_provider().shutdown()
+        await asyncio.sleep(1)
+    
+    suite_end_time = datetime.now()
+    suite_duration = (suite_end_time - suite_start_time).total_seconds()
+    passed = sum(1 for r in results if r["success"])
+    total = len(results)
+    
+    print("\n" + "=" * 60)
+    print("📊 Tutorial Series Results")
+    print("=" * 60)
+    
+    for result in results:
+        status = "✅ PASSED" if result["success"] else "❌ FAILED"
+        print(f"{status} {result['description']}")
+    
+    success_rate = (passed / total * 100) if total > 0 else 0
+    print(f"\n📈 Overall: {passed}/{total} tutorials completed successfully")
+    print(f"🎯 Success Rate: {success_rate:.1f}%")
+    print(f"⏱️  Total Duration: {suite_duration:.1f}s")
+    
+    if passed == total:
+        print("\n🎉 Tutorial series complete! You've mastered the todo agent!")
+    else:
+        print("\n🔧 Some tutorials had issues - check the output above for details.")
+    
+    return passed == total
+
+
+async def main():
+    """Main entry point."""
+    parser = argparse.ArgumentParser(description="Run todo-agent tutorial series")
+    parser.add_argument(
+        "tutorial", 
+        nargs="?", 
+        choices=["basic", "research", "language", "all"], 
+        default="all", 
+        help="Tutorial to run: basic, research, language, or all (default: all)"
+    )
+    
+    args = parser.parse_args()
+    
+    if args.tutorial == "all":
+        success = await run_all_tutorials()
+    else:
+        success = await run_tutorial(args.tutorial)
+    
+    exit(0 if success else 1)
+
+
+if __name__ == "__main__":
+    asyncio.run(main()) 

tests/test_basic_crud.py

@@ -0,0 +1,195 @@
+"""
+Basic CRUD Operations Test
+Tutorial: Learn core todo app operations while planning an observability article.
+"""
+
+import os
+import sys
+import asyncio
+import json
+from pathlib import Path
+from datetime import datetime
+from dotenv import load_dotenv
+from phoenix.otel import register
+import weave
+from agents import Runner, Agent
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from agent.todo_agent import create_agent
+from agent.storage import JsonTodoStorage
+
+
+def reset_test_data():
+    """Reset todos and session data for clean test runs."""
+    os.makedirs("data", exist_ok=True)
+    
+    with open("data/todos.json", "w") as f:
+        json.dump([], f)
+    
+    with open("data/session_default.json", "w") as f:
+        json.dump({"history": []}, f)
+    
+    print("🔄 Data reset - starting with clean slate")
+
+
+
+def initialize_tracing(project_name: str):
+    """Initialize tracing with graceful error handling."""
+    os.environ["OPENAI_TRACING_ENABLED"] = "1"
+    os.environ["WEAVE_PRINT_CALL_LINK"] = "false"
+    
+    # Phoenix: Add minimal custom resource attributes via environment variable
+    os.environ["OTEL_RESOURCE_ATTRIBUTES"] = f"tutorial.name={project_name},tutorial.type=basic_crud,environment=test,app.name=todo-agent"
+    
+    try:
+        register(project_name=project_name, auto_instrument=True)
+        print(f"✅ Phoenix tracing initialized for: {project_name}")
+    except Exception as e:
+        print(f"⚠️  Phoenix tracing failed: {e}")
+    
+    if not weave.get_client():
+        try:
+            weave.init(project_name)
+            print(f"✅ Weave tracing initialized for: {project_name}")
+        except Exception as e:
+            print(f"⚠️  Weave tracing failed (continuing without Weave): {e}")
+
+
+async def run_basic_crud_test():
+    """Tutorial: Set up article structure while learning essential todo operations."""
+    start_time = datetime.now()
+    test_details = {
+        "turns": 0,
+        "validation_results": {},
+        "errors": []
+    }
+    
+    try:
+        reset_test_data()
+        
+        load_dotenv()
+        
+        initialize_tracing("writing-article-foundation")
+        
+        agent = create_agent(storage=JsonTodoStorage(), agent_name="To-Do Agent (Article Planning)")
+
+        print("🧪 Starting Basic CRUD Tutorial")
+        print("=" * 50)
+        print("🎯 Learn: Essential todo operations while planning an article")
+        print("📚 Foundation: Set up observability platforms comparison article")
+        
+        test_messages = [
+            # === Article Structure Setup ===
+            "Add 'Write introduction to agent observability' to my Writing project with description 'Explain why observability matters for AI agents'",
+            
+            # === Platform Sections ===
+            "Add these platform sections to Writing project: 'Create OpenAI platform overview', 'Write Arize Phoenix analysis', and 'Add Weights & Biases Weave section'",
+            
+            # === Progress Check ===
+            "Show me my Writing project tasks",
+            
+            # === Status Updates ===
+            "Mark 'Create OpenAI platform overview' as in progress since I'm starting research on that section",
+            
+            # === Description Enhancement ===
+            "Update the description for 'Write Arize Phoenix analysis' to include 'Focus on cloud deployment benefits and trace visualization features'",
+            
+            # === Final Completion ===
+            "Mark 'Write introduction to agent observability' as completed and add note 'Finished 300-word intro explaining the importance of observability'"
+        ]
+        
+        history = []
+        
+        # Weave: Add minimal context attributes for this tutorial session  
+        with weave.attributes({'tutorial_type': 'basic_crud', 'environment': 'test', 'app_name': 'todo-agent', 'tutorial_name': 'writing-article-foundation'}):
+            for i, message in enumerate(test_messages, 1):
+                print(f"\n--- Tutorial Step {i} ---")
+                print(f"User: {message}")
+                
+                history.append({"role": "user", "content": message})
+                result = await Runner.run(agent, input=history)
+                
+                print(f"Agent: {result.final_output}")
+                history = result.to_input_list()
+                
+                await asyncio.sleep(0.5)
+        
+        test_details["turns"] = len(test_messages)
+        
+        print("\n" + "=" * 50)
+        print("🎓 Basic CRUD Tutorial Complete")
+        
+        validation_success = True
+        
+        try:
+            with open("data/todos.json", "r") as f:
+                todos = json.load(f)
+            
+            total_todos = len(todos)
+            completed_todos = len([t for t in todos if t and t.get('status') == 'Completed'])
+            in_progress_todos = len([t for t in todos if t and t.get('status') == 'In Progress'])
+            test_details["validation_results"]["total_todos"] = total_todos
+            test_details["validation_results"]["completed_todos"] = completed_todos
+            test_details["validation_results"]["in_progress_todos"] = in_progress_todos
+            
+            print(f"\n📊 Article Foundation: {total_todos} sections planned, {completed_todos} completed, {in_progress_todos} in progress")
+            
+            for todo in todos:
+                if not todo or not isinstance(todo, dict):
+                    continue
+                    
+                status = todo.get('status', 'Not Started')
+                name = todo.get('name', 'Unnamed Task')
+                
+                if status == 'Completed':
+                    status_emoji = "✅"
+                elif status == 'In Progress':
+                    status_emoji = "🚧"
+                else:
+                    status_emoji = "📝"
+                    
+                print(f"  {status_emoji} {name}")
+                if todo.get('project'):
+                    print(f"    Project: {todo['project']}")
+                if todo.get('description'):
+                    desc = todo['description']
+                    print(f"    Description: {desc[:60]}{'...' if len(desc) > 60 else ''}")
+            
+        except FileNotFoundError:
+            validation_success = False
+            error_msg = "No todos.json file found"
+            test_details["errors"].append(error_msg)
+            print(f"❌ {error_msg}")
+        
+        overall_success = validation_success and len(test_details["errors"]) == 0
+        
+        print(f"\n🎓 What You Learned:")
+        print("• Create structured writing tasks with clear descriptions")
+        print("• Organize tasks by project for better workflow")
+        print("• Update task status (Not Started → In Progress → Completed)")
+        print("• Enhance descriptions and add progress notes")
+        print("• Comprehensive CRUD operations on all todo fields")
+        print("🚀 Next: Try the web search tutorial to research platform details!")
+        
+        end_time = datetime.now()
+        duration = (end_time - start_time).total_seconds()
+        
+        if overall_success:
+            print(f"\n✅ TUTORIAL PASSED: Article foundation ready! ({duration:.1f}s)")
+        else:
+            print(f"\n❌ TUTORIAL FAILED: Check setup and try again ({duration:.1f}s)")
+        
+        return overall_success
+        
+    except Exception as e:
+        end_time = datetime.now()
+        duration = (end_time - start_time).total_seconds()
+        print(f"\n❌ TUTORIAL FAILED: {str(e)} ({duration:.1f}s)")
+        return False
+
+
+
+
+if __name__ == "__main__":
+    success = asyncio.run(run_basic_crud_test())
+    exit(0 if success else 1) 

tests/test_natural_language.py

@@ -0,0 +1,177 @@
+"""
+Natural Language Project Completion Test
+Tutorial: Finish article project using natural language with typos and casual conversation.
+"""
+
+import os
+import sys
+import asyncio
+import json
+from pathlib import Path
+from datetime import datetime
+from dotenv import load_dotenv
+from phoenix.otel import register
+import weave
+from agents import Runner, Agent
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from agent.todo_agent import create_agent
+from agent.storage import JsonTodoStorage
+
+
+def reset_test_data():
+    """Reset todos and session data for clean test runs."""
+    os.makedirs("data", exist_ok=True)
+    
+    with open("data/todos.json", "w") as f:
+        json.dump([], f)
+    
+    with open("data/session_default.json", "w") as f:
+        json.dump({"history": []}, f)
+    
+    print("🔄 Data reset - starting with clean slate")
+
+
+
+
+def initialize_tracing(project_name: str):
+    """Initialize tracing with graceful error handling."""
+    os.environ["OPENAI_TRACING_ENABLED"] = "1"
+    os.environ["WEAVE_PRINT_CALL_LINK"] = "false"
+    
+    # Phoenix: Add minimal custom resource attributes via environment variable
+    os.environ["OTEL_RESOURCE_ATTRIBUTES"] = f"tutorial.name={project_name},tutorial.type=natural_language,environment=test,app.name=todo-agent"
+    
+    try:
+        register(project_name=project_name, auto_instrument=True)
+        print(f"✅ Phoenix tracing initialized for: {project_name}")
+    except Exception as e:
+        print(f"⚠️  Phoenix tracing failed: {e}")
+    
+    if not weave.get_client():
+        try:
+            weave.init(project_name)
+            print(f"✅ Weave tracing initialized for: {project_name}")
+        except Exception as e:
+            print(f"⚠️  Weave tracing failed (continuing without Weave): {e}")
+
+
+async def run_natural_language_test():
+    """Tutorial: Complete article project using casual, natural language."""
+    start_time = datetime.now()
+    test_details = {
+        "turns": 0,
+        "validation_results": {},
+        "errors": []
+    }
+    
+    try:
+        reset_test_data()
+        
+        load_dotenv()
+        
+        initialize_tracing("finishing-article-project")
+        
+        agent = create_agent(storage=JsonTodoStorage(), agent_name="To-Do Agent (Article Completion)")
+
+        print("🧪 Starting Natural Language Project Completion Tutorial")
+        print("=" * 50)
+        print("🎯 Learn: Natural conversation with typos and casual language")
+        print("📚 Goal: Finish observability article with editing and publishing tasks")
+        
+        test_messages = [
+            # === Casual task additions with typos ===
+            "hey, add 'write conclusion section' and 'proofread everthing' to my Writing project - getting close to finishing this article",
+            
+            # === Natural editing and context ===
+            "actually change that proofreading task to 'final review and editing' - sounds more professional",
+            
+            # === Publishing tasks with informal language ===
+            "also add 'create code examples' and 'format for publication' to my Publishing project - gotta make sure the examples actually work",
+            
+            # === Check final status ===
+            "lemme see what we have for the Writing project now"
+        ]
+        
+        history = []
+        
+        # Weave: Add minimal context attributes for this tutorial session
+        with weave.attributes({'tutorial_type': 'natural_language', 'environment': 'test', 'app_name': 'todo-agent', 'tutorial_name': 'language-completion-tutorial'}):
+            for i, message in enumerate(test_messages, 1):
+                print(f"\n--- Completion Step {i} ---")
+                print(f"User: {message}")
+                
+                history.append({"role": "user", "content": message})
+                result = await Runner.run(agent, input=history)
+                
+                print(f"Agent: {result.final_output}")
+                history = result.to_input_list()
+                
+                await asyncio.sleep(0.5)
+        
+        test_details["turns"] = len(test_messages)
+        
+        print("\n" + "=" * 50)
+        print("🎓 Natural Language Project Completion Tutorial Complete")
+        
+        validation_success = True
+        
+        try:
+            with open("data/todos.json", "r") as f:
+                todos = json.load(f)
+            
+            total_todos = len(todos)
+            test_details["validation_results"]["total_todos"] = total_todos
+            
+            projects = set(t.get('project') for t in todos if t.get('project'))
+            test_details["validation_results"]["projects"] = sorted(list(projects))
+            
+            print(f"\n📊 Article Completion: {total_todos} finishing tasks across {len(projects)} projects")
+            
+            project_groups = {}
+            for todo in todos:
+                project = todo.get('project') or 'No Project'
+                if project not in project_groups:
+                    project_groups[project] = []
+                project_groups[project].append(todo)
+            
+            for project, project_todos in sorted(project_groups.items()):
+                print(f"\n📂 {project}:")
+                for todo in project_todos:
+                    print(f"  • {todo['name']}")
+            
+        except FileNotFoundError:
+            validation_success = False
+            error_msg = "No todos.json file found"
+            test_details["errors"].append(error_msg)
+            print(f"❌ {error_msg}")
+        
+        overall_success = validation_success and len(test_details["errors"]) == 0
+        
+        print(f"\n🎓 What You Learned:")
+        print("• Agent handles typos gracefully ('everthing' → 'everything')")
+        print("• Natural conversation flow with task modifications")  
+        print("• Casual language processing: 'hey', 'lemme see', 'gotta make sure'")
+        print("• Context understanding: 'that proofreading task' references previous todo")
+        print("🎉 Tutorial Series Complete: You've mastered todo agent workflows!")
+        
+        end_time = datetime.now()
+        duration = (end_time - start_time).total_seconds()
+        
+        if overall_success:
+            print(f"\n✅ TUTORIAL PASSED: Natural language mastery achieved! ({duration:.1f}s)")
+        else:
+            print(f"\n❌ TUTORIAL FAILED: Language processing needs work ({duration:.1f}s)")
+        
+        return overall_success
+        
+    except Exception as e:
+        end_time = datetime.now()
+        duration = (end_time - start_time).total_seconds()
+        print(f"\n❌ TUTORIAL FAILED: {str(e)} ({duration:.1f}s)")
+        return False
+
+
+if __name__ == "__main__":
+    success = asyncio.run(run_natural_language_test())
+    exit(0 if success else 1) 

tests/test_web_search_brainstorming.py

@@ -0,0 +1,177 @@
+"""
+Web Search Platform Research Test
+Tutorial: Research observability platforms and convert findings into writing tasks.
+"""
+
+import os
+import sys
+import asyncio
+import json
+from pathlib import Path
+from datetime import datetime
+from dotenv import load_dotenv
+from phoenix.otel import register
+import weave
+from agents import Runner, Agent
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from agent.todo_agent import create_agent
+from agent.storage import JsonTodoStorage
+
+
+def reset_test_data():
+    """Reset todos and session data for clean test runs."""
+    os.makedirs("data", exist_ok=True)
+    
+    with open("data/todos.json", "w") as f:
+        json.dump([], f)
+    
+    with open("data/session_default.json", "w") as f:
+        json.dump({"history": []}, f)
+    
+    print("🔄 Data reset - starting with clean slate")
+
+
+
+
+def initialize_tracing(project_name: str):
+    """Initialize tracing with graceful error handling."""
+    os.environ["OPENAI_TRACING_ENABLED"] = "1"
+    os.environ["WEAVE_PRINT_CALL_LINK"] = "false"
+    
+    # Phoenix: Add minimal custom resource attributes via environment variable
+    os.environ["OTEL_RESOURCE_ATTRIBUTES"] = f"tutorial.name={project_name},tutorial.type=web_search,environment=test,app.name=todo-agent"
+    
+    try:
+        register(project_name=project_name, auto_instrument=True)
+        print(f"✅ Phoenix tracing initialized for: {project_name}")
+    except Exception as e:
+        print(f"⚠️  Phoenix tracing failed: {e}")
+    
+    if not weave.get_client():
+        try:
+            weave.init(project_name)
+            print(f"✅ Weave tracing initialized for: {project_name}")
+        except Exception as e:
+            print(f"⚠️  Weave tracing failed (continuing without Weave): {e}")
+
+
+async def run_web_search_test():
+    """Tutorial: Research platforms and create structured writing tasks."""
+    start_time = datetime.now()
+    test_details = {
+        "turns": 0,
+        "validation_results": {},
+        "errors": []
+    }
+    
+    try:
+        reset_test_data()
+        
+        load_dotenv()
+        
+        initialize_tracing("observability-platform-research")
+        
+        agent = create_agent(storage=JsonTodoStorage(), agent_name="To-Do Agent (Platform Research)")
+
+        print("🧪 Starting Web Search Platform Research Tutorial")
+        print("=" * 50)
+        print("🎯 Learn: Research workflow → structured task creation")
+        print("📚 Goal: Compare observability platforms for AI agents")
+        
+        test_messages = [
+            # === Platform Research (3 searches with guided responses) ===
+            "Search for 'Arize Phoenix Cloud main benefits agent observability' and give me a brief 2 paragraph summary",
+            
+            "Search for 'Weights & Biases Weave main benefits agent tracing' and give me a brief 2 paragraph summary",
+            
+            "Search for 'OpenAI platform observability features benefits' and give me a brief 2 paragraph summary",
+            
+            # === Convert Research to Tasks ===
+            "Based on this research, please add writing tasks to my 'Platform Comparison' project for comparing these platforms - I need specific tasks I can work on"
+        ]
+        
+        history = []
+        
+        # Weave: Add minimal context attributes for this tutorial session
+        with weave.attributes({'tutorial_type': 'web_search', 'environment': 'test', 'app_name': 'todo-agent', 'tutorial_name': 'platform-research-tutorial'}):
+            for i, message in enumerate(test_messages, 1):
+                print(f"\n--- Research Step {i} ---")
+                print(f"User: {message}")
+                
+                history.append({"role": "user", "content": message})
+                result = await Runner.run(agent, input=history)
+                
+                print(f"Agent: {result.final_output}")
+                history = result.to_input_list()
+                
+                await asyncio.sleep(0.5)
+        
+        test_details["turns"] = len(test_messages)
+        
+        print("\n" + "=" * 50)
+        print("🎓 Platform Research Tutorial Complete")
+        
+        validation_success = True
+        
+        try:
+            with open("data/todos.json", "r") as f:
+                todos = json.load(f)
+            
+            total_todos = len(todos)
+            test_details["validation_results"]["total_todos"] = total_todos
+            
+            # Research tutorial should create at least 3 writing tasks
+            if total_todos < 3:
+                validation_success = False
+                error_msg = f"Expected at least 3 writing tasks from research, got {total_todos}"
+                test_details["errors"].append(error_msg)
+                print(f"❌ {error_msg}")
+            
+            print(f"\n📊 Research Results: {total_todos} writing tasks created from platform research")
+            
+            for i, todo in enumerate(todos, 1):
+                if not todo or not isinstance(todo, dict):
+                    continue
+                name = todo.get('name', 'Unnamed Task')
+                print(f"{i}. {name}")
+                if todo.get('description'):
+                    print(f"   Description: {todo['description']}")
+                if todo.get('project'):
+                    print(f"   Project: {todo['project']}")
+            
+        except FileNotFoundError:
+            validation_success = False
+            error_msg = "No todos.json file found"
+            test_details["errors"].append(error_msg)
+            print(f"❌ {error_msg}")
+        
+        overall_success = validation_success and len(test_details["errors"]) == 0
+        
+        print(f"\n🎓 What You Learned:")
+        print("• Web search integration for research workflows")  
+        print("• Converting research findings into structured writing tasks")
+        print("• Multi-platform comparison methodology")
+        print("• Research stays in chat history, todos are actionable tasks")
+        print("🚀 Next: Try the natural language tutorial for project finishing touches!")
+        
+        end_time = datetime.now()
+        duration = (end_time - start_time).total_seconds()
+        
+        if overall_success:
+            print(f"\n✅ TUTORIAL PASSED: Platform research complete! ({duration:.1f}s)")
+        else:
+            print(f"\n❌ TUTORIAL FAILED: Research workflow needs attention ({duration:.1f}s)")
+        
+        return overall_success
+        
+    except Exception as e:
+        end_time = datetime.now()
+        duration = (end_time - start_time).total_seconds()
+        print(f"\n❌ TUTORIAL FAILED: {str(e)} ({duration:.1f}s)")
+        return False
+
+
+if __name__ == "__main__":
+    success = asyncio.run(run_web_search_test())
+    exit(0 if success else 1) 

todo_gradio/gradio_app.py

@@ -0,0 +1,160 @@
+import os
+import pandas as pd
+from typing import List, Optional, Any, Dict
+from datetime import datetime, timezone
+import gradio as gr
+from agents import Agent, function_tool, RunContextWrapper, WebSearchTool, Runner
+from phoenix.otel import register
+import weave
+
+# Add parent directory to path for local imports
+import sys
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+from agent.todo_agent import create_agent
+from agent.storage import InMemoryTodoStorage, TodoStatus
+
+def initialize_tracing():
+    """Initializes Phoenix and Weave tracing for the application."""
+    project_name = "todo-agent-gradio"
+
+    os.environ["OPENAI_TRACING_ENABLED"] = "1"
+    os.environ["WEAVE_PRINT_CALL_LINK"] = "false"
+    
+    # Phoenix: Add minimal custom resource attributes via environment variable
+    os.environ["OTEL_RESOURCE_ATTRIBUTES"] = f"app.name=todo-agent,tutorial.type=production,environment=production,interface=gradio"
+
+    # Prevent re-initialization on hot-reload
+    if not weave.get_client():
+        try:
+            register(project_name=project_name, auto_instrument=True)
+            weave.init(project_name=project_name)
+            print(f"Tracing initialized for project: '{project_name}'")
+        except Exception as e:
+            print(
+                f"Warning: Tracing initialization failed. The app will work, but traces will not be captured. Error: {e}"
+            )
+
+initialize_tracing()
+
+def format_todos_for_display(todos: list) -> pd.DataFrame:
+    """
+    Formats the to-do list for display in the Gradio DataFrame.
+    This is a "ViewModel" transformation, adapting the data model for the UI.
+    """
+    if not todos:
+        return pd.DataFrame(columns=["ID", "Status", "Task", "Details", "Project", "Created"])
+    
+    df = pd.DataFrame([t.model_dump() for t in todos])
+    
+    # Rename for user-friendly headers
+    df.rename(columns={
+        'id': 'ID',
+        'name': 'Task',
+        'description': 'Details',
+        'project': 'Project',
+        'status': 'Status',
+        'created_at': 'Created'
+    }, inplace=True)
+    
+    df['Created'] = pd.to_datetime(df['Created']).dt.strftime('%Y-%m-%d %H:%M')
+    df['Project'] = df['Project'].fillna('')
+    
+    display_df = df[['ID', 'Status', 'Task', 'Details', 'Project', 'Created']]
+    
+    return display_df
+
+async def agent_chat(user_input: str, chat_history: list, storage_instance: InMemoryTodoStorage):
+    """Handles chat interaction between user and agent."""
+    chat_history.append({"role": "user", "content": user_input})
+    
+    agent = create_agent(
+        storage=storage_instance,
+        agent_name="To-Do Agent (Gradio)"
+    )
+
+    result = await Runner.run(agent, input=chat_history)
+    full_history = result.to_input_list()
+    
+    # Hide raw tool calls in display
+    display_history = []
+    for msg in full_history:
+        role = msg.get("role")
+        content = msg.get("content")
+        
+        if role == "user":
+            display_history.append(msg)
+        elif role == "assistant":
+            if content:
+                display_content = ""
+                # Handle streaming response chunks
+                if isinstance(content, list):
+                    display_content = "".join(chunk.get('text', '') for chunk in content if isinstance(chunk, dict))
+                elif isinstance(content, dict) and 'text' in content:
+                    display_content = content['text']
+                else:
+                    display_content = str(content)
+                
+                if display_content:
+                    display_history.append({"role": "assistant", "content": display_content})
+            elif msg.get("tool_calls"):
+                display_history.append({"role": "assistant", "content": "🛠️ Thinking..."})
+    
+    todos = storage_instance.read_all()
+    df = format_todos_for_display(todos)
+        
+    return "", display_history, full_history, storage_instance, df
+
+async def refresh_todos_df(storage_instance: InMemoryTodoStorage):
+    """Callback to manually refresh the to-do list display."""
+    todos = storage_instance.read_all()
+    return format_todos_for_display(todos)
+
+with gr.Blocks(theme=gr.themes.Soft(), title="To-Do Agent") as demo:
+    gr.Markdown("# To-Do Agent")
+    gr.Markdown("Manage your to-do list with an AI assistant. The agent can create, read, update, and delete tasks. It can also use web search to help you flesh out your ideas.")
+    
+    storage_state = gr.State(InMemoryTodoStorage)
+    chat_history_state = gr.State([])
+    
+    with gr.Row():
+        with gr.Column(scale=2):
+            gr.Markdown("### To-Do List")
+            todo_df = gr.DataFrame(
+                interactive=False, 
+                wrap=True,
+                column_widths=["5%", "15%", "25%", "30%", "10%", "15%"]
+            )
+            refresh_button = gr.Button("Refresh List")
+        
+        with gr.Column(scale=1):
+            gr.Markdown("### Chat")
+            chatbot = gr.Chatbot(label="To-Do Agent Chat", type="messages", height=500)
+            with gr.Row():
+                user_input_box = gr.Textbox(placeholder="Type your message here...", show_label=False, scale=4)
+                send_button = gr.Button("Send", variant="primary", scale=1)
+
+    send_button.click(
+        agent_chat,
+        inputs=[user_input_box, chat_history_state, storage_state],
+        outputs=[user_input_box, chatbot, chat_history_state, storage_state, todo_df]
+    )
+    user_input_box.submit(
+        agent_chat,
+        inputs=[user_input_box, chat_history_state, storage_state],
+        outputs=[user_input_box, chatbot, chat_history_state, storage_state, todo_df]
+    )
+    refresh_button.click(
+        refresh_todos_df,
+        inputs=[storage_state],
+        outputs=[todo_df]
+    )
+    
+    def initial_load():
+        """Returns the initial state for the UI components."""
+        return format_todos_for_display([]), [], InMemoryTodoStorage()
+    
+    demo.load(initial_load, None, [todo_df, chatbot, storage_state])
+
+
+if __name__ == "__main__":
+    demo.launch()