# KPI Calculation Logic - Step-by-Step

This document explains how the Strategist AI analytics engine calculates each Key Performance Indicator (KPI). The process follows a multi-stage pipeline: **Discovery** (Firestore) -> **AI Enrichment** -> **dbt Transformation** (SQL Aggregation).

---

## 🏗️ The Data Pipeline
1.  **Raw Input**: Chat messages and ticket data are synchronized from Firestore.
2.  **AI Layer**: For every conversation thread, an AI model extracts signals like `intent`, `sentiment_score`, `is_resolved`, and `escalation_needed`.
3.  **dbt Staging**: Data is normalized and types are cast for reliability.
4.  **Intermediate Layer**: Time-based session metrics (like Response Time) are calculated by looking at the sequence of messages within a thread.
5.  **Mart Layer**: Data is aggregated per tenant into the final KPIs listed below.

---

## 📊 1. General Chat Metrics
*Focuses on high-level engagement and system efficiency.*

| KPI | Logic |
| :--- | :--- |
| **Total Conversations** | Total count of unique chat threads. |
| **Total Users** | Total count of unique chat threads (currently a 1:1 proxy). |
| **Avg Response Time** | Calculated as the average time between a user question and the immediate AI bot response within that same thread. |
| **Resolution Rate %** | `(Threads marked as 'Resolved' by AI / Total Threads) * 100` |
| **User Satisfaction** | Average sentiment score extracted by AI (range: -1.0 to 1.0). |
| **Hourly Response Time** | A breakdown of the Average Response Time grouped by the hour of the day the session started. |

---

## 🎯 2. Customer Intent & Demand
*Focuses on what customers want and how qualified they are.*

| KPI | Logic |
| :--- | :--- |
| **Intent Count** | Sum of sessions categorized under specific intents (e.g., Pricing, Support, Feature Request). |
| **Product Interest Score** | A weighted score: `+0.5` for High Intent, `+0.3` for CTA clicks, `+0.2` for Qualified Leads. |
| **Lead Qualification Rate %** | `(Qualified Leads / Total sessions) * 100` |
| **High Intent Rate %** | `(Sessions with High Intent / Total sessions) * 100` |

---

## 💸 3. Conversion Enablement
*Focuses on the transition from chat to business outcomes.*

| KPI | Logic |
| :--- | :--- |
| **Chat-to-Lead Rate** | Percentage of chat sessions that the AI identified as "Qualified Leads." |
| **Purchase Assist Rate** | Percentage of sessions where the user intent was specifically related to "Pricing" or "Purchasing." |
| **Drop-off Rate %** | Percentage of sessions that were NOT resolved AND the user did NOT click any Call-to-Action (CTA). |
| **CTA Click Rate %** | `(Sessions with a CTA click / Total sessions) * 100` |

---

## 😊 4. Customer Experience (CX)
*Focuses on the quality of the interaction and bot performance.*

| KPI | Logic |
| :--- | :--- |
| **CSAT Score** | The average AI-detected sentiment score, scaled for a Customer Satisfaction metric. |
| **Bot Containment Rate %** | Percentage of sessions that were successfully resolved without requiring an escalation to a human agent. |
| **Escalation Rate %** | `(Sessions requiring escalation / Total sessions) * 100` |
| **Avg Resolution Time** | The average duration (start to end) of chat sessions that were successfully resolved. |

---

## 🗣️ 5. Voice of Customer (VOC)
*Focuses on direct feedback and market signals.*

| KPI | Logic |
| :--- | :--- |
| **Pain Point Frequency** | Count of specific user struggles or friction points identified by the AI. |
| **Feature Request Volume** | Count of unique requests for new features or capabilities. |
| **Objection Trends Count** | Count of specific "No" signals or hesitations (e.g., "Too expensive", "Missing feature X"). |

---

## 🎫 6. Helpdesk & Ticketing
*Focuses on support operations and long-term retention.*

| KPI | Logic |
| :--- | :--- |
| **Avg First Response Time** | Time elapsed between ticket creation and the first recorded response. |
| **Avg Resolution Time** | Time elapsed between ticket creation and the ticket status changing to "Closed." |
| **Ticket Backlog Growth** | The current count of tickets remaining in "Open" status. |
| **Churn Risk Rate %** | Percentage of high-priority tickets coming from users with a negative average sentiment in their chat history. |
| **Repeat Complaint Rate** | Percentage of users who have opened more than one support ticket. |
| **NPS Proxy** | A Net Promoter Score estimate based on session sentiment: `Sentiment > 0.5` is considered a promoter (10), others are neutral/detractors (2). |