@tencent-rtc/trtc-agent-skills 0.1.7 → 0.1.8

package/skills/trtc-ai-realtime-interpreter/capabilities/conversation-core/src/agent.py

@@ -0,0 +1,153 @@
+# -*- coding: utf-8 -*-
+"""会话编排（骨架层）：拉起一路 Conversational AI 并管理其生命周期。
+
+设计原则：
+  - 骨架只知道「给一个 room_id + target_user_id + 启动参数，起停一路会话」这件事，
+    不知道「会议」「参会人」「房主」「翻译语言对」这些概念——这些留给上层业务能力包
+    （realtime-translation / meeting-ops）通过参数传入或组合调用。
+  - room_id 由调用方传入（可能来自我们自己签发，也可能来自调用方已有的会议/直播系统），
+    骨架不强制自己生成房间。
+  - 每次 start() 都会生成一个独立的 agent 身份（bot UserId + UserSig），互不冲突，
+    支持同一房间起多路会话（meeting-ops 扇出场景）。
+"""
+from __future__ import annotations
+
+import logging
+import secrets
+import time
+from dataclasses import dataclass, field
+from threading import RLock
+from typing import Any, Dict, Optional
+
+from credentials import Credentials
+from trtc_client import AgentLifecycleConfig, TrtcConversationClient
+from usersig import gen_user_sig
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SessionInfo:
+    session_id: str
+    room_id: str
+    room_id_type: int
+    target_user_id: str
+    agent_user_id: str
+    agent_user_sig: str
+    task_id: Optional[str] = None
+    request_id: Optional[str] = None
+    started_at: float = field(default_factory=time.time)
+
+
+class ConversationAgent:
+    """单路会话管理器（骨架层，无业务逻辑）。"""
+
+    def __init__(self, credentials: Credentials) -> None:
+        if not credentials.fully_configured:
+            raise ValueError(
+                f"credentials missing: {credentials.missing()}; "
+                "请先在 .env 里配好三把钥匙（TRTC / 腾讯云 / LLM）"
+            )
+        self._cred = credentials
+        self._client = TrtcConversationClient(
+            tencent=credentials.tencent_cloud, trtc=credentials.trtc, llm=credentials.llm,
+        )
+        self._sessions: Dict[str, SessionInfo] = {}
+        self._lock = RLock()
+
+    # ------------------------------------------------------------------
+    # 身份签发：任意 user_id 换一个 UserSig（供旁听客户端等通用场景使用）
+    # ------------------------------------------------------------------
+    def issue_user_sig(self, user_id: str) -> str:
+        return gen_user_sig(
+            sdk_app_id=self._cred.trtc.sdk_app_id,
+            sdk_secret_key=self._cred.trtc.sdk_secret_key,
+            user_id=user_id,
+        )
+
+    @property
+    def sdk_app_id(self) -> int:
+        return self._cred.trtc.sdk_app_id
+
+    # ------------------------------------------------------------------
+    # 起一路会话：room_id 由调用方给定（可能是我们签发，也可能是调用方已有房间）
+    # ------------------------------------------------------------------
+    def start(
+        self,
+        room_id: str,
+        target_user_id: str,
+        config: Optional[AgentLifecycleConfig] = None,
+        room_id_type: int = 0,
+        agent_user_id: Optional[str] = None,
+    ) -> SessionInfo:
+        agent_uid = (agent_user_id or f"ai_{secrets.token_hex(6)}")[:32]
+        agent_sig = self.issue_user_sig(agent_uid)
+        sid = secrets.token_urlsafe(12)
+
+        result = self._client.start(
+            room_id=room_id,
+            agent_user_id=agent_uid,
+            agent_user_sig=agent_sig,
+            target_user_id=target_user_id,
+            config=config,
+            room_id_type=room_id_type,
+        )
+        info = SessionInfo(
+            session_id=sid,
+            room_id=str(room_id),
+            room_id_type=room_id_type,
+            target_user_id=target_user_id,
+            agent_user_id=agent_uid,
+            agent_user_sig=agent_sig,
+            task_id=result.get("task_id"),
+            request_id=result.get("request_id"),
+        )
+        with self._lock:
+            self._sessions[sid] = info
+        logger.info("session started: session=%s room=%s target=%s task=%s", sid, room_id, target_user_id, info.task_id)
+        return info
+
+    def stop(self, session_id: str) -> None:
+        info = self._require_session(session_id)
+        if info.task_id:
+            self._client.stop(info.task_id)
+        with self._lock:
+            self._sessions.pop(session_id, None)
+        logger.info("session stopped: session=%s task=%s", session_id, info.task_id)
+
+    def control(self, session_id: str, text: str, interrupt: bool = True) -> Dict[str, Any]:
+        info = self._require_session(session_id)
+        if not info.task_id:
+            raise RuntimeError("session has no active task")
+        if not text or not text.strip():
+            raise ValueError("text cannot be empty")
+        return self._client.control(task_id=info.task_id, command="ServerPushText", text=text, interrupt=interrupt)
+
+    def get_session(self, session_id: str) -> Optional[SessionInfo]:
+        with self._lock:
+            return self._sessions.get(session_id)
+
+    def list_sessions(self) -> Dict[str, Any]:
+        with self._lock:
+            return {
+                "sessions": [
+                    {
+                        "session_id": s.session_id,
+                        "room_id": s.room_id,
+                        "target_user_id": s.target_user_id,
+                        "agent_user_id": s.agent_user_id,
+                        "task_id": s.task_id,
+                        "started_at": s.started_at,
+                    }
+                    for s in self._sessions.values()
+                ]
+            }
+
+    def _require_session(self, session_id: str) -> SessionInfo:
+        if not session_id:
+            raise ValueError("session_id is required")
+        with self._lock:
+            info = self._sessions.get(session_id)
+        if not info:
+            raise ValueError(f"session not found: {session_id}")
+        return info

package/skills/trtc-ai-realtime-interpreter/capabilities/conversation-core/src/credentials.py

@@ -0,0 +1,112 @@
+# -*- coding: utf-8 -*-
+"""三把钥匙（TRTC / 腾讯云 API / LLM）的读取与封装。
+
+密钥只从环境变量读取（Secrets 规范：env-only），绝不出现在代码或日志里。
+本文件不依赖包内相对导入，调用方需自行把本目录加入 sys.path 后 `import credentials`。
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TencentCloudCredential:
+    """钥匙 1：腾讯云 API 密钥（用于给 TRTC 控制面接口签名）。"""
+
+    secret_id: str
+    secret_key: str
+    region: str = "ap-guangzhou"
+
+    @property
+    def configured(self) -> bool:
+        return bool(self.secret_id and self.secret_key)
+
+
+@dataclass(frozen=True)
+class TrtcCredential:
+    """钥匙 2：TRTC 应用凭证（用于签发 UserSig + 调用 Conversational AI 控制面）。
+
+    region:
+      - "intl" -> 国际站 console.trtc.io，endpoint=trtc.intl.tencentcloudapi.com
+    """
+
+    sdk_app_id: int
+    sdk_secret_key: str
+    region: str = "intl"
+
+    @property
+    def configured(self) -> bool:
+        return bool(self.sdk_app_id and self.sdk_secret_key)
+
+    @property
+    def trtc_endpoint(self) -> str:
+        return "trtc.tencentcloudapi.com" if self.region == "cn" else "trtc.intl.tencentcloudapi.com"
+
+    @property
+    def trtc_region(self) -> str:
+        return "ap-guangzhou" if self.region == "cn" else "ap-singapore"
+
+
+@dataclass(frozen=True)
+class LlmCredential:
+    """钥匙 3：LLM API Key（OpenAI 兼容协议）。"""
+
+    api_key: str
+    api_url: str = "https://api.openai.com/v1/chat/completions"
+    model: str = "gpt-4o-mini"
+    llm_type: str = "openai"
+
+    @property
+    def configured(self) -> bool:
+        return bool(self.api_key and self.api_url and self.model)
+
+
+@dataclass(frozen=True)
+class Credentials:
+    tencent_cloud: TencentCloudCredential
+    trtc: TrtcCredential
+    llm: LlmCredential
+
+    @property
+    def fully_configured(self) -> bool:
+        return self.tencent_cloud.configured and self.trtc.configured and self.llm.configured
+
+    def missing(self) -> list:
+        miss = []
+        if not self.tencent_cloud.configured:
+            miss.append("tencent_cloud")
+        if not self.trtc.configured:
+            miss.append("trtc")
+        if not self.llm.configured:
+            miss.append("llm")
+        return miss
+
+
+def _int_env(key: str, default: int = 0) -> int:
+    raw = os.getenv(key, "")
+    try:
+        return int(raw)
+    except (TypeError, ValueError):
+        return default
+
+
+def load_from_env() -> Credentials:
+    return Credentials(
+        tencent_cloud=TencentCloudCredential(
+            secret_id=os.getenv("TENCENT_CLOUD_SECRET_ID", ""),
+            secret_key=os.getenv("TENCENT_CLOUD_SECRET_KEY", ""),
+            region=os.getenv("TENCENT_CLOUD_REGION", "ap-guangzhou"),
+        ),
+        trtc=TrtcCredential(
+            sdk_app_id=_int_env("TRTC_SDK_APP_ID", 0),
+            sdk_secret_key=os.getenv("TRTC_SDK_SECRET_KEY", ""),
+            region=os.getenv("TRTC_REGION", "cn"),
+        ),
+        llm=LlmCredential(
+            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"),
+            llm_type=os.getenv("LLM_TYPE", "openai"),
+        ),
+    )

package/skills/trtc-ai-realtime-interpreter/capabilities/conversation-core/src/health.py

@@ -0,0 +1,218 @@
+# -*- coding: utf-8 -*-
+"""三把钥匙的实时连通性自检。"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Optional
+from urllib.parse import urlparse
+
+import requests
+
+from credentials import LlmCredential, TencentCloudCredential, TrtcCredential
+from usersig import gen_user_sig
+
+
+@dataclass
+class CheckResult:
+    ok: bool
+    latency_ms: int
+    error_code: str = ""
+    detail: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "status": "ok" if self.ok else "failed",
+            "latency_ms": self.latency_ms,
+            "error_code": self.error_code,
+            "detail": self.detail,
+        }
+
+
+# ---------------------------------------------------------------------------
+# 1) 腾讯云 API 密钥：调用 STS GetFederationToken
+# ---------------------------------------------------------------------------
+_STS_HOST = "sts.tencentcloudapi.com"
+_STS_SERVICE = "sts"
+_STS_VERSION = "2018-08-13"
+_STS_ACTION = "GetFederationToken"
+
+
+def _sign_tc3(secret_key: str, date: str, service: str, string_to_sign: str) -> str:
+    k_date = hmac.new(("TC3" + secret_key).encode("utf-8"), date.encode("utf-8"), hashlib.sha256).digest()
+    k_service = hmac.new(k_date, service.encode("utf-8"), hashlib.sha256).digest()
+    k_signing = hmac.new(k_service, b"tc3_request", hashlib.sha256).digest()
+    return hmac.new(k_signing, string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
+
+
+def check_tencent_cloud(cred: TencentCloudCredential, timeout: float = 5.0) -> CheckResult:
+    if not cred.configured:
+        return CheckResult(ok=False, latency_ms=0, error_code="E001", detail="empty credential")
+
+    payload = json.dumps(
+        {
+            "Name": "trtc-ai-realtime-interpreter-credential-check",
+            "Policy": json.dumps(
+                {"version": "2.0", "statement": [{"effect": "deny", "action": ["*"], "resource": ["*"]}]}
+            ),
+            "DurationSeconds": 1800,
+        },
+        separators=(",", ":"),
+    )
+    timestamp = int(time.time())
+    date = datetime.fromtimestamp(timestamp, tz=timezone.utc).strftime("%Y-%m-%d")
+    canonical_headers = (
+        f"content-type:application/json; charset=utf-8\nhost:{_STS_HOST}\nx-tc-action:{_STS_ACTION.lower()}\n"
+    )
+    signed_headers = "content-type;host;x-tc-action"
+    hashed_payload = hashlib.sha256(payload.encode("utf-8")).hexdigest()
+    canonical_request = f"POST\n/\n\n{canonical_headers}\n{signed_headers}\n{hashed_payload}"
+    credential_scope = f"{date}/{_STS_SERVICE}/tc3_request"
+    hashed_canonical = hashlib.sha256(canonical_request.encode("utf-8")).hexdigest()
+    string_to_sign = f"TC3-HMAC-SHA256\n{timestamp}\n{credential_scope}\n{hashed_canonical}"
+    signature = _sign_tc3(cred.secret_key, date, _STS_SERVICE, string_to_sign)
+    authorization = (
+        f"TC3-HMAC-SHA256 Credential={cred.secret_id}/{credential_scope}, "
+        f"SignedHeaders={signed_headers}, Signature={signature}"
+    )
+    headers = {
+        "Authorization": authorization,
+        "Content-Type": "application/json; charset=utf-8",
+        "Host": _STS_HOST,
+        "X-TC-Action": _STS_ACTION,
+        "X-TC-Timestamp": str(timestamp),
+        "X-TC-Version": _STS_VERSION,
+        "X-TC-Region": cred.region,
+    }
+    started = time.perf_counter()
+    try:
+        resp = requests.post(f"https://{_STS_HOST}", headers=headers, data=payload.encode("utf-8"), timeout=timeout)
+        elapsed = int((time.perf_counter() - started) * 1000)
+        body = resp.json() if resp.content else {}
+        err = body.get("Response", {}).get("Error")
+        if resp.status_code == 200 and not err:
+            return CheckResult(ok=True, latency_ms=elapsed)
+        if err and err.get("Code", "").startswith("AuthFailure"):
+            return CheckResult(ok=False, latency_ms=elapsed, error_code="E001", detail=err.get("Message", "AuthFailure"))
+        return CheckResult(
+            ok=False, latency_ms=elapsed, error_code="E001", detail=(err or {}).get("Message") or f"HTTP {resp.status_code}"
+        )
+    except requests.Timeout:
+        return CheckResult(ok=False, latency_ms=int(timeout * 1000), error_code="E004", detail="timeout")
+    except requests.RequestException as exc:
+        return CheckResult(ok=False, latency_ms=0, error_code="E004", detail=str(exc))
+
+
+# ---------------------------------------------------------------------------
+# 2) TRTC 应用凭证：本地 UserSig 自洽 + 可选 OpenAPI 探测
+# ---------------------------------------------------------------------------
+_TRTC_SERVICE = "trtc"
+_TRTC_VERSION = "2019-07-22"
+
+
+def _trtc_sign_tc3(secret_key: str, date: str, string_to_sign: str) -> str:
+    k_date = hmac.new(("TC3" + secret_key).encode("utf-8"), date.encode("utf-8"), hashlib.sha256).digest()
+    k_service = hmac.new(k_date, _TRTC_SERVICE.encode("utf-8"), hashlib.sha256).digest()
+    k_signing = hmac.new(k_service, b"tc3_request", hashlib.sha256).digest()
+    return hmac.new(k_signing, string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
+
+
+def check_trtc(cred: TrtcCredential, tencent: Optional[TencentCloudCredential] = None, timeout: float = 5.0) -> CheckResult:
+    if not cred.configured:
+        return CheckResult(ok=False, latency_ms=0, error_code="E002", detail="empty credential")
+
+    started = time.perf_counter()
+    try:
+        sig = gen_user_sig(cred.sdk_app_id, cred.sdk_secret_key, "credential_check", expire_seconds=60)
+    except Exception as exc:  # noqa: BLE001
+        return CheckResult(ok=False, latency_ms=0, error_code="E002", detail=str(exc))
+    if not sig or len(sig) < 32:
+        return CheckResult(
+            ok=False, latency_ms=int((time.perf_counter() - started) * 1000), error_code="E002", detail="invalid usersig length"
+        )
+
+    if tencent is None or not tencent.configured:
+        return CheckResult(ok=True, latency_ms=int((time.perf_counter() - started) * 1000), detail=f"local-only (no tencent cred); region={cred.region}")
+
+    trtc_host = cred.trtc_endpoint
+    trtc_region = cred.trtc_region
+    now_ts = int(time.time())
+    payload = json.dumps({"SdkAppId": cred.sdk_app_id, "StartTime": now_ts - 60, "EndTime": now_ts}, separators=(",", ":"))
+    timestamp = now_ts
+    date = datetime.fromtimestamp(timestamp, tz=timezone.utc).strftime("%Y-%m-%d")
+    canonical_headers = (
+        f"content-type:application/json; charset=utf-8\nhost:{trtc_host}\n"
+        f"x-tc-action:describetrtcrealtimequalitydata\n"
+    )
+    signed_headers = "content-type;host;x-tc-action"
+    hashed_payload = hashlib.sha256(payload.encode("utf-8")).hexdigest()
+    canonical_request = f"POST\n/\n\n{canonical_headers}\n{signed_headers}\n{hashed_payload}"
+    credential_scope = f"{date}/{_TRTC_SERVICE}/tc3_request"
+    hashed_canonical = hashlib.sha256(canonical_request.encode("utf-8")).hexdigest()
+    string_to_sign = f"TC3-HMAC-SHA256\n{timestamp}\n{credential_scope}\n{hashed_canonical}"
+    signature = _trtc_sign_tc3(tencent.secret_key, date, string_to_sign)
+    authorization = (
+        f"TC3-HMAC-SHA256 Credential={tencent.secret_id}/{credential_scope}, "
+        f"SignedHeaders={signed_headers}, Signature={signature}"
+    )
+    headers = {
+        "Authorization": authorization,
+        "Content-Type": "application/json; charset=utf-8",
+        "Host": trtc_host,
+        "X-TC-Action": "DescribeTRTCRealTimeQualityData",
+        "X-TC-Timestamp": str(timestamp),
+        "X-TC-Version": _TRTC_VERSION,
+        "X-TC-Region": trtc_region,
+    }
+    try:
+        resp = requests.post(f"https://{trtc_host}", headers=headers, data=payload.encode("utf-8"), timeout=timeout)
+        elapsed = int((time.perf_counter() - started) * 1000)
+        body = resp.json() if resp.content else {}
+        err = body.get("Response", {}).get("Error")
+        if resp.status_code == 200 and not err:
+            return CheckResult(ok=True, latency_ms=elapsed, detail=f"region={cred.region}, endpoint={trtc_host}")
+        if err:
+            code = err.get("Code", "")
+            if "SdkAppId" in code or "AuthFailure" in code or "ResourceNotFound" in code:
+                return CheckResult(ok=False, latency_ms=elapsed, error_code="E002", detail=f"{code}: {err.get('Message', '')}")
+            return CheckResult(ok=True, latency_ms=elapsed, detail=f"sdkappid valid (region={cred.region}, endpoint={trtc_host}); api warning: {code}")
+        return CheckResult(ok=False, latency_ms=elapsed, error_code="E002", detail=f"HTTP {resp.status_code}")
+    except requests.Timeout:
+        return CheckResult(ok=False, latency_ms=int(timeout * 1000), error_code="E004", detail="trtc api timeout")
+    except requests.RequestException as exc:
+        return CheckResult(ok=False, latency_ms=0, error_code="E004", detail=str(exc))
+
+
+# ---------------------------------------------------------------------------
+# 3) LLM Key：发一个最小 prompt 验证有效性
+# ---------------------------------------------------------------------------
+def check_llm(cred: LlmCredential, timeout: float = 10.0) -> CheckResult:
+    if not cred.configured:
+        return CheckResult(ok=False, latency_ms=0, error_code="E003", detail="empty credential")
+    parsed = urlparse(cred.api_url)
+    if parsed.scheme not in ("http", "https"):
+        return CheckResult(ok=False, latency_ms=0, error_code="E003", detail="invalid api_url scheme")
+
+    headers = {"Authorization": f"Bearer {cred.api_key}", "Content-Type": "application/json"}
+    body = {"model": cred.model, "messages": [{"role": "user", "content": "ping"}], "max_tokens": 1, "temperature": 0, "stream": False}
+    started = time.perf_counter()
+    try:
+        resp = requests.post(cred.api_url, headers=headers, json=body, timeout=timeout)
+        elapsed = int((time.perf_counter() - started) * 1000)
+        if resp.status_code == 200:
+            return CheckResult(ok=True, latency_ms=elapsed)
+        if resp.status_code in (401, 403):
+            return CheckResult(ok=False, latency_ms=elapsed, error_code="E003", detail=f"unauthorized: {resp.status_code}")
+        return CheckResult(ok=False, latency_ms=elapsed, error_code="E003", detail=f"HTTP {resp.status_code}: {resp.text[:200]}")
+    except requests.Timeout:
+        return CheckResult(ok=False, latency_ms=int(timeout * 1000), error_code="E004", detail="timeout")
+    except requests.RequestException as exc:
+        return CheckResult(ok=False, latency_ms=0, error_code="E004", detail=str(exc))
+
+
+def check_all(tencent: TencentCloudCredential, trtc: TrtcCredential, llm: LlmCredential):
+    return (check_tencent_cloud(tencent), check_trtc(trtc, tencent=tencent), check_llm(llm))

package/skills/trtc-ai-realtime-interpreter/capabilities/conversation-core/src/log_filter.py

@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+"""日志脱敏过滤器：防止密钥/UserSig 意外落进日志文件（Secrets 规范）。"""
+from __future__ import annotations
+
+import logging
+import re
+
+_PATTERNS = [
+    re.compile(r"(secret[_-]?key\s*[=:]\s*)([^\s,&\"']+)", re.IGNORECASE),
+    re.compile(r"(secret[_-]?id\s*[=:]\s*)([^\s,&\"']+)", re.IGNORECASE),
+    re.compile(r"(api[_-]?key\s*[=:]\s*)([^\s,&\"']+)", re.IGNORECASE),
+    re.compile(r"(usersig\s*[=:]\s*)([^\s,&\"']+)", re.IGNORECASE),
+    re.compile(r"(authorization\s*[=:]\s*)([^\s,&\"']+)", re.IGNORECASE),
+]
+
+
+def _redact(msg: str) -> str:
+    for pat in _PATTERNS:
+        msg = pat.sub(lambda m: m.group(1) + "***REDACTED***", msg)
+    return msg
+
+
+class RedactingFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:  # noqa: A003
+        try:
+            record.msg = _redact(str(record.msg))
+        except Exception:  # noqa: BLE001
+            pass
+        return True
+
+
+def install_redacting_filter(logger: logging.Logger) -> None:
+    logger.addFilter(RedactingFilter())