Examples¶
Learn how to use Ralph Orchestrator through practical examples.
Quick Examples¶
Hello World¶
The simplest possible Ralph task:
# PROMPT.md
Write a Python function that prints "Hello, World!"
Save it to hello.py. The orchestrator will continue iterations until completion.
Run with:
Basic Math Function¶
Generate a calculator module:
# PROMPT.md
Create a Python calculator module with:
- Functions for add, subtract, multiply, divide
- Error handling for division by zero
- Docstrings for all functions
- Save to calculator.py
The orchestrator will continue iterations until complete.
Complete Examples¶
Explore our detailed example guides:
📝 Simple Task¶
Build a command-line todo list application with file persistence.
🌐 Web API¶
Create a RESTful API with Flask, including authentication and database integration.
🛠️ CLI Tool¶
Develop a feature-rich command-line tool with argument parsing and configuration.
📊 Data Analysis¶
Process CSV data, generate statistics, and create visualizations.
Example Categories¶
Code Generation¶
Use Case: Automatically generate boilerplate code, utilities, or entire modules.
Create a Python logging utility with:
- Colored console output
- File rotation
- JSON formatting option
- Multiple log levels
Testing¶
Use Case: Generate comprehensive test suites for existing code.
Write pytest tests for the user_auth.py module:
- Test all public functions
- Include edge cases
- Mock external dependencies
- Aim for 100% coverage
Documentation¶
Use Case: Create or update project documentation.
Generate comprehensive API documentation for this project:
- Document all public classes and functions
- Include usage examples
- Create a getting started guide
- Format as Markdown
Refactoring¶
Use Case: Improve code quality and structure.
Refactor the data_processor.py file:
- Split large functions (>50 lines)
- Extract common patterns
- Add type hints
- Improve variable names
- Maintain functionality
Bug Fixing¶
Use Case: Identify and fix issues in code.
Debug and fix the payment processing module:
- The calculate_tax() function returns wrong values
- Payment status isn't updating correctly
- Add logging to trace the issue
- Write tests to prevent regression
Data Processing¶
Use Case: Transform and analyze data files.
Process sales_data.csv:
- Clean missing values
- Calculate monthly totals
- Find top 10 products
- Generate summary statistics
- Export results to report.json
Best Practices for Examples¶
1. Clear Objectives¶
Always specify exactly what you want:
✅ Good:
Create a REST API endpoint that:
- Accepts POST requests to /api/users
- Validates email and password
- Returns JWT token on success
- Uses SQLite for storage
❌ Bad:
2. Include Constraints¶
Specify limitations and requirements:
Build a web scraper that:
- Uses only standard library (no pip installs)
- Respects robots.txt
- Implements rate limiting (1 request/second)
- Handles errors gracefully
3. Define Success Criteria¶
Make completion conditions explicit:
Task is complete when:
1. All tests pass (run: pytest test_calculator.py)
2. Code follows PEP 8 (run: flake8 calculator.py)
3. Documentation is complete
4. All completion criteria are met
4. Provide Context¶
Include relevant information:
Context: We're building a microservice for order processing.
Existing files: models.py, database.py
Create an order validation module that:
- Integrates with existing models
- Validates against business rules
- Returns detailed error messages
Running Examples¶
Basic Execution¶
With Cost Limits¶
# Limit spending
python ralph_orchestrator.py \
--prompt examples/web-api.md \
--max-cost 5.0 \
--max-tokens 100000
Using Specific Agents¶
# Use Claude for complex tasks
python ralph_orchestrator.py \
--agent claude \
--prompt examples/cli-tool.md
# Use Gemini for research tasks
python ralph_orchestrator.py \
--agent gemini \
--prompt examples/data-analysis.md
Development Mode¶
# Verbose output with frequent checkpoints
python ralph_orchestrator.py \
--prompt examples/simple-task.md \
--verbose \
--checkpoint-interval 1 \
--max-iterations 10
Example Prompt Templates¶
Web Application¶
# Task: Create [Application Name]
## Requirements
- Framework: [Flask/FastAPI/Django]
- Database: [SQLite/PostgreSQL/MongoDB]
- Authentication: [JWT/Session/OAuth]
## Features
1. [Feature 1]
2. [Feature 2]
3. [Feature 3]
## File Structure
## Completion Criteria
- All endpoints working
- Tests passing
- Documentation complete
- All criteria completed
Data Processing¶
# Task: Process [Data Description]
## Input
- File: [filename.csv]
- Format: [CSV/JSON/XML]
- Size: [approximate size]
## Processing Steps
1. [Step 1: Load and validate]
2. [Step 2: Clean and transform]
3. [Step 3: Analyze]
4. [Step 4: Export results]
## Output
- Format: [JSON/CSV/Report]
- Include: [metrics, visualizations, etc.]
## Success Criteria
- No errors during processing
- Output validates against schema
- Performance: < [X] seconds
- All criteria completed
CLI Tool¶
# Task: Build [Tool Name] CLI
## Commands
- `tool command1` - [description]
- `tool command2` - [description]
## Options
- `--option1` - [description]
- `--option2` - [description]
## Requirements
- Argument parsing with argparse
- Configuration file support
- Colored output
- Progress bars for long operations
## Examples
```bash
tool process --input file.txt --output result.json
tool analyze --verbose
Completion¶
- All commands working
- Help text complete
- Error handling robust
- All criteria completed ```
Learning from Examples¶
Study the Patterns¶
- Prompt Structure: How successful prompts are organized
- Iteration Counts: Typical iterations for different task types
- Token Usage: Costs for various complexities
- Completion Time: Expected runtime for tasks
Experiment¶
- Start with provided examples
- Modify them for your needs
- Compare different approaches
- Share successful patterns
Contributing Examples¶
Have a great example? Share it:
- Create a new example file
- Document the use case
- Include expected results
- Submit a pull request
Troubleshooting Examples¶
Task Not Completing¶
If examples run indefinitely: - Check completion criteria clarity - Verify agent can modify files - Review iteration logs - Adjust max iterations
High Costs¶
If examples are expensive: - Use simpler prompts - Set token limits - Choose appropriate agents - Enable context management
Poor Results¶
If output quality is low: - Provide more context - Include examples in prompt - Specify constraints clearly - Use more capable agents
Next Steps¶
- Try the Simple Task Example
- Explore Web API Example
- Build a CLI Tool
- Analyze Data
📚 Continue to Simple Task Example →