# Ralphloop - Technical Specification
## 1. Overview
Ralphloop is a command-line tool for creating and executing Ralphiloops - structured, iterative workflows powered by Large Language Models (LLMs).
## 📋 Table of Contents
1. [System Requirements](#system-requirements)
2. [Functional Requirements](#functional-requirements)
3. [Non-Functional Requirements](#non-functional-requirements)
4. [Data Specifications](#data-specifications)
5. [API Specifications](#api-specifications)
6. [Error Specifications](#error-specifications)
7. [Security Specifications](#security-specifications)
8. [Performance Specifications](#performance-specifications)
9. [Testing Specifications](#testing-specifications)
## 🔧 System Requirements
### Supported Platforms
| Linux | x86_64, ARM64 | Kernel 3.10+ | ✅ Tested |
| macOS | x86_64, Apple Silicon | macOS 10.15+ | ✅ Tested |
| Windows | x86_64 | Windows 10+ | ✅ Tested |
### Dependencies
**Runtime Dependencies:**
- None (single binary distribution)
**Build Dependencies:**
- Rust 1.70+ (edition 2021)
- Cargo package manager
- Optional: OpenSSL for local builds (for TLS support)
**System Resources:**
- **Minimum RAM**: 64MB
- **Recommended RAM**: 256MB
- **Disk Space**: 10MB for binary, 1-100MB for loops
- **Network**: Internet connection for cloud LLM providers
## 🎯 Functional Requirements
### FR-001: Loop Management
**Requirement:** The system shall allow users to create, modify, and execute Ralphiloops.
**Acceptance Criteria:**
- User can create a loop from scratch
- User can create a loop from a template
- User can modify existing loops
- User can execute loops with specified iteration count
- System validates loop syntax before execution
**Priority:** Critical
### FR-002: Multi-Provider Support
**Requirement:** The system shall support multiple LLM providers with unified interface.
**Provider Matrix:**
| OpenAI | GPT-3.5, GPT-4, GPT-4-Turbo | API Key | Streaming, Functions |
| Anthropic | Claude-3 family | API Key | Streaming, Tool Use |
| Google | Gemini Pro | API Key | Streaming |
| Local | Ollama, Llama.cpp | None | Custom endpoints |
**Priority:** Critical
### FR-003: Variable System
**Requirement:** The system shall support dynamic variable substitution and context management.
**Variable Types:**
- **Input Variables**: User-defined constants
- **Context Variables**: Outputs from previous steps
- **System Variables**: Iteration count, timestamp
- **Environment Variables**: OS environment variables
**Priority:** High
### FR-004: Template System
**Requirement:** The system shall provide a template system for common workflows.
**Built-in Templates:**
- Code Review
- Content Creation
- Research
- Creative Writing
- Problem Solving
**Priority:** High
### FR-005: Configuration Management
**Requirement:** The system shall provide secure configuration management with multiple profiles.
**Configuration Features:**
- Multiple named profiles
- Environment variable overrides
- Secure API key storage
- Provider-specific settings
**Priority:** Critical
### FR-006: Dependency Resolution
**Requirement:** The system shall resolve step dependencies and execute in correct order.
**Dependency Rules:**
- Circular dependency detection
- Parallel execution where possible
- Dependency graph validation
- Failure propagation handling
**Priority:** High
## 🛡️ Non-Functional Requirements
### NFR-001: Performance
**Requirements:**
- **Startup Time**: < 500ms cold start
- **Loop Execution**: < 2s overhead per step (excluding LLM response time)
- **Memory Usage**: < 256MB for typical loops
- **Concurrent Execution**: Support 10+ simultaneous loops
### NFR-002: Reliability
**Requirements:**
- **Uptime**: 99.9% for local operations
- **Error Recovery**: Graceful handling of network failures
- **Data Integrity**: No data loss during execution
- **Crash Recovery**: Ability to resume interrupted loops
### NFR-003: Security
**Requirements:**
- **API Key Protection**: Encryption at rest
- **Data Privacy**: No sensitive data in logs
- **Input Validation**: Protection against injection attacks
- **Secure Defaults**: Safe default configurations
### NFR-004: Usability
**Requirements:**
- **Learning Curve**: < 30 minutes for basic usage
- **Error Messages**: Clear, actionable error descriptions
- **Documentation**: Complete coverage of all features
- **CLI Consistency**: Follow standard CLI conventions
### NFR-005: Maintainability
**Requirements:**
- **Code Coverage**: > 90% test coverage
- **Documentation**: All public APIs documented
- **Modularity**: Clear separation of concerns
- **Dependencies**: Minimal external dependencies
## 📊 Data Specifications
### Loop Definition Schema
```json
{
"$schema": "https://ralph-cli.org/schema/v1.json",
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$",
"maxLength": 100
},
"description": {
"type": "string",
"maxLength": 500
},
"version": {
"type": "string",
"pattern": "^\\d+\\.\\d+\\.\\d+$"
},
"steps": {
"type": "array",
"items": {
"$ref": "#/definitions/Step"
},
"minItems": 1
},
"variables": {
"type": "object",
"patternProperties": {
"^[a-zA-Z][a-zA-Z0-9_]*$": {
"type": "string"
}
}
},
"context": {
"type": "object",
"additionalProperties": true
},
"metadata": {
"type": "object",
"properties": {
"author": { "type": "string" },
"created": { "type": "string", "format": "date-time" },
"modified": { "type": "string", "format": "date-time" },
"tags": {
"type": "array",
"items": { "type": "string" }
}
}
}
},
"required": ["name", "description", "steps"],
"additionalProperties": false,
"definitions": {
"Step": {
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$"
},
"prompt_template": {
"type": "string",
"minLength": 1
},
"output_variable": {
"type": "string",
"pattern": "^[a-zA-Z][a-zA-Z0-9_]*$"
},
"depends_on": {
"type": "array",
"items": { "type": "string" },
"uniqueItems": true
},
"retry_count": {
"type": "integer",
"minimum": 0,
"maximum": 5,
"default": 0
},
"timeout": {
"type": "integer",
"minimum": 1,
"maximum": 600,
"default": 120
}
},
"required": ["name", "prompt_template"],
"additionalProperties": false
}
}
}
```
### Configuration Schema
```json
{
"$schema": "https://ralph-cli.org/config/v1.json",
"type": "object",
"properties": {
"version": { "type": "string" },
"default_profile": { "type": "string" },
"profiles": {
"type": "object",
"patternProperties": {
"^[a-zA-Z][a-zA-Z0-9_-]*$": {
"$ref": "#/definitions/Profile"
}
}
}
},
"definitions": {
"Profile": {
"type": "object",
"properties": {
"llm_provider": {
"type": "string",
"enum": ["openai", "anthropic", "gemini", "local"]
},
"model": { "type": "string" },
"api_key": { "type": "string" },
"local_endpoint": { "type": "string", "format": "uri" },
"max_tokens": {
"type": "integer",
"minimum": 1,
"maximum": 100000
},
"temperature": {
"type": "number",
"minimum": 0.0,
"maximum": 2.0
},
"timeout": {
"type": "integer",
"minimum": 1,
"maximum": 600
},
"retry_count": {
"type": "integer",
"minimum": 0,
"maximum": 5
}
},
"required": ["llm_provider"]
}
}
}
```
## 🔌 API Specifications
### CLI Command API
#### Create Command
```bash
ralph create <name> [options]
Options:
-t, --template <template> Use a predefined template
-d, --description <desc> Loop description
-o, --output <path> Output file path
-f, --force Overwrite existing file
```
**Return Codes:**
- `0`: Success
- `1`: General error
- `2`: Invalid arguments
- `3`: Template not found
- `4`: File already exists
#### Run Command
```bash
ralph run <path> [options]
Options:
-i, --iterations <count> Number of iterations (default: 1)
-p, --profile <name> Configuration profile
-v, --variables <key=value> Override variables (can be repeated)
-d, --dry-run Show prompts without execution
-q, --quiet Minimal output
```
#### Configure Command
```bash
ralph configure [options]
Options:
-p, --profile <name> Profile name (default: default)
--provider <provider> LLM provider
--model <model> Model name
--api-key <key> API key
--local-endpoint <url> Local endpoint URL
--list-profiles List all profiles
```
### LLM Provider Interface
```rust
#[async_trait]
pub trait LLMProvider: Send + Sync {
/// Complete a prompt and return response
async fn complete(&self, prompt: &str) -> Result<LLMResponse>;
/// Stream completion (optional)
async fn complete_stream(&self, prompt: &str) -> Result<StreamResponse>;
/// Get provider information
fn provider_info(&self) -> ProviderInfo;
/// Validate configuration
fn validate_config(&self) -> Result<()>;
}
pub struct LLMResponse {
pub content: String,
pub model: String,
pub usage: Usage,
pub metadata: HashMap<String, Value>,
}
pub struct Usage {
pub prompt_tokens: u32,
pub completion_tokens: u32,
pub total_tokens: u32,
pub cost: Option<f64>,
}
```
## ❌ Error Specifications
### Error Hierarchy
```
Error
├── ConfigError
│ ├── MissingConfig
│ ├── InvalidConfig
│ └── ProfileNotFound
├── LoopError
│ ├── InvalidSyntax
│ ├── CircularDependency
│ ├── MissingVariable
│ └── StepExecutionFailed
├── ProviderError
│ ├── AuthenticationFailed
│ ├── RateLimited
│ ├── ModelNotFound
│ └── NetworkError
├── TemplateError
│ ├── TemplateNotFound
│ ├── InvalidTemplate
│ └── TemplateSyntaxError
└── IOError
├── FileNotFound
├── PermissionDenied
└── DiskFull
```
### Error Format
```json
{
"error": {
"code": "CIRCULAR_DEPENDENCY",
"message": "Circular dependency detected between steps: analyze -> refine -> analyze",
"details": {
"cycle": ["analyze", "refine", "analyze"],
"loop_file": "my-loop.json"
},
"suggestions": [
"Remove the circular reference",
"Split the loop into separate loops"
],
"timestamp": "2024-03-01T12:00:00Z",
"request_id": "req_123456789"
}
}
```
### Error Recovery Strategies
| Network Timeout | Retry with exponential backoff | None |
| Rate Limit | Wait and retry | None |
| Invalid API Key | Prompt for new key | Yes |
| Loop Syntax Error | Show error location | Yes |
| Circular Dependency | Report cycle | Yes |
## 🔐 Security Specifications
### Threat Model
#### Potential Threats
1. **API Key Exposure**
- **Risk**: Unauthorized access to LLM services
- **Mitigation**: Encryption at rest, no logging
2. **Prompt Injection**
- **Risk**: Malicious input affecting execution
- **Mitigation**: Input validation, sandboxing
3. **Data Leakage**
- **Risk**: Sensitive data in logs or cache
- **Mitigation**: Data filtering, secure cleanup
4. **Code Execution**
- **Risk**: Arbitrary code from untrusted sources
- **Mitigation**: No code execution, prompt-only
#### Security Controls
**Authentication:**
- API keys stored encrypted with system keyring
- Environment variable support for temporary keys
- Key rotation support
**Authorization:**
- Scope-limited API tokens where supported
- Profile-based access control
- Audit logging of sensitive operations
**Data Protection:**
- Zero-knowledge architecture
- Memory sanitization on exit
- No persistent storage of sensitive data
**Network Security:**
- TLS 1.3 for all HTTPS connections
- Certificate validation
- Request timeout enforcement
### Compliance Considerations
**Data Privacy:**
- GDPR compliance for EU users
- CCPA compliance for California users
- Data localization options
**Security Standards:**
- OWASP guidelines for CLI applications
- Secure coding practices
- Regular security audits
## ⚡ Performance Specifications
### Performance Benchmarks
**Startup Performance:**
- Cold start: < 500ms
- Warm start: < 100ms
- Config loading: < 50ms
**Execution Performance:**
- Step overhead: < 100ms
- Variable resolution: < 10ms
- Template rendering: < 5ms
**Memory Usage:**
- Base memory: 64MB
- Per loop: +1-10MB
- Per step: +100KB-1MB
### Resource Limits
**Loop Limits:**
- Maximum steps per loop: 50
- Maximum loop size: 10MB
- Maximum variable size: 1MB
**API Limits:**
- Concurrent requests: 10 per provider
- Request timeout: 120s
- Retry attempts: 3
### Optimization Strategies
**Caching:**
- Template compilation cache
- API response cache (same prompts)
- Configuration cache
**Lazy Loading:**
- Templates loaded on demand
- Providers initialized when used
- Configuration validated when accessed
**Parallel Execution:**
- Independent steps executed concurrently
- Async I/O for all network operations
- Worker pool for CPU-bound tasks
## 🧪 Testing Specifications
### Test Coverage Requirements
**Unit Tests:**
- All public functions: 100% coverage
- Error handling paths: 95% coverage
- Edge cases: 90% coverage
**Integration Tests:**
- CLI commands: 100% coverage
- Provider interfaces: 100% coverage
- File operations: 100% coverage
**End-to-End Tests:**
- Critical workflows: 100% coverage
- Error scenarios: 90% coverage
- Performance tests: 80% coverage
### Test Categories
**Functional Tests:**
- Loop creation and execution
- Template system
- Configuration management
- Provider interactions
**Performance Tests:**
- Load testing
- Memory usage profiling
- Concurrent execution
- Resource cleanup
**Security Tests:**
- API key protection
- Input validation
- Data privacy
- Network security
**Compatibility Tests:**
- Cross-platform compatibility
- Version compatibility
- Provider API compatibility
- Configuration migration
### Test Data
**Mock Data:**
- Sample loop definitions
- Template examples
- Configuration scenarios
- Error responses
**Test Harness:**
- Mock LLM providers
- File system fixtures
- Network simulation
- Time manipulation
### Continuous Testing
**Pre-commit Hooks:**
- Format checking (`cargo fmt`)
- Linting (`cargo clippy`)
- Unit tests (`cargo test`)
**CI Pipeline:**
- All test categories
- Multiple platforms
- Multiple Rust versions
- Security scanning
**Release Testing:**
- Integration tests
- Performance benchmarks
- Security audit
- Documentation validation
---
## 📏 Validation Criteria
### Acceptance Testing
**Critical Path Tests:**
1. Install and configure the CLI
2. Create a loop from template
3. Execute the loop successfully
4. Verify output correctness
5. Handle errors gracefully
**Performance Tests:**
1. Startup time under 500ms
2. Memory usage under 256MB
3. Support 10+ concurrent loops
4. Handle large loops (>10MB)
**Security Tests:**
1. API key encryption verification
2. No sensitive data in logs
3. Input validation effectiveness
4. Network security compliance
### Release Criteria
**Must Have:**
- All tests passing
- Security audit passed
- Performance benchmarks met
- Documentation complete
**Should Have:**
- Integration tests passing
- Cross-platform compatibility
- User acceptance testing
- Performance regression testing
**Nice to Have:**
- Load testing results
- Community feedback
- Third-party security review
- Performance profiling