Upload folder using huggingface_hub

README.md

@@ -1,10 +1,78 @@
----
-title: Herald Customer Ops
-emoji: 🐢
-colorFrom: green
-colorTo: yellow
-sdk: static
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: Herald -- Customer Operations Platform
+emoji: "\U0001F4CB"
+colorFrom: blue
+colorTo: indigo
+sdk: gradio
+sdk_version: 5.29.0
+app_file: app.py
+pinned: false
+license: mit
+short_description: AI customer ops -- chat, sentiment, health, tickets
+---
+
+# Herald -- Customer Operations Platform
+
+Herald is an AI-powered customer operations platform that unifies support chat, sentiment analysis, customer health scoring, and ticket categorization into a single system. Built with FastAPI and React, Herald gives support teams and customer success managers the tools to resolve issues faster, predict churn before it happens, and route tickets to the right team automatically.
+
+This Hugging Face Space is an interactive demo showcasing Herald's core capabilities.
+
+**GitHub:** [github.com/dbhavery/herald](https://github.com/dbhavery/herald)
+
+---
+
+## Demo Features
+
+### AI Support Chat
+Simulated multi-turn customer support conversations demonstrating how Herald's AI assistant responds to different customer scenarios (general questions, billing inquiries, technical issues, escalations) with context-aware answers and knowledge-base citations.
+
+### Sentiment Analyzer
+Paste any customer message to analyze its sentiment across five dimensions: positive, neutral, frustrated, negative, and angry. The analyzer uses keyword and pattern matching (capitalization, repeated punctuation, intensity markers) to produce confidence-weighted scores displayed on a gauge chart.
+
+### Customer Health Score
+Input customer engagement signals (login recency, support ticket volume, NPS score, usage trend) to calculate a weighted health score from 0 to 100 with churn risk classification (Low / Medium / High / Critical). The full scoring formula and component breakdown are displayed alongside the result.
+
+### Ticket Categorizer
+Paste a support ticket to automatically classify it into one of five categories: Billing, Technical Support, Account Management, Feature Request, or Bug Report. The categorizer shows confidence scores for each category with matched keyword details.
+
+---
+
+## Architecture Overview
+
+```
+Herald Platform
+|
+|-- Frontend (React + TypeScript)
+|   |-- Support Chat Interface
+|   |-- Customer Dashboard
+|   |-- Analytics Views
+|   |-- Ticket Management
+|
+|-- Backend (FastAPI + Python)
+|   |-- AI Chat Engine (LLM + RAG knowledge base)
+|   |-- Sentiment Analysis Pipeline
+|   |-- Customer Health Scoring Engine
+|   |-- Ticket Categorization Service
+|   |-- Support Rep Copilot
+|
+|-- Data Layer
+|   |-- Customer Profiles + Engagement History
+|   |-- Knowledge Base (vector search)
+|   |-- Ticket Store + Categorization Index
+|   |-- Analytics Aggregations
+```
+
+---
+
+## Running Locally
+
+```bash
+pip install -r requirements.txt
+python app.py
+```
+
+---
+
+## License
+
+MIT

app.py

@@ -0,0 +1,1264 @@
+"""
+Herald -- Customer Operations Platform
+Gradio demo showcasing AI-powered customer support tooling.
+
+Tabs:
+  1. AI Support Chat     - Simulated support chatbot with knowledge-base citations
+  2. Sentiment Analyzer  - Keyword/pattern sentiment scoring with gauge visualization
+  3. Customer Health Score - Weighted formula for churn-risk prediction
+  4. Ticket Categorizer  - Keyword-based support ticket classification
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+import gradio as gr
+import matplotlib
+import matplotlib.pyplot as plt
+import numpy as np
+from packaging.version import Version
+
+matplotlib.use("Agg")
+
+_GRADIO_VERSION = Version(gr.__version__)
+_GRADIO_6_PLUS = _GRADIO_VERSION >= Version("6.0.0")
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+APP_TITLE = "Herald -- Customer Operations Platform"
+
+SENTIMENT_LABELS = ("positive", "negative", "neutral", "frustrated", "angry")
+
+TICKET_CATEGORIES = (
+    "billing",
+    "technical",
+    "account",
+    "feature_request",
+    "bug_report",
+)
+
+HEALTH_WEIGHTS = {
+    "recency": 0.30,
+    "ticket_load": 0.25,
+    "nps": 0.25,
+    "usage_trend": 0.20,
+}
+
+CHURN_THRESHOLDS = {
+    "critical": 30,
+    "high": 50,
+    "medium": 70,
+}
+
+# ---------------------------------------------------------------------------
+# Tab 1 -- AI Support Chat (pre-scripted demo)
+# ---------------------------------------------------------------------------
+
+CUSTOMER_PROFILES = {
+    "returning_user": {
+        "label": "Returning User -- General Question",
+        "greeting": (
+            "Hi, I logged in after a few weeks and noticed the dashboard "
+            "looks different. Where did the export button go?"
+        ),
+    },
+    "billing_question": {
+        "label": "Billing Question -- Plan Upgrade",
+        "greeting": (
+            "I need to upgrade from the Starter plan to Business but I'm "
+            "mid-cycle. Will I be charged the full price or prorated?"
+        ),
+    },
+    "technical_issue": {
+        "label": "Technical Issue -- API Integration",
+        "greeting": (
+            "Our webhook endpoint is returning 422 errors from your API "
+            "since yesterday. Payload looks the same as before. What changed?"
+        ),
+    },
+    "angry_customer": {
+        "label": "Angry Customer -- Service Outage",
+        "greeting": (
+            "This is the THIRD time this month your service has gone down. "
+            "We lost actual revenue because of this. I want a refund and "
+            "I want to talk to someone in charge."
+        ),
+    },
+}
+
+# Each scenario maps to a list of (user_msg, assistant_response) pairs.
+# The first pair uses the greeting above; subsequent pairs continue the
+# conversation so the demo feels multi-turn.
+SCRIPTED_CONVERSATIONS: dict[str, list[tuple[str, str]]] = {
+    "returning_user": [
+        (
+            CUSTOMER_PROFILES["returning_user"]["greeting"],
+            (
+                "Welcome back! In the February update (v4.2) we moved bulk "
+                "actions -- including Export -- into the top-right toolbar so "
+                "they are accessible from every view.\n\n"
+                "To export your data:\n"
+                "1. Open the view you want to export (Customers, Tickets, etc.)\n"
+                "2. Click the toolbar icon (three horizontal lines) in the top-right\n"
+                "3. Select 'Export' and choose CSV or JSON\n\n"
+                "[Knowledge Base: UI Changes in v4.2 -- doc/release-notes/4.2.md]\n"
+                "[Knowledge Base: Data Export Guide -- doc/guides/export.md]"
+            ),
+        ),
+        (
+            "Got it, thanks. Can I export filtered results or only the full dataset?",
+            (
+                "You can export filtered results. Apply any filters first "
+                "(date range, status, tags), then use Export. The output "
+                "includes only the rows matching your active filters.\n\n"
+                "If you need scheduled exports, the Business plan includes "
+                "automated CSV delivery via email or S3.\n\n"
+                "[Knowledge Base: Filtered Exports -- doc/guides/export.md#filters]\n"
+                "[Knowledge Base: Scheduled Exports -- doc/guides/export.md#automation]"
+            ),
+        ),
+    ],
+    "billing_question": [
+        (
+            CUSTOMER_PROFILES["billing_question"]["greeting"],
+            (
+                "Great question. Mid-cycle upgrades are always prorated. "
+                "Here is how it works:\n\n"
+                "- We calculate the unused portion of your current Starter "
+                "plan and credit it to your account.\n"
+                "- The Business plan charge starts immediately, prorated "
+                "for the remaining days in your billing cycle.\n"
+                "- Your next full-price Business invoice will be on your "
+                "normal renewal date.\n\n"
+                "You can preview the exact amounts on the Billing page "
+                "before confirming the upgrade.\n\n"
+                "[Knowledge Base: Plan Upgrades and Proration -- doc/billing/proration.md]\n"
+                "[Knowledge Base: Billing FAQ -- doc/billing/faq.md]"
+            ),
+        ),
+        (
+            "What if I want to downgrade again before the cycle ends?",
+            (
+                "Downgrades take effect at the end of your current billing "
+                "cycle -- you keep Business features until then, and the "
+                "lower rate applies on renewal. No additional proration "
+                "charge for the downgrade.\n\n"
+                "One thing to note: Business-only data (custom dashboards, "
+                "advanced analytics history) is retained for 30 days after "
+                "downgrade in case you change your mind.\n\n"
+                "[Knowledge Base: Downgrades -- doc/billing/proration.md#downgrades]\n"
+                "[Knowledge Base: Data Retention on Plan Change -- doc/billing/retention.md]"
+            ),
+        ),
+    ],
+    "technical_issue": [
+        (
+            CUSTOMER_PROFILES["technical_issue"]["greeting"],
+            (
+                "I can see the issue. On March 3 we released API v2.4 which "
+                "tightened webhook payload validation. Two fields that were "
+                "previously optional are now required:\n\n"
+                "- `event_timestamp` (ISO 8601 format)\n"
+                "- `idempotency_key` (string, max 64 chars)\n\n"
+                "If your payload omits either field, the API returns 422 "
+                "with error code `VALIDATION_MISSING_FIELDS`.\n\n"
+                "Add those two fields and the 422s should resolve "
+                "immediately. No other payload changes are needed.\n\n"
+                "[Knowledge Base: API v2.4 Breaking Changes -- doc/api/changelog.md#v2.4]\n"
+                "[Knowledge Base: Webhook Payload Schema -- doc/api/webhooks.md]"
+            ),
+        ),
+        (
+            "Why wasn't this communicated before the release?",
+            (
+                "You are right to flag that -- the migration notice was sent "
+                "on February 25 but only to account owners, not to technical "
+                "contacts. I have filed an internal ticket to ensure API "
+                "change notices go to all contacts with Developer role.\n\n"
+                "For now, you can subscribe to our API changelog RSS feed "
+                "or enable the 'API Updates' notification channel in your "
+                "account settings so your engineering team gets direct "
+                "alerts.\n\n"
+                "[Knowledge Base: Notification Preferences -- doc/account/notifications.md]\n"
+                "[Knowledge Base: API Changelog RSS -- doc/api/changelog.md#rss]"
+            ),
+        ),
+    ],
+    "angry_customer": [
+        (
+            CUSTOMER_PROFILES["angry_customer"]["greeting"],
+            (
+                "I completely understand your frustration, and I am sorry "
+                "for the impact this has had on your business. Three "
+                "incidents in one month is not acceptable.\n\n"
+                "Here is what I am doing right now:\n\n"
+                "1. I have escalated your case to our Customer Success "
+                "Director, who will reach out within 2 hours to discuss "
+                "the refund and your account status.\n"
+                "2. I have flagged your account for SLA credit review -- "
+                "our policy covers service credits for downtime exceeding "
+                "99.9% availability.\n"
+                "3. The engineering post-mortem for the March 5 incident "
+                "is published and linked below. The root cause was a "
+                "database failover timeout; we have since reduced failover "
+                "time from 90 seconds to under 10.\n\n"
+                "Your case ID is ESC-2026-4471. You will hear from the "
+                "director shortly.\n\n"
+                "[Knowledge Base: SLA and Service Credits -- doc/legal/sla.md]\n"
+                "[Knowledge Base: March 5 Post-Mortem -- doc/incidents/2026-03-05.md]"
+            ),
+        ),
+        (
+            "I want to make sure this actually gets followed up on. "
+            "Last time I was told someone would call and nobody did.",
+            (
+                "That is a valid concern and I apologize for the previous "
+                "follow-up failure. I have done two things to make sure "
+                "this does not happen again:\n\n"
+                "1. Your escalation is now tracked in our internal system "
+                "with a hard 2-hour SLA. If the director has not contacted "
+                "you by then, it auto-escalates to the VP of Customer "
+                "Success.\n"
+                "2. I am sending you a confirmation email right now with "
+                "the case ID (ESC-2026-4471), the director's direct email, "
+                "and the committed timeline.\n\n"
+                "You also have my direct support line in that email if you "
+                "need to follow up.\n\n"
+                "[Knowledge Base: Escalation SLA Policy -- doc/internal/escalation.md]\n"
+                "[Knowledge Base: Customer Advocacy Program -- doc/cs/advocacy.md]"
+            ),
+        ),
+    ],
+}
+
+
+def _build_chat_history(
+    scenario_key: str,
+    turn_index: int,
+) -> list[dict[str, str]]:
+    """Return Gradio messages-format history up to *turn_index* (inclusive)."""
+    turns = SCRIPTED_CONVERSATIONS[scenario_key]
+    capped = min(turn_index, len(turns) - 1)
+    history: list[dict[str, str]] = []
+    for user_msg, bot_msg in turns[: capped + 1]:
+        history.append({"role": "user", "content": user_msg})
+        history.append({"role": "assistant", "content": bot_msg})
+    return history
+
+
+def start_chat(scenario_key: str) -> tuple[list[dict[str, str]], int, str]:
+    """Load the first turn of the selected scenario."""
+    history = _build_chat_history(scenario_key, turn_index=0)
+    next_index = 1
+    max_turns = len(SCRIPTED_CONVERSATIONS[scenario_key])
+    if next_index >= max_turns:
+        status = "Demo conversation complete."
+    else:
+        status = f"Turn 1 of {max_turns}. Click 'Next Response' to continue."
+    return history, next_index, status
+
+
+def next_turn(
+    scenario_key: str,
+    current_index: int,
+    current_history: list[dict[str, str]],
+) -> tuple[list[dict[str, str]], int, str]:
+    """Advance the demo conversation by one turn."""
+    turns = SCRIPTED_CONVERSATIONS[scenario_key]
+    if current_index >= len(turns):
+        return (
+            current_history,
+            current_index,
+            "Demo conversation complete -- all turns shown.",
+        )
+    history = _build_chat_history(scenario_key, current_index)
+    next_index = current_index + 1
+    max_turns = len(turns)
+    if next_index >= max_turns:
+        status = "Demo conversation complete."
+    else:
+        status = f"Turn {next_index} of {max_turns}. Click 'Next Response' to continue."
+    return history, next_index, status
+
+
+# ---------------------------------------------------------------------------
+# Tab 2 -- Sentiment Analyzer
+# ---------------------------------------------------------------------------
+
+# Weighted keyword lists.  Each word carries a base weight; surrounding
+# context (caps, exclamation marks, repeated punctuation) applies multipliers.
+
+SENTIMENT_KEYWORDS: dict[str, list[tuple[str, float]]] = {
+    "positive": [
+        ("thank", 0.25), ("thanks", 0.25), ("great", 0.30),
+        ("excellent", 0.35), ("awesome", 0.30), ("love", 0.30),
+        ("helpful", 0.25), ("appreciate", 0.30), ("amazing", 0.30),
+        ("perfect", 0.35), ("fantastic", 0.30), ("wonderful", 0.30),
+        ("pleased", 0.25), ("happy", 0.25), ("impressed", 0.30),
+        ("well done", 0.30), ("good job", 0.25), ("smooth", 0.20),
+        ("intuitive", 0.20), ("reliable", 0.20), ("fast", 0.15),
+        ("easy", 0.15), ("resolved", 0.20), ("fixed", 0.20),
+        ("works", 0.10), ("satisfied", 0.25), ("recommend", 0.25),
+    ],
+    "negative": [
+        ("bad", 0.25), ("terrible", 0.35), ("awful", 0.35),
+        ("horrible", 0.35), ("worst", 0.40), ("hate", 0.35),
+        ("useless", 0.30), ("broken", 0.30), ("failure", 0.30),
+        ("disappointed", 0.30), ("poor", 0.25), ("unacceptable", 0.35),
+        ("pathetic", 0.35), ("disaster", 0.35), ("trash", 0.30),
+        ("garbage", 0.30), ("rubbish", 0.30), ("waste", 0.25),
+        ("never works", 0.35), ("down again", 0.30),
+    ],
+    "frustrated": [
+        ("frustrat", 0.35), ("annoying", 0.30), ("annoyed", 0.30),
+        ("still not", 0.25), ("again", 0.15), ("keeps", 0.15),
+        ("another", 0.10), ("still", 0.15), ("waiting", 0.20),
+        ("how many times", 0.35), ("yet again", 0.30),
+        ("come on", 0.25), ("seriously", 0.20), ("ridiculous", 0.30),
+        ("unbelievable", 0.25), ("sick of", 0.30), ("tired of", 0.30),
+        ("over and over", 0.30), ("same issue", 0.25),
+        ("not resolved", 0.25), ("still broken", 0.30),
+    ],
+    "angry": [
+        ("furious", 0.45), ("livid", 0.45), ("outraged", 0.40),
+        ("scam", 0.40), ("sue", 0.40), ("lawyer", 0.35),
+        ("legal action", 0.40), ("demand", 0.30), ("refund", 0.20),
+        ("cancel", 0.20), ("immediately", 0.15), ("unacceptable", 0.25),
+        ("stealing", 0.40), ("fraud", 0.40), ("rip off", 0.35),
+        ("ripoff", 0.35), ("incompetent", 0.35),
+    ],
+}
+
+# Patterns that amplify scores.
+_CAPS_RATIO_THRESHOLD = 0.5  # if > 50% of alpha chars are uppercase
+_EXCLAMATION_PATTERN = re.compile(r"!{2,}")
+_QUESTION_FLOOD_PATTERN = re.compile(r"\?{2,}")
+_ELLIPSIS_PATTERN = re.compile(r"\.{3,}")
+
+
+@dataclass(frozen=True)
+class SentimentResult:
+    positive: float
+    negative: float
+    neutral: float
+    frustrated: float
+    angry: float
+    dominant: str
+    dominant_confidence: float
+
+
+def _clamp(value: float, low: float = 0.0, high: float = 1.0) -> float:
+    return max(low, min(high, value))
+
+
+def analyze_sentiment(text: str) -> SentimentResult:
+    """Score customer message sentiment using keyword/pattern matching."""
+    if not text or not text.strip():
+        return SentimentResult(
+            positive=0.0,
+            negative=0.0,
+            neutral=1.0,
+            frustrated=0.0,
+            angry=0.0,
+            dominant="neutral",
+            dominant_confidence=1.0,
+        )
+
+    text_lower = text.lower()
+    alpha_chars = [c for c in text if c.isalpha()]
+    caps_ratio = (
+        sum(1 for c in alpha_chars if c.isupper()) / len(alpha_chars)
+        if alpha_chars
+        else 0.0
+    )
+
+    # Context-based multiplier: shouting (caps), repeated punctuation
+    intensity_multiplier = 1.0
+    if caps_ratio > _CAPS_RATIO_THRESHOLD:
+        intensity_multiplier += 0.3
+    if _EXCLAMATION_PATTERN.search(text):
+        intensity_multiplier += 0.2
+    if _QUESTION_FLOOD_PATTERN.search(text):
+        intensity_multiplier += 0.1
+
+    raw_scores: dict[str, float] = {}
+    for sentiment, keywords in SENTIMENT_KEYWORDS.items():
+        score = 0.0
+        for keyword, weight in keywords:
+            if keyword in text_lower:
+                score += weight
+        raw_scores[sentiment] = score * intensity_multiplier
+
+    # Neutral is the absence of other signals.
+    total_signal = sum(raw_scores.values())
+    if total_signal < 0.15:
+        raw_scores["neutral"] = 0.8
+    elif total_signal < 0.4:
+        raw_scores["neutral"] = 0.4 - total_signal * 0.5
+    else:
+        raw_scores["neutral"] = max(0.0, 0.2 - total_signal * 0.1)
+
+    # Normalize to sum = 1.
+    all_sentiments = {
+        "positive": raw_scores.get("positive", 0.0),
+        "negative": raw_scores.get("negative", 0.0),
+        "neutral": raw_scores.get("neutral", 0.0),
+        "frustrated": raw_scores.get("frustrated", 0.0),
+        "angry": raw_scores.get("angry", 0.0),
+    }
+    total = sum(all_sentiments.values())
+    if total > 0:
+        for key in all_sentiments:
+            all_sentiments[key] /= total
+
+    dominant = max(all_sentiments, key=lambda k: all_sentiments[k])
+    return SentimentResult(
+        positive=round(all_sentiments["positive"], 3),
+        negative=round(all_sentiments["negative"], 3),
+        neutral=round(all_sentiments["neutral"], 3),
+        frustrated=round(all_sentiments["frustrated"], 3),
+        angry=round(all_sentiments["angry"], 3),
+        dominant=dominant,
+        dominant_confidence=round(all_sentiments[dominant], 3),
+    )
+
+
+def _render_sentiment_gauge(result: SentimentResult) -> plt.Figure:
+    """Render a semicircular gauge chart for overall sentiment."""
+    fig, ax = plt.subplots(figsize=(6, 3.5), subplot_kw={"projection": "polar"})
+    fig.patch.set_facecolor("#0b0f19")
+
+    # Map dominant sentiment to a position on the gauge.
+    # Left (pi) = very negative, right (0) = very positive.
+    sentiment_positions = {
+        "angry": 0.05,
+        "negative": 0.20,
+        "frustrated": 0.35,
+        "neutral": 0.50,
+        "positive": 0.90,
+    }
+    sentiment_colors = {
+        "angry": "#dc2626",
+        "negative": "#f97316",
+        "frustrated": "#eab308",
+        "neutral": "#6b7280",
+        "positive": "#22c55e",
+    }
+
+    # Draw the arc segments.
+    segment_data = [
+        (0.00, 0.15, "#dc2626", "Angry"),
+        (0.15, 0.30, "#f97316", "Negative"),
+        (0.30, 0.45, "#eab308", "Frustrated"),
+        (0.45, 0.65, "#6b7280", "Neutral"),
+        (0.65, 1.00, "#22c55e", "Positive"),
+    ]
+    for start_frac, end_frac, color, _ in segment_data:
+        theta_start = np.pi * (1 - end_frac)
+        theta_end = np.pi * (1 - start_frac)
+        theta_range = np.linspace(theta_start, theta_end, 50)
+        ax.fill_between(theta_range, 0.6, 1.0, color=color, alpha=0.35)
+
+    # Needle position.
+    needle_frac = sentiment_positions.get(result.dominant, 0.5)
+    # Blend with confidence: low confidence pulls toward center.
+    blended_frac = 0.5 + (needle_frac - 0.5) * result.dominant_confidence
+    needle_theta = np.pi * (1 - blended_frac)
+    needle_color = sentiment_colors.get(result.dominant, "#6b7280")
+
+    ax.plot(
+        [needle_theta, needle_theta],
+        [0, 0.95],
+        color=needle_color,
+        linewidth=3,
+        solid_capstyle="round",
+    )
+    ax.scatter([needle_theta], [0.0], color=needle_color, s=80, zorder=5)
+
+    # Labels on the arc.
+    for start_frac, end_frac, color, label in segment_data:
+        mid_frac = (start_frac + end_frac) / 2
+        mid_theta = np.pi * (1 - mid_frac)
+        ax.text(
+            mid_theta,
+            1.18,
+            label,
+            ha="center",
+            va="center",
+            fontsize=8,
+            fontweight="bold",
+            color=color,
+        )
+
+    ax.set_ylim(0, 1.4)
+    ax.set_thetamin(0)
+    ax.set_thetamax(180)
+    ax.set_axis_off()
+
+    # Title below the gauge.
+    fig.text(
+        0.5,
+        0.10,
+        f"{result.dominant.upper()}  ({result.dominant_confidence:.0%} confidence)",
+        ha="center",
+        va="center",
+        fontsize=14,
+        fontweight="bold",
+        color=needle_color,
+    )
+
+    fig.tight_layout(pad=1.0)
+    return fig
+
+
+def run_sentiment_analysis(
+    text: str,
+) -> tuple[plt.Figure, str]:
+    """Entry point for the Sentiment Analyzer tab."""
+    result = analyze_sentiment(text)
+    gauge = _render_sentiment_gauge(result)
+
+    breakdown_lines = [
+        "Sentiment Breakdown",
+        "---",
+        f"  Positive:    {result.positive:.1%}",
+        f"  Neutral:     {result.neutral:.1%}",
+        f"  Frustrated:  {result.frustrated:.1%}",
+        f"  Negative:    {result.negative:.1%}",
+        f"  Angry:       {result.angry:.1%}",
+        "",
+        f"Dominant sentiment:  {result.dominant}",
+        f"Confidence:          {result.dominant_confidence:.1%}",
+    ]
+    return gauge, "\n".join(breakdown_lines)
+
+
+# ---------------------------------------------------------------------------
+# Tab 3 -- Customer Health Score
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class HealthScoreResult:
+    overall_score: int
+    churn_risk: str
+    recency_score: float
+    ticket_score: float
+    nps_score: float
+    usage_score: float
+    breakdown_text: str
+
+
+def _score_recency(days_since_login: int) -> float:
+    """Score recency: 100 for today, decays toward 0 at ~90+ days."""
+    if days_since_login <= 0:
+        return 100.0
+    if days_since_login >= 120:
+        return 0.0
+    # Exponential decay: half-life at ~14 days.
+    return 100.0 * math.exp(-0.03 * days_since_login)
+
+
+def _score_tickets(ticket_count: int) -> float:
+    """Score ticket load: 0 tickets = 100, decays with more tickets."""
+    if ticket_count <= 0:
+        return 100.0
+    if ticket_count >= 20:
+        return 0.0
+    # Linear with a steep drop after 5.
+    if ticket_count <= 2:
+        return 100.0 - ticket_count * 5
+    return max(0.0, 100.0 - 10 * ticket_count)
+
+
+def _score_nps(nps: int) -> float:
+    """Score NPS: direct 0-100 mapping from 0-10 scale."""
+    clamped = max(0, min(10, nps))
+    return clamped * 10.0
+
+
+def _score_usage_trend(trend_pct: float) -> float:
+    """Score usage trend: +50% = 100, 0% = 50, -50% = 0."""
+    clamped = max(-100.0, min(100.0, trend_pct))
+    return 50.0 + clamped * 0.5
+
+
+def _classify_churn_risk(score: int) -> str:
+    if score < CHURN_THRESHOLDS["critical"]:
+        return "CRITICAL"
+    if score < CHURN_THRESHOLDS["high"]:
+        return "HIGH"
+    if score < CHURN_THRESHOLDS["medium"]:
+        return "MEDIUM"
+    return "LOW"
+
+
+def calculate_health_score(
+    days_since_login: int,
+    support_tickets_30d: int,
+    nps_score: int,
+    usage_trend_pct: float,
+) -> HealthScoreResult:
+    """Calculate weighted customer health score."""
+    recency = _score_recency(days_since_login)
+    tickets = _score_tickets(support_tickets_30d)
+    nps = _score_nps(nps_score)
+    usage = _score_usage_trend(usage_trend_pct)
+
+    weighted = (
+        recency * HEALTH_WEIGHTS["recency"]
+        + tickets * HEALTH_WEIGHTS["ticket_load"]
+        + nps * HEALTH_WEIGHTS["nps"]
+        + usage * HEALTH_WEIGHTS["usage_trend"]
+    )
+    overall = int(round(_clamp(weighted, 0.0, 100.0)))
+    churn_risk = _classify_churn_risk(overall)
+
+    breakdown = (
+        "SCORING FORMULA\n"
+        "===============\n"
+        f"  Recency        ({HEALTH_WEIGHTS['recency']:.0%} weight):  "
+        f"{recency:5.1f} / 100\n"
+        f"  Ticket Load    ({HEALTH_WEIGHTS['ticket_load']:.0%} weight):  "
+        f"{tickets:5.1f} / 100\n"
+        f"  NPS            ({HEALTH_WEIGHTS['nps']:.0%} weight):  "
+        f"{nps:5.1f} / 100\n"
+        f"  Usage Trend    ({HEALTH_WEIGHTS['usage_trend']:.0%} weight):  "
+        f"{usage:5.1f} / 100\n"
+        "---------------------------------------\n"
+        f"  Weighted Total:               {weighted:5.1f}\n"
+        f"  Overall Score:                {overall}\n"
+        f"  Churn Risk:                   {churn_risk}\n"
+        "\n"
+        "THRESHOLDS\n"
+        "==========\n"
+        f"  < {CHURN_THRESHOLDS['critical']}  = CRITICAL    "
+        f"  < {CHURN_THRESHOLDS['high']}  = HIGH\n"
+        f"  < {CHURN_THRESHOLDS['medium']}  = MEDIUM      "
+        f"  >= {CHURN_THRESHOLDS['medium']} = LOW\n"
+        "\n"
+        "COMPONENT DETAILS\n"
+        "=================\n"
+        f"  Recency:      Exponential decay (half-life ~23 days). "
+        f"Input: {days_since_login} days.\n"
+        f"  Ticket Load:  Linear penalty, steep after 5 tickets. "
+        f"Input: {support_tickets_30d} tickets.\n"
+        f"  NPS:          Direct 0-10 to 0-100 mapping. "
+        f"Input: {nps_score}.\n"
+        f"  Usage Trend:  Linear scale, 0% = 50pts, +/-100% = 100/0pts. "
+        f"Input: {usage_trend_pct:+.0f}%."
+    )
+
+    return HealthScoreResult(
+        overall_score=overall,
+        churn_risk=churn_risk,
+        recency_score=recency,
+        ticket_score=tickets,
+        nps_score=nps,
+        usage_score=usage,
+        breakdown_text=breakdown,
+    )
+
+
+def _render_health_gauge(result: HealthScoreResult) -> plt.Figure:
+    """Render a horizontal bar showing overall health score."""
+    fig, ax = plt.subplots(figsize=(8, 2.0))
+    fig.patch.set_facecolor("#0b0f19")
+    ax.set_facecolor("#0b0f19")
+
+    # Gradient background bar.
+    gradient = np.linspace(0, 1, 256).reshape(1, -1)
+    red_to_green = matplotlib.colors.LinearSegmentedColormap.from_list(
+        "health", ["#dc2626", "#f97316", "#eab308", "#22c55e"]
+    )
+    ax.imshow(
+        gradient,
+        aspect="auto",
+        cmap=red_to_green,
+        extent=[0, 100, 0, 1],
+        alpha=0.4,
+    )
+
+    # Score marker.
+    score = result.overall_score
+    risk_colors = {
+        "CRITICAL": "#dc2626",
+        "HIGH": "#f97316",
+        "MEDIUM": "#eab308",
+        "LOW": "#22c55e",
+    }
+    marker_color = risk_colors.get(result.churn_risk, "#6b7280")
+    ax.axvline(x=score, color=marker_color, linewidth=4, ymin=0.1, ymax=0.9)
+    ax.scatter([score], [0.5], color=marker_color, s=200, zorder=5)
+
+    ax.text(
+        score,
+        1.35,
+        f"{score}",
+        ha="center",
+        va="bottom",
+        fontsize=22,
+        fontweight="bold",
+        color=marker_color,
+    )
+    ax.text(
+        score,
+        -0.35,
+        f"Churn Risk: {result.churn_risk}",
+        ha="center",
+        va="top",
+        fontsize=11,
+        fontweight="bold",
+        color=marker_color,
+    )
+
+    # Threshold markers.
+    for label, threshold in CHURN_THRESHOLDS.items():
+        ax.axvline(x=threshold, color="#4b5563", linewidth=1, linestyle="--", alpha=0.6)
+        ax.text(
+            threshold,
+            1.1,
+            str(threshold),
+            ha="center",
+            va="bottom",
+            fontsize=8,
+            color="#9ca3af",
+        )
+
+    ax.set_xlim(0, 100)
+    ax.set_ylim(-0.5, 1.8)
+    ax.set_axis_off()
+    fig.tight_layout(pad=0.5)
+    return fig
+
+
+def run_health_score(
+    days_since_login: int,
+    support_tickets: int,
+    nps: int,
+    usage_trend: float,
+) -> tuple[plt.Figure, str]:
+    """Entry point for the Health Score tab."""
+    result = calculate_health_score(
+        int(days_since_login),
+        int(support_tickets),
+        int(nps),
+        float(usage_trend),
+    )
+    gauge = _render_health_gauge(result)
+    return gauge, result.breakdown_text
+
+
+# ---------------------------------------------------------------------------
+# Tab 4 -- Ticket Categorizer
+# ---------------------------------------------------------------------------
+
+CATEGORY_KEYWORDS: dict[str, list[tuple[str, float]]] = {
+    "billing": [
+        ("invoice", 0.35), ("charge", 0.30), ("payment", 0.35),
+        ("billing", 0.40), ("subscription", 0.30), ("refund", 0.35),
+        ("credit card", 0.35), ("plan", 0.20), ("upgrade", 0.25),
+        ("downgrade", 0.25), ("prorate", 0.35), ("proration", 0.35),
+        ("receipt", 0.30), ("overcharged", 0.35), ("pricing", 0.30),
+        ("cost", 0.20), ("fee", 0.25), ("renewal", 0.30),
+        ("trial", 0.25), ("coupon", 0.30), ("discount", 0.25),
+    ],
+    "technical": [
+        ("error", 0.25), ("crash", 0.35), ("api", 0.30),
+        ("timeout", 0.30), ("ssl", 0.35), ("certificate", 0.30),
+        ("endpoint", 0.30), ("server", 0.25), ("database", 0.30),
+        ("integration", 0.25), ("webhook", 0.30), ("latency", 0.30),
+        ("performance", 0.25), ("deploy", 0.25), ("configuration", 0.25),
+        ("dns", 0.30), ("404", 0.30), ("500", 0.30), ("502", 0.30),
+        ("connection", 0.20), ("sync", 0.20), ("load", 0.15),
+    ],
+    "account": [
+        ("password", 0.35), ("login", 0.30), ("account", 0.25),
+        ("access", 0.20), ("permission", 0.30), ("role", 0.25),
+        ("sso", 0.35), ("mfa", 0.35), ("two factor", 0.35),
+        ("locked out", 0.35), ("reset", 0.25), ("email change", 0.30),
+        ("profile", 0.20), ("team member", 0.25), ("invite", 0.25),
+        ("deactivate", 0.25), ("username", 0.30), ("sign in", 0.30),
+        ("authentication", 0.35), ("session", 0.25), ("token", 0.25),
+    ],
+    "feature_request": [
+        ("feature", 0.30), ("request", 0.20), ("would be nice", 0.35),
+        ("could you add", 0.35), ("suggestion", 0.30),
+        ("it would help", 0.30), ("wish", 0.25), ("roadmap", 0.30),
+        ("planned", 0.20), ("enhancement", 0.30), ("improve", 0.20),
+        ("add support for", 0.35), ("capability", 0.20),
+        ("missing feature", 0.35), ("need ability", 0.30),
+        ("want to be able", 0.35), ("should support", 0.30),
+    ],
+    "bug_report": [
+        ("bug", 0.40), ("broken", 0.30), ("not working", 0.35),
+        ("doesn't work", 0.35), ("does not work", 0.35),
+        ("unexpected", 0.25), ("wrong", 0.20), ("incorrect", 0.25),
+        ("should be", 0.20), ("supposed to", 0.25), ("regression", 0.40),
+        ("reproduce", 0.35), ("steps to", 0.20), ("intermittent", 0.30),
+        ("flaky", 0.30), ("glitch", 0.30), ("malfunction", 0.30),
+        ("behaving", 0.15), ("issue", 0.15), ("problem", 0.15),
+    ],
+}
+
+CATEGORY_DISPLAY_NAMES = {
+    "billing": "Billing",
+    "technical": "Technical Support",
+    "account": "Account Management",
+    "feature_request": "Feature Request",
+    "bug_report": "Bug Report",
+}
+
+
+@dataclass(frozen=True)
+class CategorizationResult:
+    category: str
+    display_name: str
+    confidence: float
+    all_scores: dict[str, float]
+    reasoning: str
+
+
+def categorize_ticket(text: str) -> CategorizationResult:
+    """Categorize a support ticket using keyword matching."""
+    if not text or not text.strip():
+        return CategorizationResult(
+            category="uncategorized",
+            display_name="Uncategorized",
+            confidence=0.0,
+            all_scores={name: 0.0 for name in TICKET_CATEGORIES},
+            reasoning="No ticket text provided.",
+        )
+
+    text_lower = text.lower()
+    raw_scores: dict[str, float] = {}
+
+    matched_keywords: dict[str, list[str]] = {}
+    for category, keywords in CATEGORY_KEYWORDS.items():
+        score = 0.0
+        matches: list[str] = []
+        for keyword, weight in keywords:
+            if keyword in text_lower:
+                score += weight
+                matches.append(keyword)
+        raw_scores[category] = score
+        matched_keywords[category] = matches
+
+    total = sum(raw_scores.values())
+    if total == 0:
+        normalized = {cat: 1.0 / len(TICKET_CATEGORIES) for cat in TICKET_CATEGORIES}
+        top_category = "technical"  # default fallback
+        confidence = round(normalized[top_category], 3)
+    else:
+        normalized = {cat: raw_scores[cat] / total for cat in TICKET_CATEGORIES}
+        top_category = max(normalized, key=lambda k: normalized[k])
+        confidence = round(normalized[top_category], 3)
+
+    # Build reasoning text.
+    reasoning_lines = ["Category Scores", "---"]
+    for cat in TICKET_CATEGORIES:
+        display = CATEGORY_DISPLAY_NAMES[cat]
+        pct = normalized.get(cat, 0.0)
+        kw_list = matched_keywords.get(cat, [])
+        kw_display = ", ".join(kw_list) if kw_list else "(none)"
+        reasoning_lines.append(f"  {display:.<25s} {pct:.1%}")
+        reasoning_lines.append(f"    Matched keywords: {kw_display}")
+
+    reasoning_lines.extend([
+        "",
+        f"Assigned Category:  {CATEGORY_DISPLAY_NAMES[top_category]}",
+        f"Confidence:         {confidence:.1%}",
+    ])
+
+    return CategorizationResult(
+        category=top_category,
+        display_name=CATEGORY_DISPLAY_NAMES[top_category],
+        confidence=confidence,
+        all_scores={cat: round(normalized[cat], 3) for cat in TICKET_CATEGORIES},
+        reasoning="\n".join(reasoning_lines),
+    )
+
+
+def _render_category_chart(result: CategorizationResult) -> plt.Figure:
+    """Horizontal bar chart of category confidence scores."""
+    fig, ax = plt.subplots(figsize=(7, 3))
+    fig.patch.set_facecolor("#0b0f19")
+    ax.set_facecolor("#0b0f19")
+
+    categories = list(result.all_scores.keys())
+    scores = [result.all_scores[c] for c in categories]
+    display_names = [CATEGORY_DISPLAY_NAMES[c] for c in categories]
+
+    # Sort by score descending.
+    sorted_indices = sorted(range(len(scores)), key=lambda i: scores[i])
+    display_names = [display_names[i] for i in sorted_indices]
+    scores = [scores[i] for i in sorted_indices]
+    categories_sorted = [categories[i] for i in sorted_indices]
+
+    bar_colors = [
+        "#3b82f6" if c != result.category else "#22c55e"
+        for c in categories_sorted
+    ]
+
+    bars = ax.barh(display_names, scores, color=bar_colors, height=0.6, alpha=0.85)
+
+    for bar, score in zip(bars, scores):
+        if score > 0.02:
+            ax.text(
+                bar.get_width() + 0.02,
+                bar.get_y() + bar.get_height() / 2,
+                f"{score:.0%}",
+                va="center",
+                ha="left",
+                fontsize=10,
+                color="#e5e7eb",
+                fontweight="bold",
+            )
+
+    ax.set_xlim(0, max(scores) * 1.3 if max(scores) > 0 else 1.0)
+    ax.tick_params(colors="#9ca3af", labelsize=10)
+    ax.spines["top"].set_visible(False)
+    ax.spines["right"].set_visible(False)
+    ax.spines["bottom"].set_color("#374151")
+    ax.spines["left"].set_color("#374151")
+    ax.xaxis.set_visible(False)
+
+    fig.tight_layout(pad=1.0)
+    return fig
+
+
+def run_ticket_categorization(text: str) -> tuple[plt.Figure, str]:
+    """Entry point for the Ticket Categorizer tab."""
+    result = categorize_ticket(text)
+    chart = _render_category_chart(result)
+    return chart, result.reasoning
+
+
+# ---------------------------------------------------------------------------
+# Gradio UI
+# ---------------------------------------------------------------------------
+
+CUSTOM_CSS = """
+.gradio-container {
+    max-width: 1100px !important;
+    margin: auto;
+}
+.app-header {
+    text-align: center;
+    padding: 1.5rem 0 0.5rem 0;
+}
+.app-header h1 {
+    font-size: 2rem;
+    font-weight: 700;
+    color: #e5e7eb;
+    margin-bottom: 0.25rem;
+}
+.app-header p {
+    color: #9ca3af;
+    font-size: 1rem;
+}
+footer {
+    display: none !important;
+}
+"""
+
+
+HERALD_THEME = gr.themes.Base(
+    primary_hue=gr.themes.colors.blue,
+    secondary_hue=gr.themes.colors.gray,
+    neutral_hue=gr.themes.colors.gray,
+    font=gr.themes.GoogleFont("Inter"),
+).set(
+    body_background_fill="#0b0f19",
+    body_background_fill_dark="#0b0f19",
+    block_background_fill="#111827",
+    block_background_fill_dark="#111827",
+    block_border_color="#1f2937",
+    block_border_color_dark="#1f2937",
+    block_label_text_color="#9ca3af",
+    block_label_text_color_dark="#9ca3af",
+    block_title_text_color="#e5e7eb",
+    block_title_text_color_dark="#e5e7eb",
+    body_text_color="#d1d5db",
+    body_text_color_dark="#d1d5db",
+    input_background_fill="#1f2937",
+    input_background_fill_dark="#1f2937",
+    input_border_color="#374151",
+    input_border_color_dark="#374151",
+    button_primary_background_fill="#2563eb",
+    button_primary_background_fill_dark="#2563eb",
+    button_primary_text_color="#ffffff",
+    button_primary_text_color_dark="#ffffff",
+)
+
+
+def build_app() -> gr.Blocks:
+    """Construct and return the Gradio Blocks application."""
+    # Gradio 6+ moved theme/css from Blocks() to launch().
+    # Gradio 5.x accepts them in the constructor.
+    blocks_kwargs: dict[str, object] = {"title": APP_TITLE}
+    if not _GRADIO_6_PLUS:
+        blocks_kwargs["theme"] = HERALD_THEME
+        blocks_kwargs["css"] = CUSTOM_CSS
+
+    with gr.Blocks(**blocks_kwargs) as app:  # type: ignore[arg-type]
+        gr.HTML(
+            '<div class="app-header">'
+            "<h1>Herald -- Customer Operations Platform</h1>"
+            "<p>AI-powered customer support, sentiment analysis, "
+            "health scoring, and ticket categorization</p>"
+            "</div>"
+        )
+
+        with gr.Tabs():
+            # ----------------------------------------------------------
+            # Tab 1: AI Support Chat
+            # ----------------------------------------------------------
+            with gr.Tab("AI Support Chat"):
+                gr.Markdown(
+                    "Simulated customer support chatbot with knowledge-base "
+                    "citations. Select a customer scenario, then step through "
+                    "the conversation."
+                )
+                with gr.Row():
+                    scenario_dropdown = gr.Dropdown(
+                        choices=[
+                            (v["label"], k)
+                            for k, v in CUSTOMER_PROFILES.items()
+                        ],
+                        value="returning_user",
+                        label="Customer Scenario",
+                        interactive=True,
+                    )
+                with gr.Row():
+                    start_btn = gr.Button("Start Conversation", variant="primary")
+                    next_btn = gr.Button("Next Response", variant="secondary")
+
+                # Gradio 6+ removed the type parameter (messages is default).
+                # Gradio 5.x requires type="messages" for dict-format history.
+                chatbot_kwargs: dict[str, object] = {
+                    "label": "Support Conversation",
+                    "height": 480,
+                }
+                if not _GRADIO_6_PLUS:
+                    chatbot_kwargs["type"] = "messages"
+                chatbot = gr.Chatbot(**chatbot_kwargs)  # type: ignore[arg-type]
+                turn_state = gr.State(value=0)
+                chat_status = gr.Textbox(
+                    label="Status",
+                    interactive=False,
+                    value="Select a scenario and click 'Start Conversation'.",
+                )
+
+                start_btn.click(
+                    fn=start_chat,
+                    inputs=[scenario_dropdown],
+                    outputs=[chatbot, turn_state, chat_status],
+                )
+                next_btn.click(
+                    fn=next_turn,
+                    inputs=[scenario_dropdown, turn_state, chatbot],
+                    outputs=[chatbot, turn_state, chat_status],
+                )
+
+            # ----------------------------------------------------------
+            # Tab 2: Sentiment Analyzer
+            # ----------------------------------------------------------
+            with gr.Tab("Sentiment Analyzer"):
+                gr.Markdown(
+                    "Paste a customer message to analyze its sentiment. "
+                    "Uses keyword and pattern matching to score across five "
+                    "dimensions: positive, neutral, frustrated, negative, angry."
+                )
+                sentiment_input = gr.Textbox(
+                    label="Customer Message",
+                    placeholder=(
+                        "e.g., This is the third time my order has been "
+                        "delayed. I'm really frustrated with the service."
+                    ),
+                    lines=5,
+                )
+                sentiment_btn = gr.Button("Analyze Sentiment", variant="primary")
+                with gr.Row():
+                    sentiment_gauge = gr.Plot(label="Sentiment Gauge")
+                    sentiment_breakdown = gr.Textbox(
+                        label="Detailed Breakdown",
+                        lines=12,
+                        interactive=False,
+                    )
+
+                sentiment_btn.click(
+                    fn=run_sentiment_analysis,
+                    inputs=[sentiment_input],
+                    outputs=[sentiment_gauge, sentiment_breakdown],
+                )
+
+                gr.Examples(
+                    examples=[
+                        [
+                            "Your team was incredibly helpful. The issue was "
+                            "resolved within minutes. Thank you so much!"
+                        ],
+                        [
+                            "I've been waiting 3 days for a response. This "
+                            "is the second time I've had to follow up. "
+                            "Seriously frustrating."
+                        ],
+                        [
+                            "THIS IS UNACCEPTABLE!!! I want a refund "
+                            "IMMEDIATELY. Your service is a complete scam "
+                            "and I will be contacting my lawyer."
+                        ],
+                        [
+                            "I have a question about the export feature. "
+                            "Can I schedule automated CSV exports?"
+                        ],
+                    ],
+                    inputs=[sentiment_input],
+                    label="Example Messages",
+                )
+
+            # ----------------------------------------------------------
+            # Tab 3: Customer Health Score
+            # ----------------------------------------------------------
+            with gr.Tab("Customer Health Score"):
+                gr.Markdown(
+                    "Calculate a customer health score (0-100) with churn "
+                    "risk classification. The score is a weighted composite "
+                    "of four engagement signals."
+                )
+                with gr.Row():
+                    with gr.Column():
+                        days_input = gr.Slider(
+                            label="Days Since Last Login",
+                            minimum=0,
+                            maximum=180,
+                            value=5,
+                            step=1,
+                        )
+                        tickets_input = gr.Slider(
+                            label="Support Tickets (Last 30 Days)",
+                            minimum=0,
+                            maximum=25,
+                            value=1,
+                            step=1,
+                        )
+                    with gr.Column():
+                        nps_input = gr.Slider(
+                            label="NPS Score (0-10)",
+                            minimum=0,
+                            maximum=10,
+                            value=8,
+                            step=1,
+                        )
+                        usage_input = gr.Slider(
+                            label="Usage Trend (% change, last 30 days)",
+                            minimum=-100,
+                            maximum=100,
+                            value=10,
+                            step=5,
+                        )
+                health_btn = gr.Button("Calculate Health Score", variant="primary")
+                health_gauge = gr.Plot(label="Health Score")
+                health_breakdown = gr.Textbox(
+                    label="Score Breakdown and Formula",
+                    lines=20,
+                    interactive=False,
+                )
+
+                health_btn.click(
+                    fn=run_health_score,
+                    inputs=[days_input, tickets_input, nps_input, usage_input],
+                    outputs=[health_gauge, health_breakdown],
+                )
+
+            # ----------------------------------------------------------
+            # Tab 4: Ticket Categorizer
+            # ----------------------------------------------------------
+            with gr.Tab("Ticket Categorizer"):
+                gr.Markdown(
+                    "Paste a support ticket to automatically categorize it. "
+                    "Uses keyword matching across five categories: Billing, "
+                    "Technical Support, Account Management, Feature Request, "
+                    "Bug Report."
+                )
+                ticket_input = gr.Textbox(
+                    label="Support Ticket",
+                    placeholder=(
+                        "e.g., Our API integration is returning 500 errors "
+                        "intermittently. The webhook endpoint times out "
+                        "after 30 seconds."
+                    ),
+                    lines=5,
+                )
+                ticket_btn = gr.Button("Categorize Ticket", variant="primary")
+                with gr.Row():
+                    ticket_chart = gr.Plot(label="Category Confidence")
+                    ticket_reasoning = gr.Textbox(
+                        label="Classification Details",
+                        lines=16,
+                        interactive=False,
+                    )
+
+                ticket_btn.click(
+                    fn=run_ticket_categorization,
+                    inputs=[ticket_input],
+                    outputs=[ticket_chart, ticket_reasoning],
+                )
+
+                gr.Examples(
+                    examples=[
+                        [
+                            "I was charged twice for my subscription this "
+                            "month. My invoice shows two payments of $49.99. "
+                            "I need a refund for the duplicate charge."
+                        ],
+                        [
+                            "The dashboard crashes every time I try to "
+                            "apply a date filter. Steps to reproduce: "
+                            "1) Open Analytics, 2) Click date picker, "
+                            "3) Select custom range. Browser: Chrome 122."
+                        ],
+                        [
+                            "It would be really helpful if Herald supported "
+                            "Slack integration for ticket notifications. "
+                            "Could you add this to the roadmap?"
+                        ],
+                        [
+                            "I can't log in to my account. I've tried "
+                            "resetting my password but the reset email "
+                            "never arrives. My username is jsmith@corp.com."
+                        ],
+                    ],
+                    inputs=[ticket_input],
+                    label="Example Tickets",
+                )
+
+        gr.HTML(
+            '<div style="text-align:center; padding:1rem; color:#6b7280; '
+            'font-size:0.85rem;">'
+            "Herald -- Customer Operations Platform | "
+            '<a href="https://github.com/dbhavery/herald" '
+            'style="color:#3b82f6;" target="_blank">GitHub</a>'
+            "</div>"
+        )
+
+    return app
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    application = build_app()
+    launch_kwargs: dict[str, object] = {}
+    if _GRADIO_6_PLUS:
+        launch_kwargs["theme"] = HERALD_THEME
+        launch_kwargs["css"] = CUSTOM_CSS
+    application.launch(**launch_kwargs)  # type: ignore[arg-type]

requirements.txt

@@ -0,0 +1,3 @@
+gradio==5.29.0
+numpy==2.2.6
+matplotlib==3.10.3