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

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

@@ -0,0 +1,93 @@
+"""session-summary FastAPI sub-router."""
+from __future__ import annotations
+
+import os
+from typing import List, Optional
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from .recorder import get_recorder
+from .summarizer import summarize
+
+router = APIRouter()
+
+
+# ---------------------------------------------------------------------------
+# Request bodies
+# ---------------------------------------------------------------------------
+class TurnItem(BaseModel):
+    role: str = Field(..., max_length=16)
+    text: str = Field("", max_length=4096)
+
+
+class RecordBody(BaseModel):
+    """Batch-upload conversation turns so a summary can be attached to a ticket
+    before the frontend requests a handoff."""
+
+    turns: List[TurnItem] = Field(default_factory=list)
+
+
+@router.get("/_list")
+def list_recent(_offset: int = 0, _limit: int = 20) -> dict:
+    if _limit < 1 or _limit > 200:
+        raise HTTPException(status_code=400, detail="_limit out of range [1,200]")
+    return {"code": 0, "data": get_recorder().list_recent(offset=_offset, limit=_limit)}
+
+
+@router.get("/{session_id}")
+def get_summary(session_id: str) -> dict:
+    rec = get_recorder().get(session_id)
+    if rec is None:
+        raise HTTPException(status_code=404, detail=f"session not found: {session_id}")
+    return {"code": 0, "data": rec.to_dict()}
+
+
+@router.post("/{session_id}/record")
+def record_turns(session_id: str, body: RecordBody) -> dict:
+    """Batch-record conversation turns for a session.
+
+    Called by the frontend right before requesting a human handoff, so that
+    attach_summary_to_ticket can produce a context summary from the transcript.
+    Safe to call repeatedly; idempotent per turn text.
+    """
+    recorder = get_recorder()
+    recorder.open(session_id)
+    accepted = 0
+    for t in body.turns:
+        role = (t.role or "").strip().lower()
+        if role not in ("user", "assistant", "system", "tool"):
+            continue
+        if not t.text:
+            continue
+        recorder.add_turn(session_id, role, t.text)
+        accepted += 1
+    rec = recorder.get(session_id)
+    return {
+        "code": 0,
+        "data": {
+            "session_id": session_id,
+            "accepted": accepted,
+            "total_turns": len(rec.turns) if rec else 0,
+        },
+    }
+
+
+@router.post("/{session_id}/finalize")
+def finalize(session_id: str) -> dict:
+    rec = get_recorder().get(session_id)
+    if rec is None:
+        raise HTTPException(status_code=404, detail=f"session not found: {session_id}")
+    prefer_llm = os.getenv("SS_LLM_SUMMARY", "true").lower() == "true"
+    summary = summarize(rec, prefer_llm=prefer_llm)
+    rec = get_recorder().finalize(session_id, summary)
+    # Write-back: select mock / local_json / default_rest by SS_ADAPTER (safe degradation to mock on failure)
+    writeback = None
+    try:
+        from .adapters.factory import get_sink
+        writeback = get_sink().write(rec.to_dict())
+    except Exception as exc:  # noqa: BLE001
+        writeback = {"accepted": False, "error": str(exc)}
+    data = rec.to_dict()
+    data["writeback"] = writeback
+    return {"code": 0, "data": data}

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

@@ -0,0 +1,163 @@
+"""Structured summary generator.
+
+Strategy:
+- Offline heuristic (default): extract questions / to-do keywords / key nouns, done locally with zero dependencies.
+- LLM secondary summarization (optional, requires LLM_API_KEY): serialize turns and call OpenAI-compatible protocol.
+
+Output JSON:
+    {
+      "topics":      ["..."],
+      "user_intents": ["..."],
+      "next_actions": ["..."],
+      "highlights":  ["..."],
+      "engine":      "heuristic" | "llm",
+      "model":       "gpt-4o-mini" | null
+    }
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+from typing import Any, Dict, List, Optional
+
+from .recorder import SessionRecord
+
+logger = logging.getLogger(__name__)
+
+
+_QUESTION_RE = re.compile(r"[^?？]+[?？]")
+_ACTION_RE = re.compile(r"(I want|please help|need to|please)([^。.!?？!\n]+)", re.IGNORECASE)
+_NOUN_RE = re.compile(r"[A-Z][A-Za-z0-9_]{2,}|[\u4e00-\u9fff]{2,}")
+_STOPWORDS = {"the", "a", "an", "because", "so", "when", "can", "need"}
+
+
+def _heuristic(record: SessionRecord) -> Dict[str, Any]:
+    topics: List[str] = []
+    intents: List[str] = []
+    actions: List[str] = []
+    highlights: List[str] = []
+    seen_topic, seen_intent, seen_action = set(), set(), set()
+    for t in record.turns:
+        if t.role != "user":
+            continue
+        for q in _QUESTION_RE.findall(t.text):
+            q = q.strip()
+            if q and q not in seen_intent:
+                intents.append(q[:120])
+                seen_intent.add(q)
+        for m in _ACTION_RE.finditer(t.text):
+            phrase = (m.group(1) + m.group(2)).strip()[:120]
+            if phrase and phrase not in seen_action:
+                actions.append(phrase)
+                seen_action.add(phrase)
+        for noun in _NOUN_RE.findall(t.text):
+            if noun in _STOPWORDS or len(noun) > 24:
+                continue
+            if noun not in seen_topic and len(topics) < 8:
+                topics.append(noun)
+                seen_topic.add(noun)
+    if record.turns:
+        highlights.append(f"{len(record.turns)} turns recorded")
+    return {
+        "topics": topics,
+        "user_intents": intents[:5],
+        "next_actions": actions[:5],
+        "highlights": highlights,
+        "engine": "heuristic",
+        "model": None,
+    }
+
+
+def _llm_summarize(record: SessionRecord) -> Dict[str, Any]:
+    api_key = os.getenv("LLM_API_KEY")
+    api_url = os.getenv("LLM_API_URL", "https://api.openai.com/v1/chat/completions")
+    model = os.getenv("LLM_MODEL", "gpt-4o-mini")
+    if not api_key:
+        raise RuntimeError("LLM_API_KEY not configured")
+    import requests
+
+    transcript = "\n".join(f"[{t.role}] {t.text}" for t in record.turns[-50:])
+    prompt = (
+        "You are a session summary assistant. Summarize the following conversation as JSON with keys: topics, user_intents,"
+        " next_actions, highlights. Each value is a string array (max 5 items)."
+        "Do not include any sensitive information (API Key/Token etc.).\n"
+        f"Conversation content:\n{transcript}\n"
+        "Output JSON only."
+    )
+    resp = requests.post(
+        api_url,
+        headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
+        json={
+            "model": model,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": 0.2,
+            "response_format": {"type": "json_object"},
+        },
+        timeout=20,
+    )
+    resp.raise_for_status()
+    data = resp.json()
+    content = data["choices"][0]["message"]["content"]
+    try:
+        parsed = json.loads(content)
+    except json.JSONDecodeError:
+        parsed = {"highlights": [content[:512]]}
+    parsed.setdefault("topics", [])
+    parsed.setdefault("user_intents", [])
+    parsed.setdefault("next_actions", [])
+    parsed.setdefault("highlights", [])
+    parsed["engine"] = "llm"
+    parsed["model"] = model
+    return parsed
+
+
+def summarize(record: SessionRecord, *, prefer_llm: bool = True) -> Dict[str, Any]:
+    if prefer_llm and os.getenv("LLM_API_KEY"):
+        try:
+            return _llm_summarize(record)
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("LLM summarize failed, fallback to heuristic: %s", exc)
+    return _heuristic(record)
+
+
+def summarize_paragraph(record: SessionRecord) -> Optional[str]:
+    """Generate a one-paragraph narrative summary of the session via LLM.
+
+    Used by the handoff flow to fill a ticket's Description with an LLM summary of the
+    chat from AI connect → handoff trigger. Returns None if LLM is not configured or the
+    session has no turns (caller then leaves the description unchanged).
+    """
+    api_key = os.getenv("LLM_API_KEY")
+    if not api_key:
+        return None
+    if not record.turns:
+        return None
+    import requests
+
+    api_url = os.getenv("LLM_API_URL", "https://api.openai.com/v1/chat/completions")
+    model = os.getenv("LLM_MODEL", "gpt-4o-mini")
+    transcript = "\n".join(f"[{t.role}] {t.text}" for t in record.turns[-50:])
+    prompt = (
+        "You are a customer-service ticket summarizer. Read the conversation below between "
+        "a customer and an AI assistant, then write ONE concise paragraph (2-4 sentences) "
+        "summarizing what the customer asked about and what was discussed, from the moment "
+        "the AI connected up to the point the customer requested a human agent. Do not invent "
+        "facts not present in the conversation. Do not include any sensitive data (API key / "
+        "token etc.). Output only the paragraph, with no preamble.\n"
+        f"Conversation:\n{transcript}\n"
+    )
+    resp = requests.post(
+        api_url,
+        headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
+        json={
+            "model": model,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": 0.3,
+        },
+        timeout=20,
+    )
+    resp.raise_for_status()
+    data = resp.json()
+    return (data["choices"][0]["message"]["content"] or "").strip() or None

package/skills/trtc-ai-service/capabilities/tool-calling/INTERFACE_ADAPT.md

@@ -0,0 +1,158 @@
+# tool-calling Interface Adaptation SOP
+
+> Alpha/beta dual-track tool calling. This capability's source code has not been refactored to ports/adapters/core in this release (Phase 1 compromise),
+> but the manifest already declares the full `business_contract.alpha_track` / `beta_track` / `arbitration` contracts.
+
+---
+
+## 1. Dual-Track Contract Overview
+
+### 1.1 Alpha Track (local functions)
+
+```yaml
+alpha_track:
+  registration_schema:
+    name: string                # e.g.: query_order
+    description: string         # Tool description for LLM consumption
+    parameters: object          # JSON Schema
+    handler: callable           # Sync or async Python function
+```
+
+Alpha track is suitable for: low latency, tight business coupling, tools that are inconvenient to expose as HTTP services.
+
+### 1.2 Beta Track (remote APIs)
+
+```yaml
+beta_track:
+  api_schema:
+    method: GET | POST | PUT | DELETE | PATCH
+    path: string
+    request_schema: object
+    response_schema: object
+    auth: bearer | api_key | none
+```
+
+Beta track is suitable for: cross-service calls, tools that need to reuse existing API gateways.
+
+### 1.3 Arbitration Rules
+
+```yaml
+arbitration:
+  default_priority: alpha               # Alpha first
+  fallback_on_failure: true             # Alpha failure auto-degrades to beta
+  timeout_ms: 3000                       # Single-track call timeout
+  merge_strategy: first_success         # Take first success only
+```
+
+---
+
+## 2. Three Scenarios When User Interfaces Don't Match
+
+### 2.1 Scenario 1: User's alpha-track function signature differs
+
+**Symptom**: The user already has local functions (e.g. `def get_order(order_id, user_id) -> dict`),
+but the skeleton expects parameters named `id` / `customer_id`.
+
+**Solution**: Write a thin wrapper registration function — no need to modify the skeleton.
+
+```python
+# Inside user project
+from capabilities.tool_calling.src.dispatcher import register_tool
+
+def get_order(order_id, user_id):
+    """User's existing function."""
+    return {"order_id": order_id, "status": "shipped"}
+
+# Adaptation layer: parameter remapping
+register_tool(
+    name="query_order",
+    description="Query order status",
+    parameters={
+        "type": "object",
+        "properties": {
+            "id": {"type": "string"},
+            "customer_id": {"type": "string"},
+        },
+        "required": ["id", "customer_id"],
+    },
+    handler=lambda id, customer_id: get_order(id, customer_id),  # Field remapping
+)
+```
+
+### 2.2 Scenario 2: User's beta-track remote API uses a different protocol
+
+**Symptom**: The remote business API is not OpenAI Tool Calling-style JSON-RPC,
+but a user's own REST endpoint (e.g. `POST /api/v1/orders/query`).
+
+**Solution**: Declare the full API schema when registering in `tools.yaml`.
+
+```yaml
+# capabilities/tool-calling/data/tools.yaml
+tools:
+  - name: query_order
+    description: Query order status
+    alpha: null                          # No local implementation
+    beta:
+      base_url: https://api.example.com  # Must be HTTPS
+      method: POST
+      path: /api/v1/orders/query
+      headers:
+        X-Api-Key: ${USER_KB_TOKEN}      # Read from environment variable
+      request_template:
+        body:
+          order_no: "{{ id }}"           # Template render: map tool input id to order_no
+          uid: "{{ customer_id }}"
+      response_path: "$.data.order"      # Response field extraction (JSONPath)
+```
+
+> This release's advanced template rendering in tools.yaml is **not fully implemented**;
+> for complex mapping needs, it's recommended to rewrite as an alpha-track local function + internal `requests` call.
+
+### 2.3 Scenario 3: User wants to disable beta track (local functions only)
+
+```bash
+export TC_PRIORITY=alpha
+export TC_DISABLE_BETA=1
+```
+
+The skeleton only uses alpha track; beta failures will not trigger. Vice versa (`TC_DISABLE_ALPHA=1`).
+
+---
+
+## 3. Arbitration Priority Override
+
+The manifest defaults to `priority=alpha`; can be overridden via environment variables:
+
+```bash
+export TC_PRIORITY=beta              # Beta first (when alpha implementation is not yet stable)
+export TC_PRIORITY=manifest_order    # Follow order of alpha/beta fields in tools.yaml
+```
+
+---
+
+## 4. Phase 4 Plan: Full ports/adapters Refactor
+
+The following will be introduced in the future:
+
+```
+capabilities/tool-calling/src/
+├── ports/
+│   ├── local_tool.py            # ABC: LocalTool
+│   └── remote_tool.py           # ABC: RemoteToolClient
+└── adapters/
+    ├── alpha_python.py          # Alpha default implementation (current dispatcher behavior)
+    ├── beta_rest.py             # Beta default implementation
+    └── user_custom.py           # User integration wizard generator
+```
+
+This document will be supplemented with automated adaptation workflows at that time.
+
+---
+
+## 5. Security Checklist
+
+- [ ] Beta track `base_url` must use https:// (localhost excepted)
+- [ ] Reject private network access (9.* / 10.* / 172.16-31.* / 192.168.*)
+- [ ] `Authorization` / `X-Api-Key` only from environment variables
+- [ ] Alpha track handlers must not expose `eval` / `exec` / arbitrary command execution
+- [ ] Tool result re-injection must have prompt injection protection (manifest.security.injection_protection)

package/skills/trtc-ai-service/capabilities/tool-calling/README.md

@@ -0,0 +1,50 @@
+# tool-calling · Alpha/Beta Dual-Track Tool Calling
+
+> Provides local function (alpha) + remote API (beta) tool calling on top of conversation-core,
+> with alpha-first by default and automatic degradation to beta on alpha failure (P1 arbitration rules).
+
+## Install
+
+```bash
+python scripts/add-capability.py tool-calling
+```
+
+## Configuration
+
+| Env Variable | Default | Description |
+|:---|:---|:---|
+| `TC_REGISTRY_FILE` | `capabilities/tool-calling/data/tools.yaml` | Tool declaration file |
+
+Tool declaration format in `data/tools.yaml`, supports hot-reload (`POST /api/v1/tools/reload`).
+
+## REST API
+
+| Method | Path | Purpose |
+|:---|:---|:---|
+| GET  | `/api/v1/tools/list`   | List all tools |
+| POST | `/api/v1/tools/invoke` | Explicit invocation `{name, params, priority?}` |
+| POST | `/api/v1/tools/reload` | Reload registry |
+
+## In-Conversation Trigger
+
+Push the following text to `agent/control` to trigger:
+
+```
+/tool get_order {"order_id": "A1234"}
+```
+
+The dispatcher replaces the original text with a `[tool_result ...]...[/tool_result]` block and injects it into the LLM.
+
+## Arbitration Rules
+
+- `priority=alpha` (default): alpha first, then beta
+- `priority=beta`: beta first, then alpha
+- `priority=manifest_order`: follow declaration order
+
+Automatic degradation to the next available track on any track failure; returns `ok=false` and `fallback_chain` when all fail.
+
+## Security
+
+- Beta track enforces HTTPS (except `http://localhost*`);
+- Tool name ≤ 64, trigger text ≤ 4096;
+- Tool parameters auto-redacted in logs (manifest declares `log_redaction.patterns`).

package/skills/trtc-ai-service/capabilities/tool-calling/data/tools.yaml

@@ -0,0 +1,58 @@
+# tool-calling default tool registry — generic AI customer service toolset (industry-neutral)
+#
+# Dual-track notes:
+#   alpha (α track) = local function / mock implementation: works out of the box, no real backend needed, easy local demo
+#   beta  (β track) = remote HTTPS API: point the endpoint at your real business system
+# Default priority=alpha: prefer local mock; change priority or pass priority=beta in a single invoke to force real API.
+# When interfaces don't align, refer to INTERFACE_ADAPT.md for request/response field mapping.
+
+priority: alpha    # alpha | beta | manifest_order
+
+tools:
+  - name: query_order_status
+    description: "Query document/order/ticket status (input order_id) — high-frequency customer service action"
+    alpha:
+      module: "capabilities.tool_calling.examples.local_tools"
+      function: "query_order_status"
+      timeout_ms: 600
+    beta:
+      endpoint: "https://api.example.com/v1/orders/status"
+      method: "POST"
+      timeout_ms: 5000
+      headers: {}
+
+  - name: get_business_info
+    description: "Query business info: hours/address/contact (topic=hours|address|contact|all)"
+    alpha:
+      module: "capabilities.tool_calling.examples.local_tools"
+      function: "get_business_info"
+      timeout_ms: 400
+    beta:
+      endpoint: "https://api.example.com/v1/business/info"
+      method: "GET"
+      timeout_ms: 5000
+      headers: {}
+
+  - name: book_appointment
+    description: "Create appointment/booking: restaurant reservations, service appointments, etc. (date, time_slot, party_size)"
+    alpha:
+      module: "capabilities.tool_calling.examples.local_tools"
+      function: "book_appointment"
+      timeout_ms: 800
+    beta:
+      endpoint: "https://api.example.com/v1/appointments"
+      method: "POST"
+      timeout_ms: 5000
+      headers: {}
+
+  - name: submit_feedback
+    description: "Submit satisfaction rating/feedback (rating 1-5, comment) — common end-of-session action"
+    alpha:
+      module: "capabilities.tool_calling.examples.local_tools"
+      function: "submit_feedback"
+      timeout_ms: 400
+    beta:
+      endpoint: "https://api.example.com/v1/feedback"
+      method: "POST"
+      timeout_ms: 5000
+      headers: {}

package/skills/trtc-ai-service/capabilities/tool-calling/examples/__init__.py

@@ -0,0 +1 @@
+"""tool-calling built-in example tools namespace."""

package/skills/trtc-ai-service/capabilities/tool-calling/examples/local_tools.py

@@ -0,0 +1,101 @@
+"""tool-calling built-in "Generic AI Customer Service Tool Set" (alpha-track default = local mock).
+
+Design principles (aligned with SKILL §6 point 2):
+- Industry-neutral: not tied to specific verticals; covers common actions across most customer service scenarios
+  (check document status / check business info / make appointment / submit feedback).
+- Works out of the box: each tool has a directly runnable alpha-track mock implementation;
+  users on Path A or local demos can see the capability in effect immediately, even without a real backend API.
+- Smoothly replaceable: each tool also declares a beta-track (remote HTTPS) placeholder in data/tools.yaml;
+  connecting to a real system only requires pointing the beta endpoint to your own API (or adapting per INTERFACE_ADAPT.md).
+
+Return value must be JSON-serializable; mock data uniformly carries "_mock": true marker,
+making it easy for frontend / logs to distinguish "demo data" from "real business data".
+"""
+from __future__ import annotations
+
+import hashlib
+import time
+from typing import Any, Dict
+
+
+def _stable_pick(seed: str, choices):
+    """Stably select a value based on seed (same input always returns the same result, making demos reproducible)."""
+    h = int(hashlib.md5(seed.encode("utf-8")).hexdigest(), 16)
+    return choices[h % len(choices)]
+
+
+def query_order_status(order_id: str = "", **_: Any) -> Dict[str, Any]:
+    """Query document / order / ticket status (generic customer service action).
+
+    Parameters:
+        order_id: Document number (order number / ticket number / appointment number fine).
+    """
+    if not order_id:
+        return {"_mock": True, "error": "order_id is required"}
+    status = _stable_pick(order_id, ["processing", "confirmed", "in_progress", "completed", "cancelled"])
+    return {
+        "_mock": True,
+        "order_id": order_id,
+        "status": status,
+        "updated_at": int(time.time()),
+        "note": "Demo data from built-in mock tool; point the β endpoint to your real system to use live data.",
+    }
+
+
+def get_business_info(topic: str = "hours", **_: Any) -> Dict[str, Any]:
+    """Query business info (hours / address / contact etc.), common high-frequency customer service question.
+
+    Parameters:
+        topic: hours | address | contact | all
+    """
+    info = {
+        "hours": "Mon-Sun 10:00-22:00 (last entry 21:00)",
+        "address": "No.1 Demo Street, Example District",
+        "contact": "+86-000-0000-0000 / support@example.com",
+    }
+    topic = (topic or "hours").lower()
+    data = info if topic == "all" else {topic: info.get(topic, info["hours"])}
+    return {"_mock": True, "topic": topic, **data,
+            "note": "Demo data from built-in mock tool; replace with your real business profile."}
+
+
+def book_appointment(date: str = "", time_slot: str = "", party_size: int = 2, **_: Any) -> Dict[str, Any]:
+    """Create reservation / booking (restaurant reservation, service appointment, callback booking etc. generic actions).
+
+    Parameters:
+        date: Date, e.g. 2026-06-12
+        time_slot: Time slot, e.g. 18:30
+        party_size: Party size / quantity
+    """
+    if not date or not time_slot:
+        return {"_mock": True, "error": "date and time_slot are required"}
+    confirm = "BK" + hashlib.md5(f"{date}{time_slot}{party_size}".encode()).hexdigest()[:8].upper()
+    return {
+        "_mock": True,
+        "confirmation_id": confirm,
+        "date": date,
+        "time_slot": time_slot,
+        "party_size": int(party_size) if str(party_size).isdigit() else party_size,
+        "status": "confirmed",
+        "note": "Demo booking created by built-in mock tool; wire the β endpoint to your reservation system.",
+    }
+
+
+def submit_feedback(rating: int = 5, comment: str = "", **_: Any) -> Dict[str, Any]:
+    """Submit satisfaction / feedback (common end-of-session action).
+
+    Parameters:
+        rating: 1-5 rating
+        comment: Text feedback (optional)
+    """
+    try:
+        rating = max(1, min(5, int(rating)))
+    except (TypeError, ValueError):
+        rating = 5
+    return {
+        "_mock": True,
+        "received": True,
+        "rating": rating,
+        "comment": (comment or "")[:512],
+        "note": "Demo acknowledgement from built-in mock tool.",
+    }