LADDER 🪜

LADDER is a Python package for generating datasets for RL. It uses LLMs to generate easier sub-problems of base problems, essentially achieving hierarchical RL by creating a tree of problem difficulties. Based on the LADDER paper.

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/username/ladder.git
cd ladder

# Install with uv (recommended)
uv sync --dev

Basic Usage

Generate variants for a single integral

import asyncio
from ladder import process_integral

async def main():
    integral = "integrate(x**2 + 2*x + 1, x)"
    difficulties = ["easier", "equivalent", "harder"]
    
    variants = await process_integral(
        integral, 
        difficulties, 
        num_variants=5
    )
    
    for variant in variants:
        print(f"Difficulty: {variant['requested_difficulty']}")
        print(f"Variant: {variant['variant']}")
        print(f"Verified: {variant['verification_passed']}")
        print("---")

asyncio.run(main())

Batch processing multiple integrals

import asyncio
from ladder import BatchGenerator

async def main():
    integrals = [
        "integrate(sin(x), x)",
        "integrate(x**2, x)",
        "integrate(1/(x**2 + 1), x)"
    ]
    
    generator = BatchGenerator(
        batch_size=2,
        difficulties={"easier": 10, "equivalent": 5}
    )
    
    variants = await generator.process_all_integrals(
        integrals,
        output_dir="results",
        save_combined=True
    )
    
    generator.print_summary(variants)

asyncio.run(main())

🛠️ Development

Setup Development Environment

# Install development dependencies
python setup_dev.py install

# Or manually
pip install -e ".[dev]"

Code Quality

# Run all quality checks (format, lint, type-check, test)
python setup_dev.py all

# Individual commands
python setup_dev.py format      # Format code
python setup_dev.py lint        # Run linting
python setup_dev.py type-check  # Run type checking
python setup_dev.py test        # Run tests
python setup_dev.py clean       # Clean build artifacts

Project Structure

ladder/
├── ladder/                  # Main package
│   ├── __init__.py         # Package exports
│   ├── generate_variants.py # Core variant generation
│   ├── batch_generator.py  # Batch processing
│   ├── cli.py             # Command-line interface
│   ├── questions/         # Question datasets
│   └── utils/             # Utility modules
├── tests/                 # Test suite
├── docs/                  # Documentation  
├── pyproject.toml        # Modern Python packaging
└── README.md            # This file

📚 API Reference

Core Functions

process_integral(integral_str, difficulties, num_variants=3)

Generate variants for a single integral.

Parameters:

• integral_str (str): The integral expression in sympy format
• difficulties (List[str]): List of difficulty levels ("easier", "equivalent", "harder")
• num_variants (int): Number of variants per difficulty level

Returns:

• List[Dict]: List of variant dictionaries with metadata

BatchGenerator(batch_size=10, difficulties=None)

Class for processing multiple integrals in batches.

Parameters:

• batch_size (int): Number of integrals to process concurrently
• difficulties (Dict[str, int]): Mapping of difficulty levels to variant counts

Configuration

Set up API keys in environment variables:

export OPENAI_API_KEY="your-openai-key"
export ANTHROPIC_API_KEY="your-anthropic-key"
export DEEPSEEK_API_KEY="your-deepseek-key"
# ... other API keys

🧪 Testing

The project includes comprehensive tests:

# Run all tests
pytest

# Run with coverage
pytest --cov=ladder --cov-report=html

# Run specific test categories
pytest -m unit          # Unit tests only
pytest -m integration   # Integration tests only
pytest -m "not slow"    # Skip slow tests

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes and add tests
4. Run the quality checks (python setup_dev.py all)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📖 Citation

If you use LADDER in your research, please cite:

@article{ladder2024,
  title={LADDER: Integration Problem Generator and Dataset Builder},
  author={Your Name},
  journal={arXiv preprint arXiv:2503.00735},
  year={2024}
}

🙏 Acknowledgments

• Built with modern Python packaging standards
• Inspired by mathematical problem generation research
• Uses various AI models for creative variant generation