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

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

@@ -0,0 +1,355 @@
+"""Real-time connectivity self-check for the 3 keys.
+
+Each key is validated immediately after input; failures get instant feedback without proceeding to the next key.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Tuple
+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) Tencent Cloud API Key: Call 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:
+    """Call STS GetFederationToken to verify SecretId/SecretKey validity."""
+    if not cred.configured:
+        return CheckResult(ok=False, latency_ms=0, error_code="E001", detail="empty credential")
+
+    payload = json.dumps(
+        {
+            "Name": "trtc-voice-agent-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\n"
+        f"host:{_STS_HOST}\n"
+        f"x-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 Application Credentials: Call TRTC OpenAPI DescribeAppStatistics to verify
+#    that SDKAppID + Tencent Cloud API Key combination actually works.
+#    Note: During StartAIConversation, TRTC server also validates SDKSecretKey
+#    against the room ID, so local UserSig generation alone cannot detect SecretKey
+#    misconfiguration. Hence we do a lightweight real OpenAPI call as a fallback
+#    (rate limit 50/s won't trigger throttling).
+#    endpoint switches by trtc.region: intl → trtc.intl.tencentcloudapi.com
+# ---------------------------------------------------------------------------
+_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: TencentCloudCredential | None = None,
+    timeout: float = 5.0,
+) -> CheckResult:
+    """Verify TRTC credentials.
+
+    1. Required: Local UserSig generation (verify SDKAppID + SDKSecretKey self-consistency)
+    2. Recommended: Call TRTC OpenAPI ``DescribeTRTCRealTimeQualityData``
+       to verify SDKAppID really exists under the Tencent Cloud account (depends on ``tencent`` cred)
+       endpoint switches by cred.region (intl / cn)
+    """
+    if not cred.configured:
+        return CheckResult(ok=False, latency_ms=0, error_code="E002", detail="empty credential")
+
+    started = time.perf_counter()
+    # —— Step 1: Local UserSig generation ——
+    try:
+        sig = gen_user_sig(
+            sdk_app_id=cred.sdk_app_id,
+            sdk_secret_key=cred.sdk_secret_key,
+            user_id="credential_check",
+            expire_seconds=60,
+        )
+    except Exception as exc:
+        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",
+        )
+
+    # —— Step 2: Real OpenAPI verification (requires Tencent Cloud API credentials) ——
+    if tencent is None or not tencent.configured:
+        elapsed = int((time.perf_counter() - started) * 1000)
+        return CheckResult(ok=True, latency_ms=elapsed, detail="local-only (no tencent cred)")
+
+    trtc_host = cred.trtc_endpoint
+    trtc_region = cred.trtc_region
+
+    # Use DescribeTRTCRealTimeQualityData for a minimal probe: pass SdkAppId + very short time window
+    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\n"
+        f"host:{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}",
+            )
+        # Distinguish two error types: SdkAppId not under this account vs others
+        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', '')} (region={cred.region})",
+                )
+            # Other business errors (e.g. a sub-capability not enabled) don't affect SdkAppId ownership; treat as pass
+            return CheckResult(
+                ok=True,
+                latency_ms=elapsed,
+                detail=f"sdkappid valid; 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) External LLM: Send a minimal prompt to verify the key is valid.
+# ---------------------------------------------------------------------------
+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,
+) -> Tuple[CheckResult, CheckResult, CheckResult]:
+    return (
+        check_tencent_cloud(tencent),
+        check_trtc(trtc, tencent=tencent),
+        check_llm(llm),
+    )

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

@@ -0,0 +1,76 @@
+"""Log redaction filter (P0 security requirement implemented).
+
+Performs irreversible masking of credential fields in log records before logging,
+based on the keywords declared in manifest.yaml security.log_redaction.patterns.
+"""
+from __future__ import annotations
+
+import logging
+import re
+from typing import Iterable
+
+# Default sensitive field names to match (aligned with manifest.yaml security.log_redaction.patterns)
+_DEFAULT_PATTERNS = (
+    "secret_id",
+    "secret_key",
+    "api_key",
+    "app_key",
+    "token",
+    "usersig",
+    "credential",
+    "authorization",
+)
+
+
+def _build_regex(patterns: Iterable[str]) -> re.Pattern[str]:
+    # Matches three common formats: key=value / "key": "value" / key: value
+    keys = "|".join(re.escape(p) for p in patterns)
+    pattern = (
+        r"(?i)(?P<key>" + keys + r")"
+        r"(?P<sep>\s*[:=]\s*\"?)"
+        r"(?P<val>[A-Za-z0-9_\-\.\+/=]{4,})"
+    )
+    return re.compile(pattern)
+
+
+def _mask(value: str) -> str:
+    if len(value) <= 8:
+        return "***"
+    return f"{value[:2]}***{value[-2:]}"
+
+
+class RedactingFilter(logging.Filter):
+    """Mask sensitive fields in log messages / args."""
+
+    def __init__(self, patterns: Iterable[str] = _DEFAULT_PATTERNS) -> None:
+        super().__init__()
+        self._regex = _build_regex(patterns)
+
+    def filter(self, record: logging.LogRecord) -> bool:  # noqa: A003
+        try:
+            if isinstance(record.msg, str):
+                record.msg = self._regex.sub(
+                    lambda m: f"{m.group('key')}{m.group('sep')}{_mask(m.group('val'))}",
+                    record.msg,
+                )
+            if record.args:
+                record.args = tuple(
+                    self._regex.sub(
+                        lambda m: f"{m.group('key')}{m.group('sep')}{_mask(m.group('val'))}",
+                        str(a),
+                    )
+                    if isinstance(a, str)
+                    else a
+                    for a in record.args
+                )
+        except Exception:  # Redaction failure must not affect the main logging flow
+            pass
+        return True
+
+
+def install_redacting_filter(logger: logging.Logger | None = None) -> None:
+    """Attach the redacting filter to the specified Logger (defaults to root Logger)."""
+    target = logger or logging.getLogger()
+    if any(isinstance(f, RedactingFilter) for f in target.filters):
+        return
+    target.addFilter(RedactingFilter())

package/skills/trtc-ai-service/capabilities/conversation-core/src/modality.py

@@ -0,0 +1,109 @@
+"""I/O modality configuration and degradation strategy (conversation-core built-in).
+
+Four channels (voice input / voice output / text input / text output) are independently configurable.
+When a channel service is unavailable, the system automatically degrades to an available channel
+according to the strategy declared in this module, ensuring session continuity.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+
+class Channel(str, Enum):
+    VOICE_INPUT = "voice_input"
+    TEXT_INPUT = "text_input"
+    VOICE_OUTPUT = "voice_output"
+    TEXT_OUTPUT = "text_output"
+
+
+@dataclass
+class ChannelConfig:
+    enabled: bool = True
+    provider: Optional[str] = None
+    fallback: Optional[Channel] = None
+    timeout_ms: int = 0
+
+
+@dataclass
+class IoModality:
+    voice_input: ChannelConfig = field(
+        default_factory=lambda: ChannelConfig(
+            enabled=True, provider="trtc-asr", fallback=Channel.TEXT_INPUT, timeout_ms=5000
+        )
+    )
+    text_input: ChannelConfig = field(default_factory=lambda: ChannelConfig(enabled=True))
+    voice_output: ChannelConfig = field(
+        default_factory=lambda: ChannelConfig(
+            enabled=True, provider="trtc-tts", fallback=Channel.TEXT_OUTPUT, timeout_ms=3000
+        )
+    )
+    text_output: ChannelConfig = field(default_factory=lambda: ChannelConfig(enabled=True))
+
+    def to_dict(self) -> dict:
+        def _dump(c: ChannelConfig) -> dict:
+            return {
+                "enabled": c.enabled,
+                "provider": c.provider,
+                "fallback": c.fallback.value if c.fallback else None,
+                "timeout_ms": c.timeout_ms,
+            }
+
+        return {
+            Channel.VOICE_INPUT.value: _dump(self.voice_input),
+            Channel.TEXT_INPUT.value: _dump(self.text_input),
+            Channel.VOICE_OUTPUT.value: _dump(self.voice_output),
+            Channel.TEXT_OUTPUT.value: _dump(self.text_output),
+        }
+
+    def resolve_input_channel(self, voice_available: bool) -> Channel:
+        """Return the input channel to use, based on enabled status + service availability."""
+        if self.voice_input.enabled and voice_available:
+            return Channel.VOICE_INPUT
+        if self.voice_input.fallback and self.text_input.enabled:
+            return Channel.TEXT_INPUT
+        if self.text_input.enabled:
+            return Channel.TEXT_INPUT
+        # Edge case: all input channels unavailable -> upper layer enters silent wait
+        raise RuntimeError("no usable input channel")
+
+    def resolve_output_channel(self, voice_available: bool) -> Channel:
+        if self.voice_output.enabled and voice_available:
+            return Channel.VOICE_OUTPUT
+        if self.voice_output.fallback and self.text_output.enabled:
+            return Channel.TEXT_OUTPUT
+        if self.text_output.enabled:
+            return Channel.TEXT_OUTPUT
+        raise RuntimeError("no usable output channel")
+
+
+def from_dict(data: dict) -> IoModality:
+    """Construct IoModality instance from the io_modality section of manifest.yaml."""
+    if not data:
+        return IoModality()
+
+    def _channel(value: Optional[str]) -> Optional[Channel]:
+        if not value:
+            return None
+        return Channel(value)
+
+    def _build(cfg: dict | None, default: ChannelConfig) -> ChannelConfig:
+        if not cfg:
+            return default
+        return ChannelConfig(
+            enabled=cfg.get("enabled", default.enabled),
+            provider=cfg.get("provider", default.provider),
+            fallback=_channel(cfg.get("fallback"))
+            if "fallback" in cfg
+            else default.fallback,
+            timeout_ms=cfg.get("timeout_ms", default.timeout_ms),
+        )
+
+    base = IoModality()
+    return IoModality(
+        voice_input=_build(data.get("voice_input"), base.voice_input),
+        text_input=_build(data.get("text_input"), base.text_input),
+        voice_output=_build(data.get("voice_output"), base.voice_output),
+        text_output=_build(data.get("text_output"), base.text_output),
+    )