@tencent-rtc/trtc-agent-skills 0.1.3 → 0.1.4

package/skills/trtc-ai-service/capabilities/human-handoff/src/adapters/local_queue.py

@@ -0,0 +1,258 @@
+"""LocalQueueHandoffClient — default local implementation.
+
+Zero external dependencies, in-process queuing + agent allocation. Migrated from the original queue.py implementation as the "default out-of-the-box" version.
+
+Implementation notes:
+- user_id also serves as ticket_id (keeping behavior consistent with old session_id)
+- State machine:
+    PENDING ──connect──▶ PROCESSING
+       │  ▲                  │
+       │  │                  ▼
+     cancel/timeout       cancel/close
+- Single-process RLock protection; cross-process sync handled by integrator upper layer (e.g. Redis)
+- Capacity and agent count read from environment variables; can be overridden via constructor
+"""
+from __future__ import annotations
+
+import os
+import threading
+from typing import Dict, List, Optional
+
+from ..core.models import (
+    OverallStatus,
+    Ticket,
+    TicketStatus,
+    TicketStatusEnum,
+    now_ts,
+)
+from ..ports.handoff_client import HandoffClient
+
+
+class LocalQueueHandoffClient(HandoffClient):
+    """In-process in-memory queuing HandoffClient implementation."""
+
+    def __init__(
+        self,
+        *,
+        capacity: int = 50,
+        agent_pool_size: int = 1,
+        estimated_wait_per_slot: int = 30,
+    ) -> None:
+        self._lock = threading.RLock()
+        self._tickets: Dict[str, Ticket] = {}     # ticket_id -> Ticket
+        self._waiting: List[str] = []             # ticket_id list, FIFO
+        self._connected: Dict[str, str] = {}      # ticket_id -> agent_id
+        self._capacity = int(capacity)
+        self._pool = int(agent_pool_size)
+        self._wait_per_slot = max(1, int(estimated_wait_per_slot))
+
+    # ------------------------------------------------------------------
+    # HandoffClient required implementations
+    # ------------------------------------------------------------------
+    def create_ticket(
+        self,
+        *,
+        user_id: str,
+        subject: str = "",
+        description: str = "",
+        priority: str = "normal",
+        transcript: Optional[List[str]] = None,
+    ) -> Ticket:
+        if not user_id:
+            raise ValueError("user_id is required")
+        with self._lock:
+            # Only one in-progress ticket per user; if exists, refresh position and return
+            existing = self._find_active_by_user(user_id)
+            if existing is not None:
+                if existing.status == TicketStatusEnum.PROCESSING.value:
+                    return existing
+                self._refresh_position(existing)
+                return existing
+
+            ticket_id = user_id  # Compatible with old behavior: session_id is ticket_id
+            t = Ticket(
+                ticket_id=ticket_id,
+                user_id=user_id,
+                subject=subject,
+                description=description,
+                priority=priority or "normal",
+                transcript=list(transcript or []),
+                reason=description[:128] if description else "",
+                created_at=now_ts(),
+                updated_at=now_ts(),
+            )
+
+            # Queue full and no available agents: mark TIMEOUT
+            if (
+                len(self._waiting) >= self._capacity
+                and self._available_agents() == 0
+            ):
+                t.status = TicketStatusEnum.TIMEOUT.value
+                t.closed_at = now_ts()
+                self._tickets[ticket_id] = t
+                return t
+
+            t.status = TicketStatusEnum.PENDING.value
+            self._tickets[ticket_id] = t
+            self._waiting.append(ticket_id)
+
+            # Auto-connect if an agent is available
+            if self._available_agents() > 0:
+                self._auto_connect()
+            self._refresh_position(t)
+            return t
+
+    def query_status(self, ticket_id: str) -> Optional[TicketStatus]:
+        with self._lock:
+            t = self._tickets.get(ticket_id)
+            if t is None:
+                return None
+            return TicketStatus.from_ticket(t)
+
+    def cancel_ticket(self, ticket_id: str, reason: str = "") -> Optional[Ticket]:
+        with self._lock:
+            t = self._tickets.get(ticket_id)
+            if t is None:
+                return None
+            if t.status == TicketStatusEnum.PROCESSING.value:
+                self._connected.pop(ticket_id, None)
+            self._waiting = [s for s in self._waiting if s != ticket_id]
+            t.status = TicketStatusEnum.CANCELED.value
+            t.reason = reason or t.reason
+            t.closed_at = now_ts()
+            t.updated_at = now_ts()
+            self._refresh_all_positions()
+            return t
+
+    def overall_status(self) -> OverallStatus:
+        with self._lock:
+            return OverallStatus(
+                agent_pool_size=self._pool,
+                available_agents=self._available_agents(),
+                waiting=len(self._waiting),
+                connected=len(self._connected),
+                capacity=self._capacity,
+            )
+
+    # ------------------------------------------------------------------
+    # Dashboard helper methods
+    # ------------------------------------------------------------------
+    def list_tickets(
+        self,
+        *,
+        limit: int = 50,
+        status: Optional[str] = None,
+    ) -> List[Ticket]:
+        with self._lock:
+            items = list(self._tickets.values())
+            if status:
+                items = [t for t in items if t.status == status]
+            items.sort(
+                key=lambda x: (x.created_at or 0.0),
+                reverse=True,
+            )
+            return items[: max(1, int(limit))]
+
+    def update_status(
+        self,
+        ticket_id: str,
+        status: str,
+        *,
+        agent_id: Optional[str] = None,
+    ) -> Optional[Ticket]:
+        try:
+            new_status = TicketStatusEnum(status).value
+        except ValueError as exc:
+            raise ValueError(f"invalid status: {status}") from exc
+
+        with self._lock:
+            t = self._tickets.get(ticket_id)
+            if t is None:
+                return None
+
+            old_status = t.status
+            t.status = new_status
+            t.updated_at = now_ts()
+
+            if new_status == TicketStatusEnum.PROCESSING.value:
+                if old_status != TicketStatusEnum.PROCESSING.value:
+                    if self._available_agents() <= 0 and ticket_id not in self._connected:
+                        # Force connect (manual): open new slot outside agent pool
+                        pass
+                    t.agent_id = agent_id or t.agent_id or f"agent_{ticket_id[-4:]}"
+                    self._connected[ticket_id] = t.agent_id
+                    self._waiting = [s for s in self._waiting if s != ticket_id]
+            elif new_status in (
+                TicketStatusEnum.CLOSED.value,
+                TicketStatusEnum.CANCELED.value,
+                TicketStatusEnum.TIMEOUT.value,
+            ):
+                t.closed_at = now_ts()
+                self._connected.pop(ticket_id, None)
+                self._waiting = [s for s in self._waiting if s != ticket_id]
+            elif new_status == TicketStatusEnum.PENDING.value:
+                self._connected.pop(ticket_id, None)
+                if ticket_id not in self._waiting:
+                    self._waiting.append(ticket_id)
+
+            self._refresh_all_positions()
+            if self._available_agents() > 0:
+                self._auto_connect()
+            return t
+
+    def get_or_attach(self, user_id: str) -> Optional[Ticket]:
+        with self._lock:
+            return self._find_active_by_user(user_id)
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+    def _available_agents(self) -> int:
+        return max(0, self._pool - len(self._connected))
+
+    def _find_active_by_user(self, user_id: str) -> Optional[Ticket]:
+        for t in self._tickets.values():
+            if t.user_id == user_id and t.status in (
+                TicketStatusEnum.PENDING.value,
+                TicketStatusEnum.PROCESSING.value,
+            ):
+                return t
+        return None
+
+    def _auto_connect(self) -> None:
+        while self._waiting and self._available_agents() > 0:
+            tid = self._waiting.pop(0)
+            t = self._tickets.get(tid)
+            if t is None:
+                continue
+            t.status = TicketStatusEnum.PROCESSING.value
+            t.updated_at = now_ts()
+            t.agent_id = f"agent_auto_{int(t.updated_at)}"
+            self._connected[tid] = t.agent_id
+
+    def _refresh_position(self, t: Ticket) -> None:
+        if (
+            t.status == TicketStatusEnum.PENDING.value
+            and t.ticket_id in self._waiting
+        ):
+            pos = self._waiting.index(t.ticket_id) + 1
+            t.queue_position = pos
+            t.eta_seconds = pos * self._wait_per_slot
+        else:
+            t.queue_position = 0
+            t.eta_seconds = 0
+
+    def _refresh_all_positions(self) -> None:
+        for t in self._tickets.values():
+            self._refresh_position(t)
+
+
+# ---------------------------------------------------------------------------
+# Factory: build default parameters from environment variables
+# ---------------------------------------------------------------------------
+def from_env() -> LocalQueueHandoffClient:
+    return LocalQueueHandoffClient(
+        capacity=int(os.getenv("HH_QUEUE_CAPACITY", "50")),
+        agent_pool_size=int(os.getenv("HH_AGENT_POOL_SIZE", "1")),
+        estimated_wait_per_slot=int(os.getenv("HH_WAIT_PER_SLOT", "30")),
+    )

package/skills/trtc-ai-service/capabilities/human-handoff/src/adapters/mock.py

@@ -0,0 +1,132 @@
+"""MockHandoffClient — mock implementation for Recipe demo recording.
+
+Inherits LocalQueueHandoffClient, pre-seeds several sample tickets on startup so the agent dashboard has content immediately.
+
+Differences from LocalQueueHandoffClient:
+- Seeds example tickets at construction (one each for pending / processing / closed)
+- Marks `is_mock = True`, making it easy to add a "demo data" watermark on the dashboard
+- Demo data uses stable ticket_id prefix `demo_` for reproducible screenshots
+"""
+from __future__ import annotations
+
+from typing import List, Optional
+
+from ..core.models import Ticket, TicketStatusEnum, now_ts
+from .local_queue import LocalQueueHandoffClient
+
+
+class MockHandoffClient(LocalQueueHandoffClient):
+    """Mock implementation for demos."""
+
+    is_mock = True
+
+    def __init__(
+        self,
+        *,
+        capacity: int = 50,
+        agent_pool_size: int = 2,
+        estimated_wait_per_slot: int = 30,
+        seed_demo_data: bool = True,
+    ) -> None:
+        super().__init__(
+            capacity=capacity,
+            agent_pool_size=agent_pool_size,
+            estimated_wait_per_slot=estimated_wait_per_slot,
+        )
+        if seed_demo_data:
+            self._seed()
+
+    def _seed(self) -> None:
+        """Seed demo data. Agent pool occupies 1 slot, leaving 1 free for live connection demos."""
+        ts_base = now_ts() - 600
+
+        # 1) Closed ticket (10 minutes ago)
+        closed = Ticket(
+            ticket_id="demo_closed_001",
+            user_id="demo_user_001",
+            subject="Invoice header correction",
+            description="Shipped order needs invoice header correction",
+            priority="normal",
+            status=TicketStatusEnum.CLOSED.value,
+            agent_id="agent_alice",
+            transcript=[
+                "User: Hi, I need to update the invoice header",
+                "AI: Which order is this regarding?",
+                "User: Order number SO20260601-0042",
+                "[handoff] User requested human agent",
+                "Agent Alice: Done. New invoice will be issued within 30 minutes.",
+            ],
+            reason="Invoice header correction",
+            created_at=ts_base,
+            updated_at=ts_base + 120,
+            closed_at=ts_base + 240,
+        )
+        self._tickets[closed.ticket_id] = closed
+
+        # 2) Processing ticket (occupies 1 agent slot)
+        processing = Ticket(
+            ticket_id="demo_processing_001",
+            user_id="demo_user_002",
+            subject="Return logistics issue",
+            description="Return not picked up for 5 days",
+            priority="high",
+            status=TicketStatusEnum.PROCESSING.value,
+            agent_id="agent_bob",
+            transcript=[
+                "User: My return has been requested 5 days and no one has picked it up yet",
+                "AI: Let me check the logistics status for you...",
+                "AI: Sorry, the logistics API is temporarily unavailable for real-time info",
+                "[handoff] Escalating to human agent",
+                "Agent Bob: Hello, I am following up on your logistics issue",
+            ],
+            reason="Return logistics issue",
+            created_at=ts_base + 300,
+            updated_at=ts_base + 320,
+        )
+        self._tickets[processing.ticket_id] = processing
+        self._connected[processing.ticket_id] = processing.agent_id  # type: ignore[assignment]
+
+        # 3) Pending ticket (FIFO queue head)
+        pending = Ticket(
+            ticket_id="demo_pending_001",
+            user_id="demo_user_003",
+            subject="Refund progress inquiry",
+            description="Refund applied 3 days ago not received",
+            priority="normal",
+            status=TicketStatusEnum.PENDING.value,
+            transcript=[
+                "User: My refund from 3 days ago hasn't arrived yet",
+                "AI: Please provide your order number for lookup",
+                "User: Order SO20260605-0099",
+                "[handoff] Transfer to agent",
+            ],
+            reason="Refund progress",
+            created_at=ts_base + 540,
+            updated_at=ts_base + 540,
+        )
+        self._tickets[pending.ticket_id] = pending
+        self._waiting.append(pending.ticket_id)
+        self._refresh_all_positions()
+
+    def list_tickets(
+        self,
+        *,
+        limit: int = 50,
+        status: Optional[str] = None,
+    ) -> List[Ticket]:
+        # Mock mode defaults to reverse chrono by creation time, consistent with LocalQueue behavior
+        return super().list_tickets(limit=limit, status=status)
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+def from_env() -> MockHandoffClient:
+    import os
+
+    return MockHandoffClient(
+        capacity=int(os.getenv("HH_QUEUE_CAPACITY", "50")),
+        agent_pool_size=int(os.getenv("HH_AGENT_POOL_SIZE", "2")),
+        estimated_wait_per_slot=int(os.getenv("HH_WAIT_PER_SLOT", "30")),
+        seed_demo_data=os.getenv("HH_MOCK_SEED", "1") not in ("0", "false", "False"),
+    )

package/skills/trtc-ai-service/capabilities/human-handoff/src/core/__init__.py

@@ -0,0 +1,25 @@
+"""human-handoff core module."""
+from .intent_detector import IntentDetector, is_handoff_intent
+from .models import (
+    OverallStatus,
+    Ticket,
+    TicketStatus,
+    TicketStatusEnum,
+    now_ts,
+    to_legacy_state,
+)
+from .service import HandoffService, get_default_service, reset_default_service
+
+__all__ = [
+    "HandoffService",
+    "IntentDetector",
+    "OverallStatus",
+    "Ticket",
+    "TicketStatus",
+    "TicketStatusEnum",
+    "get_default_service",
+    "is_handoff_intent",
+    "now_ts",
+    "reset_default_service",
+    "to_legacy_state",
+]

package/skills/trtc-ai-service/capabilities/human-handoff/src/core/intent_detector.py

@@ -0,0 +1,75 @@
+"""Handoff intent detection: keyword strong matching + weak intent (with negative context recognition).
+
+Migrated from original trigger.py. This module does **not depend** on any adapter or global state; pure functions.
+"""
+from __future__ import annotations
+
+import os
+import re
+from typing import List
+
+
+_DEFAULT_TRIGGERS = [
+    "agent", "help", "support",
+    "real person", "talk to agent", "speak to a human", "human agent",
+]
+_DEFAULT_INTENT = ["complain", "manager", "unsatisfied", "escalate"]
+
+
+def _csv_env(key: str, default: List[str]) -> List[str]:
+    raw = os.getenv(key)
+    if not raw:
+        return list(default)
+    return [item.strip() for item in raw.split(",") if item.strip()]
+
+
+class IntentDetector:
+    """Determine whether input text expresses a "handoff" intent using regex."""
+
+    def __init__(
+        self,
+        *,
+        triggers: List[str] | None = None,
+        intent_keywords: List[str] | None = None,
+    ) -> None:
+        self._triggers = triggers if triggers is not None else _csv_env(
+            "HH_TRIGGERS", _DEFAULT_TRIGGERS
+        )
+        self._intent = intent_keywords if intent_keywords is not None else _csv_env(
+            "HH_INTENT_KEYWORDS", _DEFAULT_INTENT
+        )
+        self._triggers_re = re.compile(
+            "|".join(re.escape(k) for k in self._triggers), re.IGNORECASE
+        )
+        self._intent_re = re.compile(
+            "|".join(re.escape(k) for k in self._intent), re.IGNORECASE
+        )
+        self._negative_re = re.compile(
+            r"\b(not|don't|do not|no|never)\b", re.IGNORECASE
+        )
+
+    def is_handoff_intent(self, text: str) -> bool:
+        if not text or len(text) > 4096:
+            return False
+        if self._triggers_re.search(text):
+            return True
+        if self._intent_re.search(text) and not self._negative_re.search(text):
+            return True
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Default singleton (keeps behavior consistent with old trigger.py; tests can manually construct new instances to override)
+# ---------------------------------------------------------------------------
+_default_detector: IntentDetector | None = None
+
+
+def get_default_detector() -> IntentDetector:
+    global _default_detector
+    if _default_detector is None:
+        _default_detector = IntentDetector()
+    return _default_detector
+
+
+def is_handoff_intent(text: str) -> bool:
+    return get_default_detector().is_handoff_intent(text)

package/skills/trtc-ai-service/capabilities/human-handoff/src/core/models.py

@@ -0,0 +1,163 @@
+"""human-handoff core models.
+
+Defines unified domain models:
+- TicketStatusEnum  Ticket status (aligned with business_contract.ticket.status_query.response.status)
+- Ticket            Complete ticket record (transport object between adapters)
+- TicketStatus      Lightweight status view (returned by status_query)
+- OverallStatus     Overall queue status (dashboard use)
+
+The core layer does not know any specific backend implementation; all adapters must use this module's data structures.
+"""
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class TicketStatusEnum(str, Enum):
+    """Ticket status enum.
+
+    Business semantics mapping:
+    - PENDING    User has applied; not yet assigned an agent (equivalent to old HandoffState.WAITING)
+    - PROCESSING Agent assigned, processing (equivalent to old HandoffState.CONNECTED)
+    - CLOSED     Agent closed ticket
+    - CANCELED   User actively canceled
+    - TIMEOUT    Timeout, no agent connected
+    """
+
+    PENDING = "pending"
+    PROCESSING = "processing"
+    CLOSED = "closed"
+    CANCELED = "canceled"
+    TIMEOUT = "timeout"
+
+
+# Status name mapping for old API compatibility (HandoffState era)
+_LEGACY_STATE_MAP = {
+    TicketStatusEnum.PENDING.value: "waiting",
+    TicketStatusEnum.PROCESSING.value: "connected",
+    TicketStatusEnum.CLOSED.value: "closed",
+    TicketStatusEnum.CANCELED.value: "canceled",
+    TicketStatusEnum.TIMEOUT.value: "timeout",
+}
+
+
+def to_legacy_state(status: str) -> str:
+    """Convert new TicketStatusEnum value back to old API state name."""
+    if not status:
+        return "idle"
+    return _LEGACY_STATE_MAP.get(status, status)
+
+
+@dataclass
+class Ticket:
+    """Ticket record. Transport object between adapters.
+
+    user_id and ticket_id default to the same value in LocalQueue implementation (using session_id),
+    REST implementation uses ticket_id returned by the business side.
+    """
+
+    ticket_id: str
+    user_id: str
+    subject: str = ""
+    description: str = ""
+    priority: str = "normal"
+    status: str = TicketStatusEnum.PENDING.value
+    queue_position: int = 0
+    eta_seconds: int = 0
+    agent_id: Optional[str] = None
+    transcript: List[str] = field(default_factory=list)
+    reason: str = ""                          # Trigger reason summary (compatible with old field)
+    created_at: Optional[float] = None
+    updated_at: Optional[float] = None
+    closed_at: Optional[float] = None
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+    @staticmethod
+    def new_id() -> str:
+        return f"tk_{uuid.uuid4().hex[:12]}"
+
+    def to_dict(self) -> dict:
+        return {
+            "ticket_id": self.ticket_id,
+            "session_id": self.user_id,
+            "user_id": self.user_id,
+            "subject": self.subject,
+            "description": self.description,
+            "priority": self.priority,
+            "status": self.status,
+            "queue_position": self.queue_position,
+            "eta_seconds": self.eta_seconds,
+            "agent_id": self.agent_id,
+            "transcript": list(self.transcript),
+            "reason": self.reason,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "closed_at": self.closed_at,
+            # Written at ticket creation by human-handoff - session-summary linkage (None if capability not installed)
+            "session_summary": self.extra.get("session_summary"),
+            # Written by HandoffService.submit_feedback (None if not yet rated)
+            "feedback": self.extra.get("feedback"),
+        }
+
+    def to_legacy_dict(self) -> dict:
+        """Field format returned by old REST API (/api/v1/handoff/*), keeps Web Demo compatibility."""
+        return {
+            "session_id": self.user_id,
+            "state": to_legacy_state(self.status),
+            "reason": self.reason,
+            "requested_at": self.created_at,
+            "connected_at": self.updated_at if self.status == TicketStatusEnum.PROCESSING.value else None,
+            "closed_at": self.closed_at,
+            "agent_id": self.agent_id,
+            "queue_position": self.queue_position,
+            "estimated_wait_seconds": self.eta_seconds,
+        }
+
+
+@dataclass
+class TicketStatus:
+    """Response model corresponding to business_contract.ticket.status_query."""
+
+    ticket_id: str
+    status: str
+    agent_id: Optional[str] = None
+    queue_position: int = 0
+    eta_seconds: int = 0
+    updated_at: Optional[float] = None
+
+    @classmethod
+    def from_ticket(cls, t: Ticket) -> "TicketStatus":
+        return cls(
+            ticket_id=t.ticket_id,
+            status=t.status,
+            agent_id=t.agent_id,
+            queue_position=t.queue_position,
+            eta_seconds=t.eta_seconds,
+            updated_at=t.updated_at or t.created_at,
+        )
+
+
+@dataclass
+class OverallStatus:
+    agent_pool_size: int
+    available_agents: int
+    waiting: int
+    connected: int
+    capacity: int
+
+    def to_dict(self) -> dict:
+        return {
+            "agent_pool_size": self.agent_pool_size,
+            "available_agents": self.available_agents,
+            "waiting": self.waiting,
+            "connected": self.connected,
+            "capacity": self.capacity,
+        }
+
+
+def now_ts() -> float:
+    return time.time()