File size: 3,341 Bytes
30f018f | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 | # 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 |