feat: add SLA breach reporting functionality and related API endpoints

Signed-off-by: Andre Bossard <anbossar@microsoft.com>

Author: abossard

backend/app.py

@@ -623,6 +623,28 @@ async def get_csv_ticket_stats():
     })
 
 
+@app.route("/api/csv-tickets/sla-breach", methods=["GET"])
+async def get_csv_tickets_sla_breach():
+    """
+    Return unassigned tickets grouped by SLA breach status (breached → at_risk),
+    sorted by age_hours descending within each group.
+
+    Query params:
+    - unassigned_only: true/false (default: true)
+    - include_ok: true/false (default: false) — include non-breached tickets too
+    """
+    from tickets import get_sla_breach_report
+
+    unassigned_only = request.args.get("unassigned_only", "true").lower() != "false"
+    include_ok = request.args.get("include_ok", "false").lower() == "true"
+
+    tickets = _csv_ticket_service.list_tickets(
+        has_assignee=False if unassigned_only else None,
+    )
+    report = get_sla_breach_report(tickets, reference_time=None, include_ok=include_ok)
+    return jsonify(report.model_dump(mode="json"))
+
+
 @app.route("/api/health", methods=["GET"])
 async def health_check():
     """Health check endpoint."""

backend/operations.py

@@ -12,7 +12,13 @@
 from api_decorators import operation
 from csv_data import get_csv_ticket_service
 from tasks import Task, TaskCreate, TaskFilter, TaskService, TaskStats, TaskUpdate
-from tickets import Ticket, TicketStatus
+from tickets import (
+    SlaBreachReport,
+    Ticket,
+    TicketSlaInfo,
+    TicketStatus,
+    get_sla_breach_report,
+)
 
 # Service instances shared across interfaces
 _task_service = TaskService()
@@ -272,6 +278,44 @@ async def op_csv_ticket_fields() -> list[dict[str, str]]:
     return CSV_TICKET_FIELDS
 
 
+@operation(
+    name="csv_sla_breach_tickets",
+    description=(
+        "Return tickets at SLA breach risk from the CSV dataset. "
+        "By default only unassigned tickets (assigned to a group but no individual) are included. "
+        "Results contain pre-computed age_hours, sla_threshold_hours, and breach_status. "
+        "Grouped: 'breached' first, then 'at_risk'. Within each group sorted by age_hours descending. "
+        "The reference timestamp is the maximum created_at date found in the selected tickets "
+        "(not the current system time), making results deterministic for historical datasets. "
+        "SLA thresholds: critical=4h, high=24h, medium=72h, low=120h."
+    ),
+    http_method="GET",
+)
+async def op_csv_sla_breach_tickets(
+    unassigned_only: bool = True,
+    include_ok: bool = False,
+) -> SlaBreachReport:
+    """
+    Pre-compute SLA breach status for CSV tickets.
+
+    Args:
+        unassigned_only: When True (default), only return tickets that are assigned
+            to a group but have no individual assignee — the primary use case for
+            proactive SLA monitoring.
+        include_ok: When True, also include tickets that are within their SLA window.
+            Default False keeps the result focused on actionable items.
+
+    Returns:
+        SlaBreachReport with reference_timestamp, counts, and a sorted list of
+        TicketSlaInfo objects ready for display or further AI commentary.
+    """
+    _ensure_csv_loaded()
+    tickets = _csv_service.list_tickets(
+        has_assignee=False if unassigned_only else None,
+    )
+    return get_sla_breach_report(tickets, reference_time=None, include_ok=include_ok)
+
+
 # Export shared services for callers (REST app, CLI tools, etc.)
 task_service = _task_service
 csv_ticket_service = _csv_service
@@ -290,5 +334,6 @@ async def op_csv_ticket_fields() -> list[dict[str, str]]:
     "op_csv_search_tickets",
     "op_csv_ticket_stats",
     "op_csv_ticket_fields",
+    "op_csv_sla_breach_tickets",
     "CSV_TICKET_FIELDS",
 ]

backend/tickets.py

@@ -57,7 +57,7 @@ class WorkLogType(str, Enum):
 
 
 # ============================================================================
-# PRIORITY SLA DEADLINES (in minutes)
+# PRIORITY SLA DEADLINES (in minutes) — kept for backwards compatibility
 # ============================================================================
 
 PRIORITY_SLA_MINUTES: dict[TicketPriority, int] = {
@@ -68,6 +68,27 @@ class WorkLogType(str, Enum):
 }
 
 
+# ============================================================================
+# SLA BREACH THRESHOLDS (in hours) — used for breach status calculations
+# Aligns with ITSM standard expectations and the frontend dashboard
+# ============================================================================
+
+SLA_THRESHOLD_HOURS: dict[TicketPriority, float] = {
+    TicketPriority.CRITICAL: 4.0,
+    TicketPriority.HIGH: 24.0,
+    TicketPriority.MEDIUM: 72.0,
+    TicketPriority.LOW: 120.0,
+}
+
+
+class SlaBreachStatus(str, Enum):
+    """SLA breach status for a ticket."""
+    BREACHED = "breached"   # age > threshold
+    AT_RISK = "at_risk"     # age > 75% of threshold
+    OK = "ok"               # age <= 75% of threshold
+    UNKNOWN = "unknown"     # cannot determine
+
+
 # ============================================================================
 # WORKLOG MODEL
 # ============================================================================
@@ -377,6 +398,141 @@ def build_reminder_candidate(
     )
 
 
+# ============================================================================
+# SLA BREACH MODELS — for breach-status reporting
+# ============================================================================
+
+class TicketSlaInfo(BaseModel):
+    """SLA breach information for a single ticket."""
+    ticket_id: str = Field(..., description="Incident ID or UUID of the ticket")
+    priority: str = Field(..., description="Ticket priority (critical/high/medium/low)")
+    urgency: Optional[str] = Field(None, description="Urgency level")
+    assigned_group: Optional[str] = Field(None, description="Responsible support team")
+    reported_date: str = Field(..., description="Ticket creation date (ISO format)")
+    age_hours: float = Field(..., description="Hours elapsed since creation (1 decimal)")
+    sla_threshold_hours: float = Field(..., description="SLA threshold in hours for this priority")
+    breach_status: SlaBreachStatus = Field(..., description="Current SLA breach status")
+
+
+class SlaBreachReport(BaseModel):
+    """Aggregated SLA breach report."""
+    reference_timestamp: str = Field(..., description="Reference time used for age calculation")
+    total_breached: int = Field(..., ge=0)
+    total_at_risk: int = Field(..., ge=0)
+    tickets: list[TicketSlaInfo] = Field(default_factory=list)
+
+
+# ============================================================================
+# SLA BREACH CALCULATIONS — Pure functions
+# ============================================================================
+
+def get_sla_threshold_hours(priority: TicketPriority) -> float:
+    """Return the SLA threshold in hours for a given priority."""
+    return SLA_THRESHOLD_HOURS.get(priority, SLA_THRESHOLD_HOURS[TicketPriority.LOW])
+
+
+def calculate_ticket_sla_info(
+    ticket: "Ticket",
+    reference_time: Optional[datetime] = None,
+) -> TicketSlaInfo:
+    """
+    Compute SLA breach information for a single ticket.
+
+    Args:
+        ticket: The ticket to evaluate.
+        reference_time: Anchor for age calculation. When None, uses the current time.
+            Callers managing historical datasets should pass the max date in the
+            dataset so results are deterministic.
+
+    Returns:
+        TicketSlaInfo with pre-computed age_hours and breach_status.
+    """
+    if reference_time is None:
+        reference_time = datetime.now(ticket.created_at.tzinfo)
+
+    delta = reference_time - ticket.created_at
+    age_hours = round(delta.total_seconds() / 3600, 1)
+
+    threshold = get_sla_threshold_hours(ticket.priority)
+
+    if age_hours > threshold:
+        status = SlaBreachStatus.BREACHED
+    elif age_hours > threshold * 0.75:
+        status = SlaBreachStatus.AT_RISK
+    else:
+        status = SlaBreachStatus.OK
+
+    ticket_id = ticket.incident_id or str(ticket.id)
+
+    return TicketSlaInfo(
+        ticket_id=ticket_id,
+        priority=ticket.priority.value,
+        urgency=ticket.urgency,
+        assigned_group=ticket.assigned_group,
+        reported_date=ticket.created_at.isoformat(),
+        age_hours=age_hours,
+        sla_threshold_hours=threshold,
+        breach_status=status,
+    )
+
+
+def get_sla_breach_report(
+    tickets: "list[Ticket]",
+    reference_time: Optional[datetime] = None,
+    include_ok: bool = False,
+) -> SlaBreachReport:
+    """
+    Build a sorted, grouped SLA breach report from a ticket list.
+
+    Grouping order: breached first, then at_risk, then ok (if include_ok).
+    Within each group, sorted by age_hours descending.
+
+    Args:
+        tickets: Tickets to evaluate.
+        reference_time: Anchor timestamp. Uses max created_at in the list when None.
+        include_ok: Whether to include non-breached, non-at-risk tickets.
+
+    Returns:
+        SlaBreachReport with grouped/sorted TicketSlaInfo entries.
+    """
+    if not tickets:
+        ref_str = (reference_time or datetime.now()).isoformat()
+        return SlaBreachReport(reference_timestamp=ref_str, total_breached=0, total_at_risk=0)
+
+    if reference_time is None:
+        reference_time = max(t.created_at for t in tickets)
+
+    infos = [calculate_ticket_sla_info(t, reference_time) for t in tickets]
+
+    group_order = {
+        SlaBreachStatus.BREACHED: 0,
+        SlaBreachStatus.AT_RISK: 1,
+        SlaBreachStatus.OK: 2,
+        SlaBreachStatus.UNKNOWN: 3,
+    }
+
+    filtered = [
+        i for i in infos
+        if i.breach_status in (SlaBreachStatus.BREACHED, SlaBreachStatus.AT_RISK)
+        or (include_ok and i.breach_status == SlaBreachStatus.OK)
+    ]
+
+    sorted_infos = sorted(
+        filtered,
+        key=lambda i: (group_order[i.breach_status], -i.age_hours),
+    )
+
+    total_breached = sum(1 for i in sorted_infos if i.breach_status == SlaBreachStatus.BREACHED)
+    total_at_risk = sum(1 for i in sorted_infos if i.breach_status == SlaBreachStatus.AT_RISK)
+
+    return SlaBreachReport(
+        reference_timestamp=reference_time.isoformat(),
+        total_breached=total_breached,
+        total_at_risk=total_at_risk,
+        tickets=sorted_infos,
+    )
+
+
 # ============================================================================
 # EXPORTS
 # ============================================================================
@@ -387,8 +543,10 @@ def build_reminder_candidate(
     "TicketPriority",
     "ModificationStatus",
     "WorkLogType",
+    "SlaBreachStatus",
     # Constants
     "PRIORITY_SLA_MINUTES",
+    "SLA_THRESHOLD_HOURS",
     # Models
     "Ticket",
     "TicketWithDetails",
@@ -403,6 +561,9 @@ def build_reminder_candidate(
     "ModificationCreate",
     "ModificationReview",
     "OverlayMetadata",
+    # SLA breach models
+    "TicketSlaInfo",
+    "SlaBreachReport",
     # Reminder models
     "ReminderCandidate",
     "ReminderRequest",
@@ -414,4 +575,8 @@ def build_reminder_candidate(
     "is_assigned_without_assignee",
     "count_reminders_in_worklogs",
     "build_reminder_candidate",
+    # SLA breach calculations
+    "get_sla_threshold_hours",
+    "calculate_ticket_sla_info",
+    "get_sla_breach_report",
 ]

frontend/src/features/usecase-demo/demoDefinitions.js

@@ -15,33 +15,18 @@ Für schnelle Ausführung:
 Liefere nur eine kurze, handlungsorientierte Zusammenfassung mit Prioritäten und nächstem Schritt.
 Nutze ausschließlich CSV-Daten und nenne die verwendeten Ticket-IDs in Fließtext.`;
 
-const SLA_BREACH_DEFAULT_PROMPT = `Find all tickets where the "assignee" field is empty (no individual person assigned — note: Status "Assigned" means assigned to a group, NOT to a person. A ticket can have Status="Assigned" and still have no individual assignee).
+const SLA_BREACH_DEFAULT_PROMPT = `Use the csv_sla_breach_tickets tool to retrieve all unassigned tickets at SLA risk.
 
-IMPORTANT: When calling csv_list_tickets, use the "fields" parameter to request ONLY the fields you need: "id,summary,priority,urgency,assignee,assigned_group,created_at". Also use has_assignee=false to filter server-side. This avoids fetching unnecessary data.
-Set limit=100 for initial retrieval and keep this compact field set unless a specific ticket needs deep detail.
-Do not use semantic/text-heavy analysis for this use case; numeric/status/date fields are sufficient.
-Do not include notes/resolution by default; fetch them only for a small number of tickets if strictly required.
+Call it with default parameters (unassigned_only=true, include_ok=false). The tool returns a pre-computed SlaBreachReport with:
+- reference_timestamp: the anchor date used for age calculations (max date in the dataset)
+- total_breached / total_at_risk: summary counts
+- tickets: list of TicketSlaInfo objects already grouped (breached → at_risk) and sorted by age_hours descending
 
-Check these tickets against priority-based SLA thresholds measuring time since created_at (the reported date).
+Output the tickets array as a JSON block with these fields per row:
+  ticket_id, priority, urgency, assigned_group, reported_date, age_hours, sla_threshold_hours, breach_status
 
-IMPORTANT: For the reference timestamp ("now"), do NOT use the current system time. Instead, find the most recent date across all date fields in the CSV data and use that as "now". This ensures meaningful age calculations for demo/historical data.
-
-SLA thresholds by priority:
-- Critical (1): 4 hours
-- High (2): 24 hours (1 day)
-- Medium (3): 72 hours (3 days)
-- Low (4): 120 hours (5 days)
-
-For each matching ticket, compute:
-- age_hours: hours elapsed from reported_date to the reference timestamp
-- sla_threshold_hours: the SLA threshold for its priority
-- breach_status: "breached" if age_hours > sla_threshold_hours, "at risk" if age_hours > 0.75 * sla_threshold_hours, otherwise "ok"
-
-Return ALL tickets with breach_status "breached" or "at risk". Group them by breach_status (all "breached" first, then all "at risk"), and within each group sort by age_hours descending.
-
-Output a JSON array of objects with these fields: ticket_id, priority, urgency, assigned_group (the team responsible), reported_date, age_hours (rounded to 1 decimal), sla_threshold_hours, breach_status.
 After the JSON block, provide a short markdown summary that:
-1. States the reference timestamp used
+1. States the reference_timestamp used
 2. Groups ticket counts by breach_status and assigned_group
 3. Recommends actions for the most critical breaches`;