Ditto

On-the-go data analysis toolkit optimized for Cursor Cloud Agent development.

A lightweight Python package for rapid iteration on data analysis tasks, designed to work seamlessly with Cursor agents. Built with pandas and seaborn for data manipulation and visualization.

Features

• Domain-driven architecture: Organized by domain (NFL, health, research, etc.)
• CLI-first design: Typer-based CLI for interactive analysis
• Caching: Parquet-based caching for efficient data retrieval
• Headless plotting: Seaborn visualizations saved to artifacts/
• Agent-friendly: Startup prompts and templates for Cursor Cloud Agent workflows

Quickstart

Installation

# Install dependencies
pip install -e .

# Or with dev dependencies
pip install -e ".[dev]"

Basic Usage

# Fetch NFL data for a season
ditto nfl fetch --season 2023 --weeks 1,2,3

# Analyze a team's recent performance
ditto nfl analyze --season 2023 --team NYG --window 5

# Generate visualization plots
ditto nfl plot --season 2023 --team NYG --window 5

Development Commands

# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Run tests
pytest tests/ -v

# Clean cache and artifacts
rm -rf data/cache/* artifacts/*

On-the-go Workflow with Cursor Agents

Starting a New Iteration

1. Use the startup prompt: The repository includes a built-in startup workflow in .cursor/startup_prompt.md

2. Run the startup command:

   # In Cursor, use the agent command:
   # "Follow the startup prompt workflow and ask me the 5 questions"

3. Answer the 5 questions:

   • (a) Iteration name (slug) + domain
   • (b) Primary user & success metric
   • (c) Inputs/data sources + constraints
   • (d) Outputs + definition of done
   • (e) Time budget + risk tolerance

4. Automatic setup: The agent will:

   • Generate iterations/<slug>/PRD.md
   • Generate iterations/<slug>/IMPLEMENTATION.md
   • Generate iterations/<slug>/TASKS.md
   • Update README with iteration details
   • Update prompts/commands.yml with defaults

Working with Existing Iterations

• View tasks: Check iterations/<slug>/TASKS.md
• Update progress: Mark tasks complete in TASKS.md
• Run commands: Use the CLI commands defined in the iteration docs

Project Structure

ditto/
├── src/ditto/              # Core package
│   ├── __init__.py
│   ├── cli.py              # CLI entry point
│   ├── core/               # Core utilities
│   │   ├── config.py       # Configuration & paths
│   │   └── io.py           # I/O operations
│   └── domains/            # Domain-specific modules
│       └── nfl/            # NFL analysis domain
│           ├── ingest.py   # Data fetching & caching
│           ├── features.py # Feature engineering
│           ├── models.py   # Data models
│           └── plots.py    # Visualization
├── iterations/             # Iteration documentation
│   └── _template/          # Template files
├── prompts/                # Agent prompts & commands
├── tests/                  # Test suite
├── data/                   # Data storage
│   └── cache/              # Cached data (parquet)
├── artifacts/              # Generated outputs (plots, reports)
└── .cursor/                # Cursor agent configuration

NFL Domain (v0)

The NFL domain provides commands for fetching, analyzing, and visualizing NFL play-by-play data.

Data Sources

• Primary: nflfastpy (requires pip install nflfastpy)
• Fallback: Sample data provider for testing (works offline)

Commands

• ditto nfl fetch --season YEAR [--weeks 1,2,3]: Fetch and cache NFL data
• ditto nfl analyze --season YEAR --team TEAM --window N: Analyze team performance
• ditto nfl plot --season YEAR --team TEAM --window N: Generate visualization plots

Example Workflow

# 1. Fetch data for weeks 1-5 of 2023 season
ditto nfl fetch --season 2023 --weeks 1,2,3,4,5

# 2. Analyze Giants performance over last 3 weeks
ditto nfl analyze --season 2023 --team NYG --window 3

# 3. Generate plots
ditto nfl plot --season 2023 --team NYG --window 3

Code Quality

• File size limit: No file >300 lines
• Pure functions: Core logic separated from I/O
• Testing: Unit tests for pure functions, integration tests for CLI workflows
• Documentation: All modules and functions documented

Contributing

1. Follow the file structure conventions
2. Keep files under 300 lines
3. Write tests for new functionality
4. Update iteration docs as you work

License

MIT