# Oshun AI Integration Training Materials

Comprehensive training resources for developers working with Oshun AI
provider integrations including ElevenLabs, ComfyUI/RunComfy, and Civitai.

## Overview

This training program is designed to take developers from beginners to
experts in building AI-powered applications using the Oshun platform.

```
┌─────────────────────────────────────────────────────────────────┐
│                    Training Path                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌──────────┐    ┌──────────┐    ┌──────────┐                │
│   │ Examples │───▶│Exercises │───▶│Workshops │                │
│   │  (Read)  │    │(Practice)│    │  (Learn) │                │
│   └──────────┘    └──────────┘    └──────────┘                │
│        │               │               │                        │
│        └───────────────┼───────────────┘                        │
│                        ▼                                        │
│                  ┌──────────┐                                   │
│                  │ Videos   │                                   │
│                  │ (Watch)  │                                   │
│                  └──────────┘                                   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

## Training Materials

### [Code Examples](./examples/)

Production-ready code examples demonstrating all aspects of the AI
integrations:

- **ElevenLabs** - Text-to-speech, streaming, voice management, cloning
- **ComfyUI/RunComfy** - Workflow execution, image generation, batch processing
- **Civitai** - Model discovery, image/video generation, LoRA training

### [Hands-on Exercises](./exercises/)

Progressive exercises to build practical skills:

| Level | Focus | Time |
|-------|-------|------|
| Beginner | Fundamentals | 2-3 hours |
| Intermediate | Production patterns | 4-6 hours |
| Advanced | Complex systems | 8-12 hours |

### [Workshops](./workshops/)

Interactive guided sessions:

1. **Getting Started** (2 hours) - Setup and basics
2. **Production Patterns** (3 hours) - Streaming, batching, resilience
3. **Advanced Architecture** (4 hours) - Orchestration, observability

### [Video Tutorials](./videos/)

Scripts for video content (can be used as written guides):

1. Getting Started with Oshun AI (15-20 min)
2. Streaming and Real-Time AI (12-15 min)
3. Batch Processing and Performance (planned)
4. Building Resilient Applications (planned)
5. Complete AI Pipeline (planned)

## Learning Paths

### Quick Start (1 day)

For developers who need to get productive quickly:

1. Read: `examples/README.md`
2. Follow: `examples/elevenlabs-examples.ts` sections 1-2
3. Complete: Beginner exercises 1-3
4. Build: Simple text-to-speech application

### Complete Program (2 weeks)

For comprehensive mastery:

**Week 1: Foundations**
- Days 1-2: Workshop 1 + Beginner exercises
- Days 3-4: Examples deep dive
- Day 5: Practice project

**Week 2: Production Skills**
- Days 1-2: Workshop 2 + Intermediate exercises
- Days 3-4: Advanced patterns
- Day 5: Capstone project

### Self-Paced

Study at your own pace:

1. Start with video tutorials for overview
2. Work through examples section by section
3. Complete corresponding exercises
4. Build projects to reinforce learning

## Prerequisites

### Technical Requirements

- Node.js 18+
- pnpm package manager
- TypeScript knowledge
- Code editor (VS Code recommended)

### API Keys

| Service | Required For | How to Get |
|---------|--------------|------------|
| ElevenLabs | TTS | [elevenlabs.io](https://elevenlabs.io) |
| RunComfy | Image gen | [runcomfy.com](https://runcomfy.com) |
| Civitai | Models | [civitai.com](https://civitai.com) |

### Environment Setup

```bash
# Clone repository
git clone git@github.com:GreyChimp/oshun.git
cd oshun

# Install dependencies
pnpm install

# Set up environment variables
export ELEVENLABS_API_KEY=your_key
export RUNCOMFY_API_KEY=your_key
export CIVITAI_API_KEY=your_key
```

## Key Concepts

### Provider Pattern

All Oshun AI integrations follow a consistent provider pattern:

```typescript
// 1. Initialize with configuration
const provider = new Provider({
  apiKey: process.env.API_KEY,
  timeout: 30000,
  maxRetries: 3,
});

// 2. Execute operations
const result = await provider.operation(params);

// 3. Handle errors
try {
  await provider.operation(params);
} catch (error) {
  // Handle appropriately
}

// 4. Monitor health
const healthy = await provider.healthCheck();
const stats = provider.getStats();

// 5. Clean up
await provider.shutdown();
```

### Resilience Patterns

Production applications need resilience:

- **Retry with backoff** - Handle transient failures
- **Circuit breaker** - Prevent cascade failures
- **Fallback** - Degrade gracefully
- **Rate limiting** - Respect API limits

### Resource Management

Properly manage connections and resources:

- **Connection pooling** - Reuse expensive connections
- **Cleanup managers** - Ensure proper shutdown
- **Memory management** - Handle large payloads

### Observability

Monitor your AI applications:

- **Metrics** - Track requests, latency, errors
- **Health checks** - Verify service availability
- **Logging** - Record important events
- **Tracing** - Follow requests through system

## Getting Help

### Resources

- [API Documentation](../integrations/)
- [GitHub Issues](https://github.com/GreyChimp/oshun/issues)
- [Discord Community](#) (if available)

### Common Issues

**Q: My API key isn't working**
A: Check that the key is set correctly and hasn't expired. Try regenerating.

**Q: Requests are timing out**
A: Increase timeout in config. Check network connectivity. Verify API status.

**Q: I'm hitting rate limits**
A: Implement proper rate limiting. Use batch processing with delays.

**Q: Memory issues with large files**
A: Use streaming instead of loading entire files into memory.

## Contributing

To contribute to training materials:

1. Follow existing format and style
2. Test all code examples
3. Include comprehensive documentation
4. Update relevant README files
5. Submit PR with clear description

## License

Training materials are part of the Oshun project. See root LICENSE file.