Update documentation for AI-powered features

- Added comprehensive documentation for AI speaker detection
- Documented AI text segmentation capabilities
- Added Ollama setup instructions
- Explained benefits of AI-powered vs pattern-based detection
- Updated API endpoint documentation with AI feature details

backend/README.md

@@ -62,7 +62,43 @@ pip install --upgrade pip
 pip install -r requirements.txt
 ```
 
-### 3. Environment Configuration
+### 3. Ollama Setup (Optional but Recommended)
+
+For AI-powered speaker detection and text segmentation, install Ollama:
+
+**Installation:**
+- Visit [ollama.com](https://ollama.com) and download for your platform
+- Or use package managers:
+  ```bash
+  # macOS
+  brew install ollama
+  
+  # Linux
+  curl -fsSL https://ollama.com/install.sh | sh
+  ```
+
+**Pull the required model:**
+```bash
+ollama pull llama3
+```
+
+**Start Ollama service:**
+```bash
+ollama serve
+```
+
+Verify Ollama is running:
+```bash
+curl http://localhost:11434/api/tags
+```
+
+**Benefits of using Ollama:**
+- ✨ Intelligently detects speakers in unmarked text
+- ✨ Automatically segments dialogue and assigns to correct characters
+- ✨ Handles narrative text without explicit role markers
+- ✨ Falls back to pattern matching if unavailable
+
+### 4. Environment Configuration
 
 ```bash
 cp .env.example .env
@@ -72,9 +108,10 @@ Edit `.env` if needed:
 ```bash
 PORT=8000
 LOG_LEVEL=info
+OLLAMA_BASE_URL=http://localhost:11434  # Optional: Ollama API URL
 ```
 
-### 4. Run the Server
+### 5. Run the Server
 
 ```bash
 uvicorn main:app --reload --host 0.0.0.0 --port 8000
@@ -162,7 +199,10 @@ curl http://localhost:8000/api/health
 
 ### POST /api/tts/roles
 
-Detect distinct roles/speakers in text.
+Detect distinct roles/speakers in text using AI-powered detection.
+
+**AI-Powered Detection:**
+When Ollama is available, the system uses AI (llama3) to intelligently detect speakers in unmarked text. This allows you to input plain narrative text without explicit role markers, and the AI will identify all characters and speakers.
 
 **Request Body:**
 ```json
@@ -182,11 +222,21 @@ Detect distinct roles/speakers in text.
 }
 ```
 
-**Supported Role Patterns:**
+**Detection Methods:**
-- Colon pattern: `RoleName: dialogue text`
+1. **AI Detection (Primary)**: Uses Ollama with llama3 to intelligently identify speakers in unmarked text
-- Bracket pattern: `[RoleName] dialogue text`
+   - Example: "The wizard spoke softly. The knight replied." → Detects "Wizard" and "Knight"
+2. **Pattern Matching (Fallback)**: Falls back to pattern-based detection if Ollama unavailable
+   - Colon pattern: `RoleName: dialogue text`
+   - Bracket pattern: `[RoleName] dialogue text`
 
-**Example:**
+**Example with AI Detection:**
+```bash
+curl -X POST http://localhost:8000/api/tts/roles \
+  -H "Content-Type: application/json" \
+  -d '{"text":"The wizard gazed into his crystal ball. The knight drew his sword."}'
+```
+
+**Example with Pattern Markers:**
 ```bash
 curl -X POST http://localhost:8000/api/tts/roles \
   -H "Content-Type: application/json" \
@@ -195,7 +245,13 @@ curl -X POST http://localhost:8000/api/tts/roles \
 
 ### POST /api/tts
 
-Generate multi-voice audiobook.
+Generate multi-voice audiobook with AI-powered text segmentation.
+
+**AI-Powered Segmentation:**
+When Ollama is available, the system uses AI to intelligently split text and assign each segment to the appropriate speaker. This means you can input plain narrative text, and the AI will automatically:
+- Assign dialogue to the correct character
+- Assign narrative descriptions to the Narrator
+- Handle mixed dialogue and narration seamlessly
 
 **Request Body:**
 ```json
@@ -211,13 +267,21 @@ Generate multi-voice audiobook.
 ```
 
 **Parameters:**
-- `text` (required): Text to synthesize
+- `text` (required): Text to synthesize (can be plain narrative or marked with role patterns)
 - `lang` (required): Language code (a=American English, b=British English, f=French, j=Japanese)
 - `roles` (required): Array of role-to-voice mappings
 - `speed` (optional): Playback speed (0.5-1.5, default: 1.0)
 
 **Response:**
 - Content-Type: `audio/wav`
+- Content-Disposition: `attachment; filename=audiobook.wav`
+
+**Segmentation Methods:**
+1. **AI Segmentation (Primary)**: Uses Ollama to intelligently split text and assign speakers
+   - Handles unmarked dialogue and narrative
+   - Automatically assigns dialogue to characters and descriptions to Narrator
+2. **Pattern Segmentation (Fallback)**: Uses explicit role markers when AI unavailable
+   - Requires `RoleName:` or `[RoleName]` markers in text
 - Content-Disposition: `attachment; filename="audiobook.wav"`
 - Body: Audio file bytes