# AI & ML Integrations Guide

**Last Updated**: 2026-06-29  
**Change Log**:
- 2026-06-29: Initial version generated after cloning the repository.

---

## 🎯 Overview

The Post-Call Analytics Platform leverages AI at three distinct stages:
1. **Language Detection & Audio Routing**: Fast classification models route calls based on spoken languages.
2. **Speech-To-Text (STT) Diarization**: Converts speech to multi-speaker text segments (Hindi-English mix using **Deepgram**, regional/other Indian languages using **Sarvam**).
3. **Generative LLM Analysis & RAG**: Evaluates transcripts for quality metrics, scoring criteria, BANT indicators, and objection checks using **AWS Bedrock (Nova)** and **Ollama**.

---

## 🤖 Model Inventory

| Function | Model Name / API | Provider | Tradeoffs & Rationale |
|----------|------------------|----------|-----------------------|
| STT (Mix) | `nova-3` (Hindi/English) | Deepgram | High accuracy on code-switching (Hinglish). |
| STT (Regional) | `saaras:v2.5` | Sarvam AI | Superior support for Kannada, Tamil, Telugu, and Malayalam. |
| Call Analysis | `amazon.nova-lite-v1:0` | AWS Bedrock | Balanced latency/cost, reliable JSON structured outputs. |
| Fallback / Local | Custom (e.g. `llama3`) | Ollama | Private local processing fallback when AWS limits are reached. |
| Embeddings | `titan-embed-text-v2` | AWS Bedrock | Low-dimensional (1024-d), cost-effective RAG semantic representation. |

---

## ⚙️ Prompt Orchestration & Construction

### 1. Template Rendering
Prompts are dynamically composed in `agent_runner.py` using `{placeholder}` structures:
- `{transcript}`: Clean, speaker-labeled timeline representation (`[SPEAKER 1]: text...`).
- `{scoring_parameters}`: Formatted list of rules, max scores, and descriptions.
- `{objections}`: Custom business-specific objection flags.

### 2. JSON Structure Output Request
The platform relies on system-level prompts requesting strict JSON answers containing:
- `quality_score` (overall calculated score based on active weights)
- `summary` (brief summary of call)
- `bant` (Budget, Authority, Need, Timeline annotations)
- `objections_identified` (exact match lists)

---

## 🔄 Chaining & Fallback Logic

```mermaid
flowchart TD
    Start["Start Call Analysis"] --> CheckProvider{"Select Provider"}
    CheckProvider -->|"Default"| Bedrock["AWS Bedrock (Nova)"]
    CheckProvider -->|"Configured Local"| Ollama["Ollama (localhost)"]
    
    Bedrock --> CheckSuccess{"Call Successful?"}
    CheckSuccess -->|"Yes"| Done["Parse & Store JSON"]
    CheckSuccess -->|"No"| Failover["Ollama Fallback Route"]
    
    Ollama --> CheckSuccessLocal{"Call Successful?"}
    CheckSuccessLocal -->|"Yes"| Done
    CheckSuccessLocal -->|"No"| ErrorState["Status = failed"]
```

---

## 📉 Optimization & Limitations

- **Diarization Limitations**: Overlapping speech or high background noise sometimes attributes customer lines to agents, leading to false-positive BANT signals.
- **Token Management**: Calls exceeding 10 minutes are truncated to the first 4000 words to respect input context limits and reduce prompt token costs.