CLAUDE.md

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

uv sync                    # Install/sync dependencies

Running the Application

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

Testing

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

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

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