# Harmony Response Format - Examples
This directory contains comprehensive examples demonstrating how to use the Harmony Response Format library.
## ⚠️ **CRITICAL: This Library Requires an OpenAI Model**
**These examples do NOT include an AI model.** They demonstrate the conversation formatting and parsing layer. To complete the pipeline, you must:
1. **Send formatted tokens** to OpenAI's API or compatible model
2. **Receive response tokens** from the model
3. **Parse response tokens** back to structured messages using this library
**Complete Pipeline:** Your App → This Library (format) → OpenAI Model → This Library (parse) → Your App
## Running Examples
To run any example, use:
```bash
cargo run --example <example_name>
```
For example:
```bash
cargo run --example basic_usage
cargo run --example tool_integration
```
## Examples Overview
### 1. Basic Usage (`basic_usage.rs`)
**What it demonstrates:**
- Creating messages and conversations
- Loading encodings
- Rendering conversations to tokens
- Different rendering modes (basic, completion, training)
**Key concepts:**
- Message creation with different roles
- System content configuration
- Token rendering process
- Error handling for network dependencies
```bash
cargo run --example basic_usage
```
### 2. Tool Integration (`tool_integration.rs`)
**What it demonstrates:**
- Creating custom tools with JSON schemas
- Using built-in browser and Python tools
- Tool calling with recipients
- Developer instructions and guidelines
**Key concepts:**
- ToolDescription creation with parameters
- ToolNamespaceConfig organization
- Message routing with recipients
- Complex conversation flows with tool interactions
```bash
cargo run --example tool_integration
```
### 3. Streaming Parser (`streaming_parser.rs`)
**What it demonstrates:**
- Real-time token processing
- State management during streaming
- Content delta tracking
- Message boundary detection
**Key concepts:**
- StreamableParser usage
- Token-by-token processing
- UTF-8 boundary handling
- State introspection during parsing
```bash
cargo run --example streaming_parser
```
### 4. Channel Management (`channel_management.rs`)
**What it demonstrates:**
- Multi-channel conversations (analysis, commentary, final)
- Analysis dropping behavior
- Channel configuration and routing
- Structured reasoning workflows
**Key concepts:**
- Channel-based message organization
- Auto-drop analysis configuration
- Reasoning effort levels
- Message flow analysis
```bash
cargo run --example channel_management
```
## Example Structure
Each example follows a consistent structure:
1. **Setup**: Import necessary modules and create basic structures
2. **Configuration**: Set up encoding, system content, and tools
3. **Demonstration**: Show the primary functionality
4. **Analysis**: Display results and explain what happened
5. **Error Handling**: Gracefully handle network unavailability
## Network Dependencies
Most examples attempt to load the actual encoding from OpenAI's servers. If network access is unavailable, they will:
- Display a warning message
- Continue with mock data or structural demonstrations
- Still show the conversation building and configuration
This ensures examples are useful even in offline environments.
## Extending Examples
To create your own examples:
1. Copy an existing example as a template
2. Modify the conversation structure for your use case
3. Add specific tool configurations if needed
4. Update the documentation comments
5. Test both with and without network access
## Tips for Learning
1. **Start with `basic_usage.rs`** to understand fundamentals
2. **Read the source code** - examples are heavily commented
3. **Experiment with modifications** - change messages, tools, or channels
4. **Check error handling** - see how examples handle various failure modes
5. **Compare token outputs** - observe how different configurations affect rendering
## Performance Notes
Examples include timing information and token counts to help you understand:
- Rendering performance characteristics
- Memory usage patterns
- Token efficiency of different conversation structures
## Integration with Other Languages
- See `python/examples/` for Python binding usage
- See `www/index.html` for WebAssembly integration
- Examples demonstrate the same concepts across different language bindings
## Troubleshooting
**"Encoding load failed" errors:**
- Expected without network access
- Examples continue with mock data
- Not a problem with the library
**Compilation errors:**
- Ensure you're in the project root directory
- Run `cargo check` to verify setup
- Check that all dependencies are available
**Performance concerns:**
- Examples may be slower on first run (compilation)
- Network loading adds latency for encoding
- Use `cargo run --release --example <name>` for optimized performance