# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a constraint satisfaction and scheduling application built with Google OR-Tools and Gradio. The project provides both a web UI and programmatic interfaces for solving task scheduling problems with dependencies and time constraints.

### Core Architecture

- **app.py** - Main Gradio web application with constraint solving logic
- **schedule.py** - Standalone scheduling solver for personal activities 
- **test_app.py** - Test suite for the application logic

The application uses:
- Google OR-Tools CP-SAT solver for constraint satisfaction problems
- Gradio for the web interface
- Mermaid diagrams for schedule visualization
- UV for dependency management and Python execution

## Development Commands

### Environment Setup
```bash
uv sync                    # Install/sync dependencies
```

### Running the Application
```bash
uv run python app.py       # Start Gradio web interface (serves on http://localhost:7860)
uv run python schedule.py  # Run standalone personal scheduler
```

### Testing
```bash
uv run pytest              # Run all tests
uv run pytest test_app.py -v  # Run specific test file with verbose output
```
Note: Some tests are currently failing due to task name normalization changes

### Code Quality
```bash
uv run ruff check app.py   # Lint specific file
uv run ruff format app.py  # Format specific file
uv run ruff check .        # Lint entire project
uv run ruff format .       # Format entire project
```

### Adding Dependencies
```bash
uv add <package>           # Add new dependency to pyproject.toml
```

## Key Functions and Logic

### Task Parsing and Normalization
- `normalize_task_name()` - Converts task names to lowercase with underscores for internal processing
- `parse_requirements()` - Parses dependency strings like "TaskA requires TaskB" into dependency graphs
- `parse_tasks()` - Extracts task lists from comma/newline separated text

### Constraint Solving
- `solve_all_tasks()` - Main CP-SAT solver that schedules all tasks respecting dependencies
- Uses Google OR-Tools constraint programming to find valid task orderings
- Returns ordered task lists or indicates if no solution exists (cyclic dependencies)

### Visualization
- `generate_mermaid_gantt()` - Creates Mermaid Gantt charts from task schedules
- Supports both simple ordering and time-based scheduling with durations

### Gradio Interface
The web UI provides text areas for:
- Task list input (comma or newline separated)
- Requirements/dependencies input 
- Interactive solving and visualization

## Code Conventions

- Uses snake_case for functions and variables
- Type hints encouraged for public APIs
- Ruff for linting/formatting (PEP8 style)
- 4-space indentation, 120-character line limit
- Comprehensive docstrings for public functions

## Development Notes

- The project uses UV instead of pip/venv for faster dependency management
- Tests exist but some are failing due to recent changes in task name handling
- The application can handle cyclic dependency detection
- Both programmatic (schedule.py) and interactive (app.py) interfaces available
- Mermaid diagram generation supports time-based and simple orderings
- try to keep all features accessible from gradio