AI_INTEGRATION_GUIDE.md•17.2 kB
# AI Integration Guide for SRT Chunking Functions
This guide provides comprehensive documentation for integrating SRT chunking functions with Claude, GPT, Gemini, and other AI models that support the Todo tool.
## Table of Contents
1. [Overview](#overview)
2. [Quick Start](#quick-start)
3. [Model-Specific Integration](#model-specific-integration)
4. [Todo Tool Integration](#todo-tool-integration)
5. [Context Optimization](#context-optimization)
6. [Examples](#examples)
7. [Best Practices](#best-practices)
8. [Troubleshooting](#troubleshooting)
## Overview
The SRT chunking integration provides a unified interface for working with different AI models while leveraging their specific capabilities and the Todo tool for progress tracking.
### Key Features
- **Unified Interface**: Single API for all AI models
- **Todo Tool Integration**: Progress tracking and task management
- **Context Optimization**: Intelligent chunking for AI context limits
- **Model-Specific Optimizations**: Tailored for each AI model's capabilities
- **Advanced Chunking**: Semantic analysis and speaker diarization
## Quick Start
### Basic Usage
```typescript
import { UnifiedAIFactory } from './src/integration/unified-ai-interface.js';
import { parseSRTFile } from './src/parsers/srt-parser.js';
// Create unified AI interface for Claude
const aiInterface = UnifiedAIFactory.createUnifiedAI('claude');
// Parse SRT file
const srtContent = await fs.readFile('example.srt', 'utf8');
const parseResult = parseSRTFile(srtContent);
if (parseResult.success && parseResult.file) {
// Process with Claude
const result = await aiInterface.processSRT({
subtitles: parseResult.file.subtitles,
processingType: 'translation',
targetLanguage: 'es',
options: {
useReasoning: true,
temperature: 0.7,
contextOptimization: true
}
});
console.log('Processing completed:', result.success);
console.log('Chunks processed:', result.chunks.length);
console.log('Todo list:', result.todoList);
}
```
### With Todo Tool Integration
```typescript
import { SRTProcessingTodoManager } from './src/integration/todo-tool-integration.js';
// Create todo manager for progress tracking
const todoManager = new SRTProcessingTodoManager('claude');
// Create processing todos
const todoResult = await todoManager.createSRTProcessingTodos(
'example.srt',
10, // chunk count
'translation',
'es' // target language
);
console.log('Todos created:', todoResult.success);
console.log('Todo IDs:', todoResult.todoIds);
```
## Model-Specific Integration
### Claude Integration
Claude integration leverages Anthropic's reasoning capabilities and Todo tool support.
```typescript
import { ClaudeSRTIntegration, ClaudeConfig } from './src/integration/claude-integration.js';
const claudeConfig: ClaudeConfig = {
modelType: 'claude',
supportsTodoTool: true,
maxContextSize: 200000,
chunkSizeLimit: 15,
processingStrategy: 'sequential',
contextOptimization: true,
claudeSpecific: {
useAnthropicFormat: true,
enableReasoning: true,
maxTokensPerRequest: 4000,
temperature: 0.7
}
};
const claudeIntegration = new ClaudeSRTIntegration(claudeConfig, {
modelConfig: claudeConfig,
chunkingStrategy: 'conversation-aware',
contextManagement: 'balanced',
todoIntegration: true,
progressTracking: true
});
// Process with Claude reasoning
const result = await claudeIntegration.processSRTWithClaude(
subtitles,
'translation',
{
useReasoning: true,
temperature: 0.7,
maxTokens: 4000
}
);
console.log('Claude reasoning:', result.reasoning);
console.log('Claude metrics:', result.claudeMetadata);
```
### GPT Integration
GPT integration supports function calling and parallel processing.
```typescript
import { UnifiedAIInterface } from './src/integration/unified-ai-interface.js';
const gptInterface = UnifiedAIFactory.createUnifiedAI('gpt');
const result = await gptInterface.processSRT({
subtitles,
processingType: 'analysis',
options: {
temperature: 0.7,
maxTokens: 4000,
contextOptimization: true
}
});
```
### Gemini Integration
Gemini integration supports multimodal processing and large context windows.
```typescript
const geminiInterface = UnifiedAIFactory.createUnifiedAI('gemini');
const result = await geminiInterface.processSRT({
subtitles,
processingType: 'conversation-detection',
options: {
temperature: 0.7,
maxTokens: 8000,
contextOptimization: true
}
});
```
## Todo Tool Integration
### Creating Todo Lists
```typescript
import { SRTTodoTemplates, TodoToolFactory } from './src/integration/todo-tool-integration.js';
// Create todo tool for specific model
const todoTool = TodoToolFactory.createTodoTool('claude');
// Create file analysis todos
const fileAnalysisTodos = SRTTodoTemplates.createFileAnalysisTodos('example.srt');
const todoResult = await todoTool.createTodoList(fileAnalysisTodos);
console.log('Todos created:', todoResult.success);
console.log('Todo IDs:', todoResult.todoIds);
```
### Managing Todo Progress
```typescript
// Update todo status
await todoTool.updateTodoStatus('claude-todo-1', 'completed');
// Get todo list
const todos = await todoTool.getTodoList();
console.log('Current todos:', todos);
// Get todos by category
const analysisTodos = await todoTool.getTodosByCategory('file-analysis');
// Get todo statistics
const stats = await todoTool.getTodoStatistics();
console.log('Completion rate:', stats.completionRate);
```
### SRT Processing Todo Manager
```typescript
import { SRTProcessingTodoManager } from './src/integration/todo-tool-integration.js';
const todoManager = new SRTProcessingTodoManager('claude');
// Create comprehensive processing todos
const todoResult = await todoManager.createSRTProcessingTodos(
'example.srt',
15, // chunk count
'translation',
'es' // target language
);
// Update processing progress
await todoManager.updateProcessingProgress('file-analysis', 'completed');
await todoManager.updateProcessingProgress('chunk-detection', 'in_progress');
// Get processing statistics
const stats = await todoManager.getProcessingStatistics();
console.log('Processing stats:', stats);
```
## Context Optimization
### Basic Context Optimization
```typescript
import { ContextOptimizationFactory } from './src/integration/context-optimization.js';
// Create context optimizer
const optimizer = ContextOptimizationFactory.createOptimizer('claude');
// Optimize chunks for AI context
const result = await optimizer.optimizeChunksForAI(chunks, 'translation');
console.log('Original chunks:', result.originalChunks.length);
console.log('Optimized chunks:', result.optimizedChunks.length);
console.log('Context efficiency:', result.performanceMetrics.contextEfficiency);
```
### Advanced Context Optimization
```typescript
import { AIContextOptimizer, ContextOptimizationConfig } from './src/integration/context-optimization.js';
const config: ContextOptimizationConfig = {
strategy: 'adaptive',
maxContextSize: 200000,
chunkSizeLimit: 15,
contextManagement: 'balanced',
enableSemanticChunking: true,
enableSpeakerAwareChunking: true,
enableComplexityBasedChunking: true,
enableTimingBasedChunking: true,
modelSpecific: {
claude: {
maxContextSize: 200000,
optimalChunkSize: 8,
contextOverhead: 1000,
reasoningTokens: 500,
responseTokens: 1000,
safetyMargin: 0.8
},
// ... other model configs
}
};
const optimizer = new AIContextOptimizer(config, 'claude');
const result = await optimizer.optimizeChunksForAI(chunks, 'translation');
// Analyze optimization results
console.log('Context analysis:', result.contextAnalysis);
console.log('Optimizations applied:', result.optimizationApplied);
console.log('Performance metrics:', result.performanceMetrics);
```
## Examples
### Complete Translation Workflow
```typescript
import { UnifiedAIFactory } from './src/integration/unified-ai-interface.js';
import { parseSRTFile, writeSRTFile } from './src/parsers/srt-parser.js';
async function translateSRTFile(inputFile: string, outputFile: string, targetLanguage: string) {
try {
// Parse SRT file
const srtContent = await fs.readFile(inputFile, 'utf8');
const parseResult = parseSRTFile(srtContent);
if (!parseResult.success || !parseResult.file) {
throw new Error('Failed to parse SRT file');
}
// Create AI interface
const aiInterface = UnifiedAIFactory.createUnifiedAI('claude');
// Process with translation
const result = await aiInterface.processSRT({
subtitles: parseResult.file.subtitles,
processingType: 'translation',
targetLanguage,
sourceLanguage: 'auto-detect',
options: {
useReasoning: true,
temperature: 0.7,
maxTokens: 4000,
contextOptimization: true,
preserveFormatting: true
}
});
if (!result.success) {
throw new Error('Translation failed');
}
// Create translated SRT file
const translatedSubtitles = result.results.map(chunkResult =>
chunkResult.translatedSubtitles
).flat();
const translatedSRT = {
...parseResult.file,
subtitles: translatedSubtitles
};
// Write translated file
const translatedContent = writeSRTFile(translatedSRT);
await fs.writeFile(outputFile, translatedContent);
console.log('Translation completed successfully');
console.log('Chunks processed:', result.chunks.length);
console.log('Processing time:', result.processingTime, 'ms');
console.log('Context efficiency:', result.metadata.contextEfficiency);
} catch (error) {
console.error('Translation failed:', error);
}
}
// Usage
await translateSRTFile('input.srt', 'output.srt', 'es');
```
### Analysis Workflow with Progress Tracking
```typescript
import { SRTProcessingTodoManager } from './src/integration/todo-tool-integration.js';
import { UnifiedAIFactory } from './src/integration/unified-ai-interface.js';
async function analyzeSRTWithProgress(inputFile: string) {
const todoManager = new SRTProcessingTodoManager('claude');
const aiInterface = UnifiedAIFactory.createUnifiedAI('claude');
try {
// Parse SRT file
const srtContent = await fs.readFile(inputFile, 'utf8');
const parseResult = parseSRTFile(srtContent);
if (!parseResult.success || !parseResult.file) {
throw new Error('Failed to parse SRT file');
}
// Create analysis todos
const todoResult = await todoManager.createSRTProcessingTodos(
inputFile,
parseResult.file.subtitles.length,
'analysis'
);
console.log('Analysis todos created:', todoResult.success);
// Process with analysis
const result = await aiInterface.processSRT({
subtitles: parseResult.file.subtitles,
processingType: 'analysis',
options: {
useReasoning: true,
temperature: 0.7,
contextOptimization: true
}
});
// Update todos
await todoManager.updateProcessingProgress('file-analysis', 'completed');
await todoManager.updateProcessingProgress('chunk-detection', 'completed');
await todoManager.updateProcessingProgress('processing', 'completed');
await todoManager.updateProcessingProgress('validation', 'completed');
// Get final statistics
const stats = await todoManager.getProcessingStatistics();
console.log('Analysis completed');
console.log('Todos completed:', stats.completed);
console.log('Completion rate:', stats.completionRate);
return result;
} catch (error) {
console.error('Analysis failed:', error);
throw error;
}
}
// Usage
const analysisResult = await analyzeSRTWithProgress('example.srt');
```
### Multi-Model Comparison
```typescript
async function compareModels(inputFile: string) {
const models = ['claude', 'gpt', 'gemini'] as const;
const results = new Map();
for (const model of models) {
console.log(`Processing with ${model}...`);
const aiInterface = UnifiedAIFactory.createUnifiedAI(model);
const result = await aiInterface.processSRT({
subtitles: parseResult.file.subtitles,
processingType: 'translation',
targetLanguage: 'es',
options: {
contextOptimization: true
}
});
results.set(model, {
processingTime: result.processingTime,
contextEfficiency: result.metadata.contextEfficiency,
chunksProcessed: result.chunks.length,
errors: result.errors.length,
warnings: result.warnings.length
});
}
// Compare results
console.log('Model Comparison:');
for (const [model, metrics] of results) {
console.log(`${model}:`);
console.log(` Processing time: ${metrics.processingTime}ms`);
console.log(` Context efficiency: ${metrics.contextEfficiency.toFixed(2)}`);
console.log(` Chunks processed: ${metrics.chunksProcessed}`);
console.log(` Errors: ${metrics.errors}, Warnings: ${metrics.warnings}`);
}
}
```
## Best Practices
### 1. Model Selection
- **Claude**: Best for reasoning-intensive tasks, translation with cultural context
- **GPT**: Good for general processing, parallel processing, function calling
- **Gemini**: Excellent for large context, multimodal content, batch processing
### 2. Context Optimization
```typescript
// Always enable context optimization for large files
const result = await aiInterface.processSRT({
subtitles,
processingType: 'translation',
options: {
contextOptimization: true // Essential for large files
}
});
```
### 3. Todo Tool Usage
```typescript
// Use todo tool for long-running processes
const todoManager = new SRTProcessingTodoManager('claude');
// Create todos before processing
await todoManager.createSRTProcessingTodos(fileName, chunkCount, processingType);
// Update progress during processing
await todoManager.updateProcessingProgress('chunk-detection', 'completed');
```
### 4. Error Handling
```typescript
try {
const result = await aiInterface.processSRT(request);
if (!result.success) {
console.error('Processing failed:', result.errors);
return;
}
// Check for warnings
if (result.warnings.length > 0) {
console.warn('Processing warnings:', result.warnings);
}
} catch (error) {
console.error('Unexpected error:', error);
}
```
### 5. Performance Monitoring
```typescript
// Monitor processing metrics
console.log('Processing metrics:');
console.log(' Total time:', result.processingTime, 'ms');
console.log(' Context efficiency:', result.metadata.contextEfficiency);
console.log(' Chunks processed:', result.chunks.length);
console.log(' Average chunk size:', result.metadata.averageChunkSize);
```
## Troubleshooting
### Common Issues
1. **Context Limit Exceeded**
```typescript
// Enable context optimization
options: {
contextOptimization: true
}
```
2. **Todo Tool Not Working**
```typescript
// Check if model supports todo tool
const config = UnifiedAIFactory.createUnifiedAI('claude');
console.log('Supports todo tool:', config.config.capabilities.supportsTodoTool);
```
3. **Processing Timeout**
```typescript
// Use sequential processing for large files
const config = {
...baseConfig,
capabilities: {
...baseConfig.capabilities,
processingStrategy: 'sequential'
}
};
```
### Debug Mode
```typescript
// Enable detailed logging
const result = await aiInterface.processSRT({
subtitles,
processingType: 'translation',
options: {
contextOptimization: true,
detailedLogging: true // Enable debug logging
}
});
console.log('Debug info:', result.metadata);
```
### Performance Tuning
```typescript
// Adjust chunking parameters for your use case
const customConfig = {
chunkingOptions: {
boundaryThreshold: 0.6, // More aggressive chunking
maxChunkSize: 10, // Smaller chunks
minChunkSize: 2,
enableSemanticAnalysis: true,
enableSpeakerDiarization: true
},
contextOptimization: {
enabled: true,
maxContextSize: 100000, // Adjust for your model
chunkSizeLimit: 8, // Smaller limit
contextManagement: 'aggressive'
}
};
```
## API Reference
### UnifiedAIInterface
- `processSRT(request: ProcessingRequest): Promise<UnifiedProcessingResult>`
### SRTProcessingTodoManager
- `createSRTProcessingTodos(fileName, chunkCount, processingType, targetLanguage?): Promise<TodoListResult>`
- `updateProcessingProgress(stage, status): Promise<void>`
- `getProcessingStatistics(): Promise<TodoStatistics>`
### AIContextOptimizer
- `optimizeChunksForAI(chunks, processingType): Promise<OptimizedChunkResult>`
### TodoToolInterface
- `createTodoList(todos): Promise<TodoListResult>`
- `updateTodoStatus(todoId, status): Promise<boolean>`
- `getTodoList(): Promise<TodoItem[]>`
- `getTodoStatistics(): Promise<TodoStatistics>`
## Conclusion
This integration provides a powerful, unified interface for working with SRT files across different AI models while leveraging the Todo tool for progress tracking and context optimization for efficient processing.
For more examples and advanced usage, see the test files in the `tests/` directory.