# Oshun AI Integration Exercises

Hands-on exercises for mastering the Oshun AI provider integrations. These
exercises are designed to build skills progressively from beginner to advanced.

## Exercise Structure

### Beginner Level (`01-beginner-*.ts`)

Foundation skills for working with AI providers:

| Exercise | Topics |
|----------|--------|
| 1. Initialization | Provider setup, configuration |
| 2. Basic TTS | Synthesis, voice settings, voice listing |
| 3. Basic Images | Workflow execution, job management |
| 4. Model Discovery | Search, filtering, model details |
| 5. Error Handling | Safe operations, error classification, retry |
| 6. Monitoring | Statistics, health checks, reporting |

**Time estimate:** 2-3 hours

### Intermediate Level (`02-intermediate-*.ts`)

Production patterns and resilience:

| Exercise | Topics |
|----------|--------|
| 1. Streaming | Real-time audio, buffering |
| 2. Batch Processing | Parallel execution, rate limiting, cancellation |
| 3. Error Handling | Exponential backoff, circuit breaker, fallback |
| 4. Resource Management | Connection pooling, cleanup |
| 5. Monitoring | Metrics collection, health monitoring |
| 6. Caching | LRU cache, memoization |

**Time estimate:** 4-6 hours

### Advanced Level (`03-advanced-*.ts`)

Production-grade systems:

| Exercise | Topics |
|----------|--------|
| 1. Orchestration | Smart routing, workflow DAGs |
| 2. Fault Tolerance | Bulkhead pattern, adaptive retry |
| 3. Observability | Distributed tracing, dashboards |
| 4. Optimization | Deduplication, predictive prefetching |
| 5. Security | Audit logging, quota management |
| 6. Integration | Complete AI pipeline |

**Time estimate:** 8-12 hours

## Getting Started

### Prerequisites

1. Complete the code examples review
2. Set up environment variables:
   ```bash
   export ELEVENLABS_API_KEY=your_key
   export RUNCOMFY_API_KEY=your_key
   export CIVITAI_API_KEY=your_key
   ```

### Running Exercises

```bash
# Run beginner exercise tests
npx ts-node docs/training/exercises/01-beginner-exercises.ts

# Run intermediate exercise tests
npx ts-node docs/training/exercises/02-intermediate-exercises.ts

# Run advanced exercise tests
npx ts-node docs/training/exercises/03-advanced-exercises.ts
```

### Exercise Format

Each exercise file contains:

1. **Exercise function stubs** - Functions you need to implement
2. **Requirements** - What the implementation must do
3. **Tests** - Automated tests to verify your solution
4. **Solutions** - Reference implementations (in separate files)

Example:

```typescript
/**
 * Exercise 1.1: Description
 *
 * Requirements:
 * - Requirement 1
 * - Requirement 2
 * - Requirement 3
 *
 * @param param1 - Description
 * @returns Description
 */
export function exercise_1_1_name(param1: Type): ReturnType {
  // YOUR CODE HERE
  throw new Error('Not implemented');
}
```

## Recommended Learning Path

### Week 1: Foundations

1. **Day 1-2**: Complete beginner exercises 1-3
2. **Day 3-4**: Complete beginner exercises 4-6
3. **Day 5**: Review solutions, practice variations

### Week 2: Production Patterns

1. **Day 1-2**: Complete intermediate exercises 1-2
2. **Day 3-4**: Complete intermediate exercises 3-4
3. **Day 5**: Complete intermediate exercises 5-6

### Week 3: Advanced Concepts

1. **Day 1-2**: Complete advanced exercises 1-2
2. **Day 3-4**: Complete advanced exercises 3-4
3. **Day 5**: Complete advanced exercises 5-6

## Tips for Success

### Before Starting

- Read the exercise description completely
- Understand all requirements before coding
- Review related examples if needed

### While Implementing

- Start with the simplest case
- Add complexity incrementally
- Test frequently with small inputs
- Use console.log for debugging

### When Stuck

- Re-read the requirements carefully
- Check the examples for similar patterns
- Review the solution file for hints
- Take a break and return fresh

### After Completing

- Compare with the reference solution
- Note alternative approaches
- Consider edge cases you might have missed
- Refactor for clarity if needed

## Self-Assessment

After completing all exercises, you should be able to:

### Beginner Level
- [ ] Initialize any provider with proper configuration
- [ ] Synthesize speech with custom voice settings
- [ ] Execute image generation workflows
- [ ] Search and filter models
- [ ] Handle errors gracefully
- [ ] Monitor provider health

### Intermediate Level
- [ ] Implement streaming audio synthesis
- [ ] Process batches with concurrency control
- [ ] Implement retry with exponential backoff
- [ ] Build a circuit breaker
- [ ] Create a connection pool
- [ ] Implement an LRU cache

### Advanced Level
- [ ] Build a multi-provider router
- [ ] Orchestrate complex workflows
- [ ] Implement distributed tracing
- [ ] Optimize with deduplication
- [ ] Create audit logging
- [ ] Build a complete AI pipeline

## Exercise Solutions

Solutions are provided in separate files:

- `01-beginner-solutions.ts`
- `02-intermediate-solutions.ts`
- `03-advanced-solutions.ts` (partial - advanced exercises are open-ended)

**Important:** Try to complete exercises before checking solutions. The learning
comes from the struggle, not just seeing the answer.

## Additional Challenges

After completing all exercises, try these challenges:

### Challenge 1: Multi-Modal Pipeline
Build a pipeline that takes a text story, generates images for key scenes,
and creates an audio narration.

### Challenge 2: Cost Optimizer
Create a system that automatically selects providers based on a cost budget,
balancing quality with expense.

### Challenge 3: A/B Testing Framework
Build a framework for A/B testing different models/providers and tracking
quality metrics.

### Challenge 4: Webhook Integration
Implement webhook handlers for long-running jobs, including retry logic and
state management.

### Challenge 5: Rate Limit Coordinator
Build a coordinator that manages rate limits across multiple concurrent
processes.

## Contributing

To add new exercises:

1. Follow the existing format and naming convention
2. Include clear requirements and documentation
3. Provide comprehensive tests
4. Include reference solutions
5. Update this README

## Related Resources

- [Code Examples](../examples/README.md)
- [Workshop Materials](../workshops/README.md)
- [Video Tutorial Scripts](../videos/README.md)