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

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

@@ -0,0 +1,192 @@
+"""HandoffService — Application service chaining IntentDetector with HandoffClient.
+
+Only depends on ports (HandoffClient interface), does not know the specific backend implementation.
+Switching adapter only requires re-injecting client (adapters.factory.set_client).
+"""
+from __future__ import annotations
+
+from typing import List, Optional
+
+from ..ports.handoff_client import HandoffClient
+from ..summary_link import attach_summary_to_ticket
+from .intent_detector import IntentDetector, get_default_detector
+from .models import OverallStatus, Ticket, TicketStatus, TicketStatusEnum
+
+
+class HandoffService:
+    """Handoff business service."""
+
+    def __init__(
+        self,
+        *,
+        client: HandoffClient,
+        detector: Optional[IntentDetector] = None,
+    ) -> None:
+        self._client = client
+        self._detector = detector or get_default_detector()
+
+    # ------------------------------------------------------------------
+    # Intent detection + trigger (for injection into conversation-core.before_push_text)
+    # ------------------------------------------------------------------
+    def maybe_handoff(self, session_id: str, text: str) -> Optional[str]:
+        """Recognize handoff intent; if matched, request ticket and return assembled script; otherwise return None."""
+        if not session_id or not text:
+            return None
+        if not self._detector.is_handoff_intent(text):
+            return None
+
+        # Reuse existing ticket (don't duplicate for same user in progress)
+        existing = self._client.get_or_attach(session_id)
+        if existing is not None and existing.status in (
+            TicketStatusEnum.PENDING.value,
+            TicketStatusEnum.PROCESSING.value,
+        ):
+            return self._render_handoff_message(existing)
+
+        ticket = self._client.create_ticket(
+            user_id=session_id,
+            subject=text[:64],
+            description=text[:512],
+            priority="normal",
+        )
+        # Attach session summary at ticket creation so agents can immediately see the issue on the dashboard (no-op if session-summary is not installed)
+        attach_summary_to_ticket(ticket)
+        return self._render_handoff_message(ticket)
+
+    @staticmethod
+    def _render_handoff_message(t: Ticket) -> Optional[str]:
+        if t.status == TicketStatusEnum.PROCESSING.value:
+            return (
+                f"[handoff state=connected agent={t.agent_id}]\n"
+                "You are now connected to a human agent. Please wait a moment."
+            )
+        if t.status == TicketStatusEnum.PENDING.value:
+            return (
+                f"[handoff state=waiting position={t.queue_position} "
+                f"eta={t.eta_seconds}s]\n"
+                f"You are number {t.queue_position} in the agent queue, "
+                f"estimated wait {t.eta_seconds} seconds."
+            )
+        if t.status == TicketStatusEnum.TIMEOUT.value:
+            return "[handoff state=timeout]\nNo agents are currently available. Please try again later."
+        return None
+
+    # ------------------------------------------------------------------
+    # Explicit operations (for router calls)
+    # ------------------------------------------------------------------
+    def request(
+        self,
+        session_id: str,
+        *,
+        reason: str = "",
+        subject: Optional[str] = None,
+        description: Optional[str] = None,
+    ) -> Ticket:
+        existing = self._client.get_or_attach(session_id)
+        if existing is not None and existing.status in (
+            TicketStatusEnum.PENDING.value,
+            TicketStatusEnum.PROCESSING.value,
+        ):
+            return existing
+        ticket = self._client.create_ticket(
+            user_id=session_id,
+            subject=(subject or reason or "human handoff")[:64],
+            description=(description or reason or "")[:512],
+            priority="normal",
+        )
+        # Attach session summary at ticket creation (no-op if session-summary not installed; does not affect main flow)
+        attach_summary_to_ticket(ticket)
+        return ticket
+
+    def connect(self, session_id: str, agent_id: str) -> Ticket:
+        """For /api/v1/handoff/connect: force-connect a session to a specified agent."""
+        # Look up active ticket by user_id first
+        ticket = self._client.get_or_attach(session_id)
+        if ticket is None:
+            raise ValueError(f"session {session_id} not waiting")
+        if ticket.status == TicketStatusEnum.PROCESSING.value:
+            return ticket
+        updated = self._client.update_status(
+            ticket.ticket_id,
+            TicketStatusEnum.PROCESSING.value,
+            agent_id=agent_id,
+        )
+        if updated is None:
+            raise ValueError(f"ticket {ticket.ticket_id} not found")
+        return updated
+
+    def cancel(self, session_id: str, *, reason: str = "") -> Ticket:
+        ticket = self._client.get_or_attach(session_id)
+        if ticket is None:
+            raise ValueError(f"session not found: {session_id}")
+        result = self._client.cancel_ticket(ticket.ticket_id, reason=reason)
+        if result is None:
+            raise ValueError(f"ticket {ticket.ticket_id} not found")
+        return result
+
+    def get_by_session(self, session_id: str) -> Optional[Ticket]:
+        return self._client.get_or_attach(session_id)
+
+    def overall_status(self) -> OverallStatus:
+        return self._client.overall_status()
+
+    # ------------------------------------------------------------------
+    # Dashboard helpers
+    # ------------------------------------------------------------------
+    def list_tickets(
+        self,
+        *,
+        limit: int = 50,
+        status: Optional[str] = None,
+    ) -> List[Ticket]:
+        return self._client.list_tickets(limit=limit, status=status)
+
+    def update_ticket_status(
+        self,
+        ticket_id: str,
+        status: str,
+        *,
+        agent_id: Optional[str] = None,
+    ) -> Optional[Ticket]:
+        return self._client.update_status(ticket_id, status, agent_id=agent_id)
+
+    def query_ticket(self, ticket_id: str) -> Optional[TicketStatus]:
+        return self._client.query_status(ticket_id)
+
+    # ------------------------------------------------------------------
+    # Customer satisfaction feedback
+    # ------------------------------------------------------------------
+    def submit_feedback(self, session_id: str, rating: int, comment: str = "") -> dict:
+        """Persist a satisfaction rating and, if a ticket exists for the session,
+        attach it to that ticket so agents can see the score on the dashboard."""
+        from ..feedback_store import make_feedback, save_feedback
+
+        fb = make_feedback(rating, comment)
+        save_feedback(session_id, fb)
+        try:
+            ticket = self._client.get_or_attach(session_id)
+            if ticket is not None:
+                ticket.extra["feedback"] = fb
+        except Exception:  # noqa: BLE001 - feedback must never break on ticket lookup
+            pass
+        return {"session_id": session_id, "feedback": fb}
+
+
+# ---------------------------------------------------------------------------
+# Default service singleton
+# ---------------------------------------------------------------------------
+_default_service: Optional[HandoffService] = None
+
+
+def get_default_service() -> HandoffService:
+    """Build service singleton from current environment (client from adapters.factory)."""
+    global _default_service
+    if _default_service is None:
+        from ..adapters.factory import get_client
+        _default_service = HandoffService(client=get_client())
+    return _default_service
+
+
+def reset_default_service() -> None:
+    global _default_service
+    _default_service = None

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

@@ -0,0 +1,54 @@
+"""In-process satisfaction feedback store (CSAT).
+
+Lightweight memory store keyed by session_id. Used by HandoffService.submit_feedback
+so the dashboard can look up a session's rating without requiring a ticket to exist.
+
+Why memory-only?
+- The default adapter (HH_ADAPTER=local_queue) is itself in-process, so an in-memory
+  feedback store keeps the demo self-contained with zero external dependencies.
+- Production deployments that persist tickets out-of-band should swap this for a
+  persistent sink; the public surface (make_feedback / save_feedback / get_feedback)
+  stays stable.
+"""
+from __future__ import annotations
+
+import threading
+import time
+import uuid
+from typing import Any, Dict, Optional
+
+_lock = threading.RLock()
+_store: Dict[str, Dict[str, Any]] = {}
+
+
+def make_feedback(rating: int, comment: str = "") -> Dict[str, Any]:
+    """Build a normalized feedback record (does not persist)."""
+    rating = int(rating)
+    if rating < 1:
+        rating = 1
+    elif rating > 5:
+        rating = 5
+    return {
+        "feedback_id": f"fb_{uuid.uuid4().hex[:12]}",
+        "rating": rating,
+        "comment": (comment or "").strip()[:1000],
+        "created_at": time.time(),
+    }
+
+
+def save_feedback(session_id: str, feedback: Dict[str, Any]) -> Dict[str, Any]:
+    """Persist a feedback record keyed by session_id (overwrites prior entry)."""
+    if not session_id:
+        raise ValueError("session_id is required")
+    with _lock:
+        _store[session_id] = dict(feedback)
+    return feedback
+
+
+def get_feedback(session_id: str) -> Optional[Dict[str, Any]]:
+    """Return the stored feedback for a session, or None if not rated yet."""
+    if not session_id:
+        return None
+    with _lock:
+        fb = _store.get(session_id)
+        return dict(fb) if fb is not None else None

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

@@ -0,0 +1,4 @@
+"""human-handoff abstract ports module."""
+from .handoff_client import HandoffClient
+
+__all__ = ["HandoffClient"]

package/skills/trtc-ai-service/capabilities/human-handoff/src/ports/handoff_client.py

@@ -0,0 +1,86 @@
+"""human-handoff abstract port (Port).
+
+One-to-one correspondence with manifest.yaml.business_contract fields:
+- create_ticket   -> ticket.create
+- query_status    -> ticket.status_query
+- cancel_ticket   -> ticket.cancel
+- overall_status  -> internal status (not in external contract; for local dashboard use only)
+
+All concrete implementations (local_queue / default_rest / mock / user_custom) must inherit this ABC.
+The core layer only depends on this interface, unaware of any specific backend type; switching backends only requires changing the adapter.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import List, Optional
+
+from ..core.models import OverallStatus, Ticket, TicketStatus
+
+
+class HandoffClient(ABC):
+    """Unified interface contract for handoff / ticketing backends."""
+
+    # --- Methods aligned with business_contract --------------------------
+
+    @abstractmethod
+    def create_ticket(
+        self,
+        *,
+        user_id: str,
+        subject: str = "",
+        description: str = "",
+        priority: str = "normal",
+        transcript: Optional[List[str]] = None,
+    ) -> Ticket:
+        """Create ticket. Corresponds to business_contract.ticket.create."""
+
+    @abstractmethod
+    def query_status(self, ticket_id: str) -> Optional[TicketStatus]:
+        """Query single ticket status. Corresponds to ticket.status_query.
+
+        Returns None if ticket does not exist.
+        """
+
+    @abstractmethod
+    def cancel_ticket(self, ticket_id: str, reason: str = "") -> Optional[Ticket]:
+        """Cancel ticket. Corresponds to ticket.cancel. Returns None if ticket does not exist."""
+
+    @abstractmethod
+    def overall_status(self) -> OverallStatus:
+        """Overall queue status (dashboard use, not external contract)."""
+
+    # --- Dashboard helper methods (default implementation; remote backends may not override) ---------
+
+    def list_tickets(
+        self,
+        *,
+        limit: int = 50,
+        status: Optional[str] = None,
+    ) -> List[Ticket]:
+        """List tickets (default returns empty; remote backends override as needed)."""
+        return []
+
+    def update_status(
+        self,
+        ticket_id: str,
+        status: str,
+        *,
+        agent_id: Optional[str] = None,
+    ) -> Optional[Ticket]:
+        """Agent manually updates ticket status (not supported by default; can be overridden by mock / local_queue)."""
+        raise NotImplementedError(
+            f"{type(self).__name__} does not support manual status update"
+        )
+
+    # --- Bridge interface compatible with old trigger.maybe_handoff ---------
+
+    def get_or_attach(self, user_id: str) -> Optional[Ticket]:
+        """Find existing ticket by user_id (old session_id); returns None if not found.
+
+        This method allows the facade layer to query existing ticket status without breaking the old API.
+        Default implementation iterates list_tickets.
+        """
+        for t in self.list_tickets(limit=200):
+            if t.user_id == user_id:
+                return t
+        return None

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

@@ -0,0 +1,62 @@
+"""queue.py — compatibility facade.
+
+Keeps the `attach_session` public symbol for manifest.extensions (agent.after_start)
+to continue calling as `_hh_queue.attach_session(session_id, info=...)`.
+
+Old version's `get_queue()` / `HandoffQueue` / `HandoffRecord` / `HandoffState`
+are no longer used under the new architecture; kept as deprecated shims for gradual migration of third-party code.
+
+New code should use directly:
+- adapters.factory.get_client()    Get HandoffClient instance
+- core.service.get_default_service() Get HandoffService instance
+"""
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+from .adapters.factory import get_client
+from .core.models import (  # noqa: F401  (backward compatible export)
+    OverallStatus,
+    Ticket,
+    TicketStatus,
+    TicketStatusEnum,
+)
+
+
+def attach_session(session_id: str, info: Any = None) -> None:
+    """For conversation-core.after_start injection point use.
+
+    Under the refactored implementation, "session registration" is done by client on create_ticket as needed;
+    kept here as a no-op entry point to avoid breaking old calls from manifest.extensions.
+    info parameter reserved for compatibility with old signature.
+    """
+    # Trigger client singleton init to surface config errors early during startup
+    _ = get_client()
+    return None
+
+
+# --------------------------------------------------------------------
+# Deprecated shim (for old tests / old external code gradual migration only; new code should not depend)
+# --------------------------------------------------------------------
+def get_queue():
+    warnings.warn(
+        "human_handoff.queue.get_queue() is deprecated; "
+        "use adapters.factory.get_client() or core.service.get_default_service() instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return get_client()
+
+
+# Old symbol aliases (some integrators may directly import)
+HandoffState = TicketStatusEnum
+HandoffRecord = Ticket
+
+
+__all__ = [
+    "HandoffRecord",
+    "HandoffState",
+    "attach_session",
+    "get_queue",
+]

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

@@ -0,0 +1,201 @@
+"""human-handoff FastAPI sub-router.
+
+Mounted on skeleton: app.include_router(router, prefix="/api/v1/handoff")
+
+Refactoring notes:
+- All business logic delegated to core.service.HandoffService
+- Response fields remain fully consistent with Phase 2 (to_legacy_dict), not breaking Web Demo
+- New /admin/* sub-routes for Phase 3 Path A ticket agent dashboard
+"""
+from __future__ import annotations
+
+from typing import List, Optional
+
+from fastapi import APIRouter, HTTPException, Query
+from pydantic import BaseModel, Field
+
+from .core.models import TicketStatusEnum
+from .core.service import get_default_service
+
+
+router = APIRouter()
+
+
+# ---------------------------------------------------------------------------
+# Request body
+# ---------------------------------------------------------------------------
+class RequestBody(BaseModel):
+    session_id: str = Field(..., max_length=64)
+    reason: Optional[str] = Field(default="", max_length=512)
+
+
+class ConnectBody(BaseModel):
+    session_id: str = Field(..., max_length=64)
+    agent_id: str = Field(..., max_length=64)
+
+
+class CancelBody(BaseModel):
+    session_id: str = Field(..., max_length=64)
+
+
+class DetectBody(BaseModel):
+    """Body for handoff intent detection (reuses intent_detector pure function)."""
+
+    text: str = Field(..., max_length=4096)
+
+
+class FeedbackBody(BaseModel):
+    """Body for submitting a post-call satisfaction rating."""
+
+    session_id: str = Field(..., max_length=64)
+    rating: int = Field(..., ge=1, le=5)
+    comment: Optional[str] = Field(default="", max_length=1000)
+
+
+class AdminUpdateBody(BaseModel):
+    status: str = Field(..., max_length=32)
+    agent_id: Optional[str] = Field(default=None, max_length=64)
+
+
+# ---------------------------------------------------------------------------
+# Existing endpoints (fully compatible with Phase 2)
+# ---------------------------------------------------------------------------
+@router.get("/status")
+def overall() -> dict:
+    return {"code": 0, "data": get_default_service().overall_status().to_dict()}
+
+
+@router.get("/{session_id}")
+def session_status(session_id: str) -> dict:
+    ticket = get_default_service().get_by_session(session_id)
+    if ticket is None:
+        raise HTTPException(
+            status_code=404, detail=f"session not tracked: {session_id}"
+        )
+    return {"code": 0, "data": ticket.to_legacy_dict()}
+
+
+@router.post("/request")
+def request_handoff(body: RequestBody) -> dict:
+    ticket = get_default_service().request(
+        body.session_id, reason=body.reason or ""
+    )
+    return {"code": 0, "data": ticket.to_legacy_dict()}
+
+
+@router.post("/connect")
+def connect(body: ConnectBody) -> dict:
+    try:
+        ticket = get_default_service().connect(body.session_id, body.agent_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except RuntimeError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    return {"code": 0, "data": ticket.to_legacy_dict()}
+
+
+@router.post("/cancel")
+def cancel(body: CancelBody) -> dict:
+    try:
+        ticket = get_default_service().cancel(body.session_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    return {"code": 0, "data": ticket.to_legacy_dict()}
+
+
+# ---------------------------------------------------------------------------
+# Intent detection + satisfaction feedback (issue 6 / issue 7)
+# ---------------------------------------------------------------------------
+@router.post("/detect")
+def detect_handoff(body: DetectBody) -> dict:
+    """Pure intent detection: returns whether the text implies a handoff request.
+
+    Reuses core.intent_detector (same logic the backend uses internally), so the
+    frontend fast-path and the backend stay in sync.
+    """
+    from .core.intent_detector import is_handoff_intent
+
+    matched = bool(is_handoff_intent(body.text or ""))
+    return {"code": 0, "data": {"matched": matched, "text": body.text or ""}}
+
+
+@router.post("/feedback")
+def submit_feedback(body: FeedbackBody) -> dict:
+    """Persist a post-call CSAT rating and attach it to the session's ticket (if any)."""
+    result = get_default_service().submit_feedback(
+        body.session_id, body.rating, body.comment or ""
+    )
+    return {"code": 0, "data": result}
+
+
+@router.get("/feedback/{session_id}")
+def get_feedback(session_id: str) -> dict:
+    """Return the stored feedback for a session (404 if not yet rated)."""
+    from .feedback_store import get_feedback as _get
+
+    fb = _get(session_id)
+    if fb is None:
+        raise HTTPException(
+            status_code=404, detail=f"no feedback for session: {session_id}"
+        )
+    return {"code": 0, "data": {"session_id": session_id, "feedback": fb}}
+
+
+# ---------------------------------------------------------------------------
+# New: Ticket agent dashboard endpoints (Phase 3 Path A)
+# Path: /admin/tickets
+# These endpoints output "new version" fields (including ticket_id / subject / priority / transcript),
+# coexisting with the legacy field format of existing /handoff/{session_id}.
+# ---------------------------------------------------------------------------
+@router.get("/admin/tickets")
+def admin_list_tickets(
+    limit: int = Query(default=50, ge=1, le=200),
+    status: Optional[str] = Query(default=None, max_length=32),
+) -> dict:
+    items = get_default_service().list_tickets(limit=limit, status=status)
+    return {
+        "code": 0,
+        "data": {
+            "items": [t.to_dict() for t in items],
+            "count": len(items),
+        },
+    }
+
+
+@router.get("/admin/tickets/{ticket_id}")
+def admin_get_ticket(ticket_id: str) -> dict:
+    status = get_default_service().query_ticket(ticket_id)
+    if status is None:
+        raise HTTPException(status_code=404, detail=f"ticket not found: {ticket_id}")
+    items = [
+        t for t in get_default_service().list_tickets(limit=200)
+        if t.ticket_id == ticket_id
+    ]
+    if not items:
+        raise HTTPException(status_code=404, detail=f"ticket not found: {ticket_id}")
+    return {"code": 0, "data": items[0].to_dict()}
+
+
+@router.post("/admin/tickets/{ticket_id}/status")
+def admin_update_status(ticket_id: str, body: AdminUpdateBody) -> dict:
+    # Validate status value
+    try:
+        TicketStatusEnum(body.status)
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=400,
+            detail=f"invalid status: {body.status}",
+        ) from exc
+
+    try:
+        ticket = get_default_service().update_ticket_status(
+            ticket_id, body.status, agent_id=body.agent_id
+        )
+    except NotImplementedError as exc:
+        raise HTTPException(status_code=405, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    if ticket is None:
+        raise HTTPException(status_code=404, detail=f"ticket not found: {ticket_id}")
+    return {"code": 0, "data": ticket.to_dict()}

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

@@ -0,0 +1,77 @@
+"""Best-effort linkage with session-summary (optional capability).
+
+When a handoff ticket is created, auto-generate a session summary and attach it to the ticket,
+so agents can see customer issue context directly in the ticket details — no need to manually click "generate summary".
+
+Design principles:
+- Soft dependency: silently no-ops when session-summary is not installed; does not affect the handoff main flow.
+- Non-blocking: defaults to heuristic summary (local, zero latency); does not call LLM in the ticket creation chain.
+- Decoupled: dynamically loaded via conversation-core's _capability_loader;
+  human-handoff has no static import dependency on session-summary.
+"""
+from __future__ import annotations
+
+import importlib.util
+import logging
+from pathlib import Path
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+_loader: Optional[Any] = None
+_loader_resolved = False
+
+
+def _get_loader() -> Optional[Any]:
+    """Dynamically load conversation-core's _capability_loader (no relative imports, can load independently)."""
+    global _loader, _loader_resolved
+    if _loader_resolved:
+        return _loader
+    _loader_resolved = True
+    try:
+        # <root>/capabilities/human-handoff/src/summary_link.py → parents[3] = <root>
+        repo_root = Path(__file__).resolve().parents[3]
+        loader_path = (
+            repo_root / "capabilities" / "conversation-core" / "src" / "_capability_loader.py"
+        )
+        if not loader_path.is_file():
+            return None
+        spec = importlib.util.spec_from_file_location("_hh_capability_loader", loader_path)
+        if spec is None or spec.loader is None:
+            return None
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+        _loader = mod
+    except Exception as exc:  # noqa: BLE001
+        logger.info("session-summary link unavailable: %s", exc)
+        _loader = None
+    return _loader
+
+
+def attach_summary_to_ticket(ticket: Any) -> None:
+    """Generate an LLM narrative summary of the session chat and write it into the ticket's
+    Description field (from AI connect → handoff trigger).
+
+    The ticket Description becomes an LLM summary of the conversation, so agents see the
+    context directly without a separate "Session Summary" block. session-summary not
+    installed / any exception → silently skip (does not affect ticket creation main flow).
+    """
+    loader = _get_loader()
+    if loader is None:
+        return
+    try:
+        recorder_mod = loader.try_load_capability("session-summary", "src/recorder.py")
+        summarizer_mod = loader.try_load_capability("session-summary", "src/summarizer.py")
+        if recorder_mod is None or summarizer_mod is None:
+            return
+        session_id = ticket.user_id
+        recorder = recorder_mod.get_recorder()
+        rec = recorder.get(session_id)
+        if rec is None:
+            return  # No transcript recorded for this session (e.g. manually inserted test ticket), skip
+        # LLM-generated one-paragraph summary of the chat → ticket Description.
+        paragraph = summarizer_mod.summarize_paragraph(rec)
+        if paragraph:
+            ticket.description = paragraph
+    except Exception as exc:  # noqa: BLE001
+        logger.info("attach description summary skipped: %s", exc)