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

package/skills/trtc-ai-service/capabilities/session-summary/manifest.yaml

@@ -0,0 +1,165 @@
+# session-summary capability self-describing manifest
+# Type: capability (optional install)
+
+name: "session-summary"
+version: "1.0.0"
+type: "capability"
+description: "Automatic session summarization + structured summary output (turn recording / key fact extraction / LLM secondary summarization)"
+
+dependencies:
+  - name: "conversation-core"
+    version: ">=1.0.0,<2.0.0"
+
+# Optional integration (soft dependency, not hard dependency):
+# When human-handoff is also installed, ticket creation will auto-trigger this capability
+# to generate a summary for that session and attach it to the ticket. Agents can see the
+# customer issue context directly in the dashboard ticket details (no need to manually click "generate summary").
+# The integration is implemented as a best-effort call from human-handoff (capabilities/human-handoff/src/summary_link.py);
+# when this capability is not installed, the call silently skips without affecting the handoff main flow.
+optional_integrations:
+  - capability: "human-handoff"
+    trigger: "ticket.create"
+    behavior: "auto-finalize session summary (heuristic) and embed into ticket payload"
+
+extensions:
+  # Archive as a user turn before text injection
+  - inject_at: "agent.before_push_text"
+    inline_code: |
+      # [session-summary] record user turn
+      from ._capability_loader import try_load_capability
+      _ss_recorder = try_load_capability("session-summary", "src/recorder.py")
+      if _ss_recorder is not None:
+          _ss_recorder.record_user_turn(session_id, text)
+  - inject_at: "agent.after_start"
+    inline_code: |
+      # [session-summary] open session
+      from ._capability_loader import try_load_capability
+      _ss_recorder = try_load_capability("session-summary", "src/recorder.py")
+      if _ss_recorder is not None:
+          _ss_recorder.open_session(session_id)
+  - inject_at: "server.router_extension"
+    inline_code: |
+      # [session-summary] mount sub-router
+      from ._capability_loader import try_load_capability as _try_load_capability
+      _ss_router_mod = _try_load_capability("session-summary", "src/router.py")
+      if _ss_router_mod is not None and hasattr(_ss_router_mod, "router"):
+          app.include_router(
+              _ss_router_mod.router, prefix="/api/v1/summary", tags=["session-summary"]
+          )
+
+config:
+  adapter:
+    description: "Summary write-back target: mock (default, no external deps) | local_json | default_rest"
+    default: "mock"
+    env: "SS_ADAPTER"
+    options:
+      mock: "Log-only + returns mock record_id, suitable for local / Path A demos"
+      local_json: "Append to local JSONL (data/_writeback.jsonl)"
+      default_rest: "POST to real CRM / ticketing system (requires SS_REST_BASE_URL[/SS_REST_TOKEN])"
+  storage_dir:
+    description: "Summary file landing directory (one JSON per session)"
+    default: "capabilities/session-summary/data/"
+  llm_summary:
+    description: "Whether to enable LLM secondary summarization (consumes LLM_API_KEY; set false for offline scenarios)"
+    default: true
+  retention_days:
+    description: "Summary retention days; auto-cleanup after expiry"
+    default: 30
+  redact_patterns:
+    description: "Fields to auto-redact before writing summaries (same standard as skeleton log_redaction)"
+    default:
+      - "secret_id"
+      - "secret_key"
+      - "api_key"
+      - "token"
+
+endpoints:
+  - method: GET
+    path: /api/v1/summary/{session_id}
+    description: Get single session summary (includes turn list and structured summary)
+  - method: POST
+    path: /api/v1/summary/{session_id}/finalize
+    description: Close session and trigger LLM secondary summarization
+  - method: GET
+    path: /api/v1/summary/_list
+    description: List most recent N summaries (_offset / _limit query)
+
+integration:
+  mode: "auto"
+  auto_adapters:
+    - tech_stack: ["express", "koa", "fastify"]
+      adapter: "node-backend"
+    - tech_stack: ["flask", "fastapi", "django"]
+      adapter: "python-backend"
+    - tech_stack: ["react", "vue", "angular"]
+      adapter: "frontend-spa"
+      description: "Append summary viewer panel to SPA"
+  fallback:
+    guided_templates:
+      - "../../auto_adapters/integration_templates/generic-backend.md"
+    manual_api:
+      rest_endpoint: "/api/v1/summary"
+
+security:
+  log_redaction:
+    enabled: true
+    patterns: ["secret_id", "secret_key", "api_key", "token", "credential"]
+  storage:
+    file_permission: "0600"
+
+# ---------------------------------------------------------------------------
+# Business contract (Phase 3 new; follows references/business-contract-spec.md v1.0)
+# Note: Source code for this capability is not refactored in this phase (compromise strategy);
+# only declares the external contract for contract-adapt.py consumption.
+# ---------------------------------------------------------------------------
+business_contract:
+  port_class: "src.adapters.base.SummarySink"
+  default_adapter: "src.adapters.default_rest.DefaultRestSink"
+  mock_adapter: "src.adapters.mock.MockSink"
+  customization_sop: "INTERFACE_ADAPT.md"
+  external_apis:
+    # CRM / Ticketing: write session summary back
+    - name: summary.write_to_crm
+      direction: outbound
+      method: POST
+      path: /sessions/{session_id}/summary
+      description: "After session finalize, write structured summary to user's CRM / ticketing / data platform"
+      request_schema:
+        session_id: string
+        user_id: string
+        topic: string
+        outcome: enum[resolved, transferred, abandoned, follow_up]
+        next_actions: string[]
+        full_transcript: string[]
+        structured_facts: object
+        finalized_at: int
+      response_schema:
+        record_id: string
+        accepted: bool
+      adapter_slots:
+        - request.topic
+        - request.outcome
+        - request.next_actions
+        - request.structured_facts
+        - response.record_id
+      auth:
+        type: bearer
+        location: header
+        name: Authorization
+      timeout_ms: 5000
+
+    # Secondary summarization call (reuses conversation-core LLM interface; declared here only as reference)
+    - name: summary.llm_summarize
+      direction: outbound
+      description: "Reuses conversation-core llm.chat_completions interface;
+                    uses same LLM_API_URL / LLM_API_KEY config; no separate adaptation needed."
+      method: POST
+      path: "(see conversation-core: llm.chat_completions)"
+      request_schema: {}
+      response_schema: {}
+      adapter_slots: []
+
+acceptance:
+  - "Each user/assistant turn persisted as JSONL"
+  - "After calling finalize, produce structured summary (includes topics / next_actions)"
+  - "File permissions set to 0600, sensitive fields auto-redacted"

package/skills/trtc-ai-service/capabilities/session-summary/src/__init__.py

@@ -0,0 +1,2 @@
+"""session-summary capability: session summary + structured abstract."""
+__version__ = "1.0.0"

package/skills/trtc-ai-service/capabilities/session-summary/src/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""session-summary write-back adapter layer."""
+from .base import SummarySink
+from .factory import get_sink
+
+__all__ = ["SummarySink", "get_sink"]

package/skills/trtc-ai-service/capabilities/session-summary/src/adapters/base.py

@@ -0,0 +1,31 @@
+"""session-summary write-back adapter layer.
+
+Consistent "three-tier adapter + factory" paradigm matching knowledge-base / human-handoff:
+    mock          — Default; summary only logged + returns mock record_id, no external system needed,
+                    allows local / Path A demos to immediately see "write-back success".
+    local_json    — Append to local JSONL (data/_writeback.jsonl), can be checked offline.
+    default_rest  — POST to user's real CRM / ticketing system (SS_REST_BASE_URL).
+
+External contract see manifest.business_contract.external_apis[summary.write_to_crm].
+When interface fields don't align, refer to INTERFACE_ADAPT.md for request/response mapping.
+"""
+from __future__ import annotations
+
+import abc
+from typing import Any, Dict
+
+
+class SummarySink(abc.ABC):
+    """Unified abstraction for session summary write-back targets."""
+
+    name: str = "base"
+
+    @abc.abstractmethod
+    def write(self, summary_record: Dict[str, Any]) -> Dict[str, Any]:
+        """Write a finalized summary record to the target system.
+
+        Returns
+        -------
+        dict: {"record_id": str, "accepted": bool, "sink": str}
+        """
+        raise NotImplementedError

package/skills/trtc-ai-service/capabilities/session-summary/src/adapters/default_rest.py

@@ -0,0 +1,67 @@
+"""default_rest write-back sink — POST to user's real CRM / ticketing system.
+
+Environment variables:
+    SS_REST_BASE_URL   Required, e.g. https://crm.example.com/api
+    SS_REST_TOKEN      Optional, Bearer Token
+    SS_REST_TIMEOUT_MS Optional, default 5000
+
+Aligned with manifest.business_contract.external_apis[summary.write_to_crm]:
+    POST {base}/sessions/{session_id}/summary
+Adjust _build_payload in this file or refer to INTERFACE_ADAPT.md when fields don't align.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Dict
+
+from .base import SummarySink
+
+logger = logging.getLogger(__name__)
+
+
+class DefaultRestSink(SummarySink):
+    name = "default_rest"
+
+    def __init__(self) -> None:
+        self._base = (os.getenv("SS_REST_BASE_URL") or "").rstrip("/")
+        self._token = os.getenv("SS_REST_TOKEN") or ""
+        self._timeout = max(int(os.getenv("SS_REST_TIMEOUT_MS", "5000")), 100) / 1000.0
+        if not self._base:
+            raise RuntimeError("SS_REST_BASE_URL not configured for default_rest sink")
+        # Security: forbid plaintext http (except localhost debugging), prevent credentials / summaries over unencrypted channels
+        if not self._base.startswith("https://") and "localhost" not in self._base:
+            raise RuntimeError(f"SS_REST_BASE_URL must use HTTPS: {self._base}")
+
+    def _build_payload(self, rec: Dict[str, Any]) -> Dict[str, Any]:
+        summary = rec.get("summary") or {}
+        return {
+            "session_id": rec.get("session_id"),
+            "topic": (summary.get("topics") or [None])[0],
+            "outcome": summary.get("outcome", "follow_up"),
+            "next_actions": summary.get("next_actions") or [],
+            "full_transcript": [t.get("text", "") for t in rec.get("turns") or []],
+            "structured_facts": summary,
+            "finalized_at": rec.get("closed_at"),
+        }
+
+    def write(self, summary_record: Dict[str, Any]) -> Dict[str, Any]:
+        import requests
+
+        sid = summary_record.get("session_id", "")
+        url = f"{self._base}/sessions/{sid}/summary"
+        headers = {"Content-Type": "application/json"}
+        if self._token:
+            headers["Authorization"] = f"Bearer {self._token}"
+        resp = requests.post(url, json=self._build_payload(summary_record),
+                             headers=headers, timeout=self._timeout)
+        resp.raise_for_status()
+        try:
+            data = resp.json()
+        except ValueError:
+            data = {}
+        return {
+            "record_id": data.get("record_id", ""),
+            "accepted": bool(data.get("accepted", True)),
+            "sink": self.name,
+        }

package/skills/trtc-ai-service/capabilities/session-summary/src/adapters/factory.py

@@ -0,0 +1,51 @@
+"""Write-back sink factory — selects implementation by env SS_ADAPTER (consistent with KB/handoff factory paradigm).
+
+    SS_ADAPTER=mock         Default; no external dependencies
+    SS_ADAPTER=local_json   Write local JSONL
+    SS_ADAPTER=default_rest POST to real CRM (requires SS_REST_BASE_URL)
+
+When any implementation initialization fails (e.g. default_rest missing base_url), safely degrades to mock,
+ensuring the finalize flow is never interrupted due to unavailable write-back targets.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import threading
+from typing import Optional
+
+from .base import SummarySink
+from .mock import MockSink
+
+logger = logging.getLogger(__name__)
+
+_lock = threading.RLock()
+_instance: Optional[SummarySink] = None
+_instance_key: Optional[str] = None
+
+
+def _build(name: str) -> SummarySink:
+    name = (name or "mock").strip().lower()
+    if name == "local_json":
+        from .local_json import LocalJsonSink
+        return LocalJsonSink()
+    if name == "default_rest":
+        from .default_rest import DefaultRestSink
+        return DefaultRestSink()
+    return MockSink()
+
+
+def get_sink() -> SummarySink:
+    """Return the currently configured write-back sink (cached by SS_ADAPTER; rebuilds on env change)."""
+    global _instance, _instance_key
+    key = (os.getenv("SS_ADAPTER", "mock") or "mock").strip().lower()
+    with _lock:
+        if _instance is not None and _instance_key == key:
+            return _instance
+        try:
+            _instance = _build(key)
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("session-summary sink '%s' init failed, fallback to mock: %s", key, exc)
+            _instance = MockSink()
+        _instance_key = key
+        return _instance

package/skills/trtc-ai-service/capabilities/session-summary/src/adapters/local_json.py

@@ -0,0 +1,42 @@
+"""local_json write-back sink — append to local JSONL for offline verification."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import threading
+import time
+from pathlib import Path
+from typing import Any, Dict
+
+from .base import SummarySink
+
+_LOCK = threading.RLock()
+
+
+class LocalJsonSink(SummarySink):
+    name = "local_json"
+
+    def __init__(self) -> None:
+        base = os.getenv(
+            "SS_STORAGE_DIR",
+            str(Path(__file__).resolve().parents[2] / "data"),
+        )
+        self._file = Path(base) / "_writeback.jsonl"
+        self._file.parent.mkdir(parents=True, exist_ok=True)
+
+    def write(self, summary_record: Dict[str, Any]) -> Dict[str, Any]:
+        sid = str(summary_record.get("session_id", ""))
+        record_id = "CRM-LOCAL-" + hashlib.md5(sid.encode("utf-8")).hexdigest()[:10].upper()
+        line = json.dumps(
+            {"record_id": record_id, "written_at": int(time.time()), "record": summary_record},
+            ensure_ascii=False,
+        )
+        with _LOCK:
+            with self._file.open("a", encoding="utf-8") as f:
+                f.write(line + "\n")
+            try:
+                os.chmod(self._file, 0o600)
+            except OSError:
+                pass
+        return {"record_id": record_id, "accepted": True, "sink": self.name}

package/skills/trtc-ai-service/capabilities/session-summary/src/adapters/mock.py

@@ -0,0 +1,22 @@
+"""mock write-back sink — default implementation, no external dependencies, suitable for demos."""
+from __future__ import annotations
+
+import hashlib
+import logging
+from typing import Any, Dict
+
+from .base import SummarySink
+
+logger = logging.getLogger(__name__)
+
+
+class MockSink(SummarySink):
+    name = "mock"
+
+    def write(self, summary_record: Dict[str, Any]) -> Dict[str, Any]:
+        sid = str(summary_record.get("session_id", ""))
+        record_id = "CRM-MOCK-" + hashlib.md5(sid.encode("utf-8")).hexdigest()[:10].upper()
+        topics = (summary_record.get("summary") or {}).get("topics") or []
+        logger.info("[session-summary][mock] write-back session=%s topics=%s -> %s",
+                    sid, topics[:3], record_id)
+        return {"record_id": record_id, "accepted": True, "sink": self.name, "_mock": True}

package/skills/trtc-ai-service/capabilities/session-summary/src/recorder.py

@@ -0,0 +1,210 @@
+"""Session turn recorder.
+
+Persistence strategy:
+- Each session generates ``{session_id}.json`` under storage_dir, permissions 0600.
+- Sensitive fields redacted before writing (same standard as skeleton log_filter).
+- File structure:
+    {
+      "session_id": "...",
+      "opened_at": 1717830000.0,
+      "closed_at": null,
+      "turns": [
+        {"role": "user", "ts": 1717830001.0, "text": "..."},
+        {"role": "assistant", "ts": 1717830002.0, "text": "..."}
+      ],
+      "summary": null  # Populated after finalize
+    }
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+_DEFAULT_STORAGE_DIR = Path(
+    os.getenv(
+        "SS_STORAGE_DIR",
+        str(Path(__file__).resolve().parent.parent / "data"),
+    )
+)
+_RETENTION_DAYS = int(os.getenv("SS_RETENTION_DAYS", "30"))
+
+
+# Default redaction mode (aligned with skeleton log_filter)
+_REDACT_PATTERNS = [
+    re.compile(r"(?i)(secret_id|secret_key|api_key|token|credential|authorization)\s*[:=]\s*([^\s,'\"\\]+)"),
+]
+
+
+def _redact(text: str) -> str:
+    if not text:
+        return text
+    out = text
+    for pat in _REDACT_PATTERNS:
+        out = pat.sub(lambda m: f"{m.group(1)}=***", out)
+    return out
+
+
+@dataclass
+class Turn:
+    role: str
+    text: str
+    ts: float = field(default_factory=time.time)
+
+    def to_dict(self) -> dict:
+        return {"role": self.role, "text": self.text, "ts": self.ts}
+
+
+@dataclass
+class SessionRecord:
+    session_id: str
+    opened_at: float = field(default_factory=time.time)
+    closed_at: Optional[float] = None
+    turns: List[Turn] = field(default_factory=list)
+    summary: Optional[Dict[str, Any]] = None
+
+    def to_dict(self) -> dict:
+        return {
+            "session_id": self.session_id,
+            "opened_at": self.opened_at,
+            "closed_at": self.closed_at,
+            "turns": [t.to_dict() for t in self.turns],
+            "summary": self.summary,
+        }
+
+
+class Recorder:
+    def __init__(self, storage_dir: Optional[Path] = None) -> None:
+        self._lock = threading.RLock()
+        self._dir = Path(storage_dir or _DEFAULT_STORAGE_DIR)
+        self._dir.mkdir(parents=True, exist_ok=True)
+        self._cache: Dict[str, SessionRecord] = {}
+        self._cleanup_old_files()
+
+    @property
+    def storage_dir(self) -> Path:
+        return self._dir
+
+    def open(self, session_id: str) -> SessionRecord:
+        with self._lock:
+            rec = self._cache.get(session_id)
+            if rec is not None:
+                return rec
+            path = self._path(session_id)
+            if path.exists():
+                rec = self._load(path)
+            else:
+                rec = SessionRecord(session_id=session_id)
+            self._cache[session_id] = rec
+            self._persist(rec)
+            return rec
+
+    def add_turn(self, session_id: str, role: str, text: str) -> None:
+        if not text or not text.strip():
+            return
+        if role not in ("user", "assistant", "system", "tool"):
+            return
+        with self._lock:
+            rec = self._cache.get(session_id) or self.open(session_id)
+            rec.turns.append(Turn(role=role, text=_redact(text)[:4096]))
+            self._persist(rec)
+
+    def get(self, session_id: str) -> Optional[SessionRecord]:
+        with self._lock:
+            rec = self._cache.get(session_id)
+            if rec is not None:
+                return rec
+            path = self._path(session_id)
+            if path.exists():
+                rec = self._load(path)
+                self._cache[session_id] = rec
+                return rec
+            return None
+
+    def list_recent(self, offset: int = 0, limit: int = 20) -> List[Dict[str, Any]]:
+        files = sorted(
+            self._dir.glob("*.json"),
+            key=lambda p: p.stat().st_mtime,
+            reverse=True,
+        )[offset : offset + limit]
+        out: List[Dict[str, Any]] = []
+        for p in files:
+            try:
+                out.append(json.loads(p.read_text(encoding="utf-8")))
+            except (OSError, json.JSONDecodeError):
+                continue
+        return out
+
+    def finalize(self, session_id: str, summary: Dict[str, Any]) -> SessionRecord:
+        with self._lock:
+            rec = self.get(session_id)
+            if rec is None:
+                raise ValueError(f"session not found: {session_id}")
+            rec.closed_at = time.time()
+            rec.summary = summary
+            self._persist(rec)
+            return rec
+
+    # ------------------------------------------------------------------
+    def _path(self, session_id: str) -> Path:
+        safe = re.sub(r"[^A-Za-z0-9_\-]", "_", session_id)[:64]
+        return self._dir / f"{safe}.json"
+
+    def _load(self, path: Path) -> SessionRecord:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        rec = SessionRecord(
+            session_id=data.get("session_id", path.stem),
+            opened_at=float(data.get("opened_at", time.time())),
+            closed_at=data.get("closed_at"),
+            summary=data.get("summary"),
+        )
+        for t in data.get("turns") or []:
+            rec.turns.append(Turn(role=t.get("role", "user"), text=t.get("text", ""), ts=float(t.get("ts", 0))))
+        return rec
+
+    def _persist(self, rec: SessionRecord) -> None:
+        path = self._path(rec.session_id)
+        tmp = path.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps(rec.to_dict(), ensure_ascii=False, indent=2), encoding="utf-8")
+        os.replace(tmp, path)
+        try:
+            os.chmod(path, 0o600)
+        except OSError:
+            pass
+
+    def _cleanup_old_files(self) -> None:
+        cutoff = time.time() - _RETENTION_DAYS * 86400
+        for p in self._dir.glob("*.json"):
+            try:
+                if p.stat().st_mtime < cutoff:
+                    p.unlink()
+            except OSError:
+                continue
+
+
+# ---------------------------------------------------------------------------
+# Global singleton + manifest.extensions injection functions
+# ---------------------------------------------------------------------------
+_global_recorder = Recorder()
+
+
+def get_recorder() -> Recorder:
+    return _global_recorder
+
+
+def open_session(session_id: str) -> None:
+    _global_recorder.open(session_id)
+
+
+def record_user_turn(session_id: str, text: str) -> None:
+    _global_recorder.add_turn(session_id, "user", text)
+
+
+def record_assistant_turn(session_id: str, text: str) -> None:
+    _global_recorder.add_turn(session_id, "assistant", text)