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

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

@@ -0,0 +1,90 @@
+"""TLS-SIG-API-v2 UserSig generator (pure Python, no third-party dependencies).
+
+TRTC room authentication uses SDKAppID + SDKSecretKey to sign the UserId via HMAC-SHA256,
+then compresses with zlib + base64url encodes to produce the UserSig. This implementation
+matches the official ``TLSSigAPIv2`` behavior, enabling usage in a minimal skeleton without
+additional SDKs.
+
+Reference: https://cloud.tencent.com/document/product/647/17275
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import time
+import zlib
+
+
+def _base64_encode(data: bytes) -> str:
+    s = base64.b64encode(data).decode("utf-8")
+    # TRTC custom base64url: + → *, / → -, = → _
+    return s.replace("+", "*").replace("/", "-").replace("=", "_")
+
+
+def _hmac_sha256(
+    sdk_app_id: int,
+    user_id: str,
+    secret_key: str,
+    current_ts: int,
+    expire: int,
+    base64_userbuf: str | None = None,
+) -> str:
+    raw_to_sign = (
+        f"TLS.identifier:{user_id}\n"
+        f"TLS.sdkappid:{sdk_app_id}\n"
+        f"TLS.time:{current_ts}\n"
+        f"TLS.expire:{expire}\n"
+    )
+    if base64_userbuf is not None:
+        raw_to_sign += f"TLS.userbuf:{base64_userbuf}\n"
+    digest = hmac.new(
+        secret_key.encode("utf-8"),
+        raw_to_sign.encode("utf-8"),
+        hashlib.sha256,
+    ).digest()
+    return base64.b64encode(digest).decode("utf-8")
+
+
+def gen_user_sig(
+    sdk_app_id: int,
+    sdk_secret_key: str,
+    user_id: str,
+    expire_seconds: int = 86400,
+) -> str:
+    """Generate a UserSig.
+
+    Args:
+        sdk_app_id: TRTC SDKAppID (integer).
+        sdk_secret_key: TRTC SDKSecretKey.
+        user_id: User identifier within the room; must remain stable.
+        expire_seconds: Validity duration in seconds, default 24 hours.
+
+    Returns:
+        A UserSig string ready for use with the TRTC Web SDK for room entry.
+    """
+    if not sdk_app_id or not sdk_secret_key:
+        raise ValueError("sdk_app_id and sdk_secret_key are required")
+    if not user_id:
+        raise ValueError("user_id is required")
+
+    current_ts = int(time.time())
+    sig = _hmac_sha256(
+        sdk_app_id=sdk_app_id,
+        user_id=user_id,
+        secret_key=sdk_secret_key,
+        current_ts=current_ts,
+        expire=expire_seconds,
+    )
+
+    payload = {
+        "TLS.ver": "2.0",
+        "TLS.identifier": str(user_id),
+        "TLS.sdkappid": int(sdk_app_id),
+        "TLS.expire": int(expire_seconds),
+        "TLS.time": int(current_ts),
+        "TLS.sig": sig,
+    }
+    compressed = zlib.compress(json.dumps(payload).encode("utf-8"))
+    return _base64_encode(compressed)

package/skills/trtc-ai-service/capabilities/conversation-core/tests/test_skeleton.py

@@ -0,0 +1,216 @@
+"""Skeleton core pipeline unit tests.
+
+Verification targets:
+  - 3-key credential encapsulation loads correctly from environment variables
+  - I/O modality channel selection and degradation strategy work correctly
+  - Log redaction filter masks common sensitive fields
+  - UserSig generator produces non-empty, reasonably-sized signatures for valid input
+  - Skeleton source code contains no hardcoded business logic (FAQ / industry prompts etc.)
+"""
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+_HERE = Path(__file__).resolve().parent
+_CORE = _HERE.parent
+sys.path.insert(0, str(_CORE))
+
+from src.credentials import load_from_env  # noqa: E402
+from src.log_filter import RedactingFilter  # noqa: E402
+from src.modality import Channel, IoModality, from_dict  # noqa: E402
+from src.usersig import gen_user_sig  # noqa: E402
+
+
+# ---------------------------------------------------------------------------
+# credentials
+# ---------------------------------------------------------------------------
+def test_credentials_from_env(monkeypatch):
+    monkeypatch.setenv("TENCENT_CLOUD_SECRET_ID", "AKID_xxx")
+    monkeypatch.setenv("TENCENT_CLOUD_SECRET_KEY", "secret_xxx")
+    monkeypatch.setenv("TRTC_SDK_APP_ID", "1400000000")
+    monkeypatch.setenv("TRTC_SDK_SECRET_KEY", "trtc_secret")
+    monkeypatch.setenv("LLM_API_KEY", "sk-xxx")
+
+    cred = load_from_env()
+    assert cred.fully_configured is True
+    assert cred.tencent_cloud.secret_id == "AKID_xxx"
+    assert cred.trtc.sdk_app_id == 1400000000
+    assert cred.llm.model == "gpt-4o-mini"  # default
+    assert cred.missing() == []
+
+
+def test_credentials_missing(monkeypatch):
+    for k in (
+        "TENCENT_CLOUD_SECRET_ID", "TENCENT_CLOUD_SECRET_KEY",
+        "TRTC_SDK_APP_ID", "TRTC_SDK_SECRET_KEY", "LLM_API_KEY",
+    ):
+        monkeypatch.delenv(k, raising=False)
+    cred = load_from_env()
+    assert cred.fully_configured is False
+    assert set(cred.missing()) == {"tencent_cloud", "trtc", "llm"}
+
+
+# ---------------------------------------------------------------------------
+# modality
+# ---------------------------------------------------------------------------
+def test_modality_default_resolve():
+    mod = IoModality()
+    assert mod.resolve_input_channel(voice_available=True) == Channel.VOICE_INPUT
+    assert mod.resolve_output_channel(voice_available=True) == Channel.VOICE_OUTPUT
+
+
+def test_modality_fallback_to_text_when_voice_unavailable():
+    mod = IoModality()
+    assert mod.resolve_input_channel(voice_available=False) == Channel.TEXT_INPUT
+    assert mod.resolve_output_channel(voice_available=False) == Channel.TEXT_OUTPUT
+
+
+def test_modality_text_only_scenario():
+    mod = from_dict(
+        {
+            "voice_input": {"enabled": False},
+            "voice_output": {"enabled": False},
+            "text_input": {"enabled": True},
+            "text_output": {"enabled": True},
+        }
+    )
+    assert mod.resolve_input_channel(voice_available=True) == Channel.TEXT_INPUT
+    assert mod.resolve_output_channel(voice_available=True) == Channel.TEXT_OUTPUT
+
+
+def test_modality_all_disabled_raises():
+    mod = from_dict(
+        {
+            "voice_input": {"enabled": False},
+            "voice_output": {"enabled": False},
+            "text_input": {"enabled": False},
+            "text_output": {"enabled": False},
+        }
+    )
+    with pytest.raises(RuntimeError):
+        mod.resolve_input_channel(voice_available=False)
+
+
+# ---------------------------------------------------------------------------
+# log redaction (P0 security)
+# ---------------------------------------------------------------------------
+def test_log_redacting_filter():
+    rec = logging.LogRecord(
+        name="t", level=logging.INFO, pathname="", lineno=1,
+        msg="boot with secret_key=ABCDEFGHIJKLMNOP and api_key: sk-1234567890abcdef",
+        args=(), exc_info=None,
+    )
+    flt = RedactingFilter()
+    assert flt.filter(rec) is True
+    masked = rec.getMessage()
+    assert "ABCDEFGHIJKLMNOP" not in masked
+    assert "sk-1234567890abcdef" not in masked
+    assert "secret_key" in masked  # Field name preserved
+    assert "api_key" in masked
+
+
+# ---------------------------------------------------------------------------
+# usersig
+# ---------------------------------------------------------------------------
+def test_usersig_basic():
+    sig = gen_user_sig(
+        sdk_app_id=1400000000,
+        sdk_secret_key="dummy_secret_for_unit_test",
+        user_id="user_123",
+        expire_seconds=60,
+    )
+    assert isinstance(sig, str) and len(sig) > 32
+    # TRTC custom base64url charset (+ → *, / → -, = → _)
+    allowed = set(
+        "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789*-_"
+    )
+    assert all(c in allowed for c in sig)
+
+
+def test_usersig_input_validation():
+    with pytest.raises(ValueError):
+        gen_user_sig(0, "k", "user")
+    with pytest.raises(ValueError):
+        gen_user_sig(1400000000, "", "user")
+    with pytest.raises(ValueError):
+        gen_user_sig(1400000000, "k", "")
+
+
+# ---------------------------------------------------------------------------
+# Skeleton purity: source code should not contain industry keywords
+# (e-commerce / orders / restaurant / reservation etc.).
+# Check target: after stripping comments and docstrings, actual code must not contain hardcoded business logic.
+# ---------------------------------------------------------------------------
+import ast
+import io
+import tokenize
+
+
+def _strip_comments_and_docstrings(source: str) -> str:
+    """Return code after stripping comments and docstrings."""
+    # 1) Remove # comments
+    out_tokens = []
+    g = tokenize.generate_tokens(io.StringIO(source).readline)
+    for tok_type, tok_val, *_ in g:
+        if tok_type == tokenize.COMMENT:
+            continue
+        out_tokens.append((tok_type, tok_val))
+    no_comments = tokenize.untokenize(out_tokens)
+    # 2) Remove docstrings: rewrite AST without Expr(Constant(str)) nodes
+    try:
+        tree = ast.parse(no_comments)
+    except SyntaxError:
+        return no_comments
+
+    class _DocstringRemover(ast.NodeTransformer):
+        def _strip(self, node):
+            if (
+                node.body
+                and isinstance(node.body[0], ast.Expr)
+                and isinstance(node.body[0].value, ast.Constant)
+                and isinstance(node.body[0].value.value, str)
+            ):
+                node.body = node.body[1:] or [ast.Pass()]
+            return node
+
+        def visit_Module(self, node):
+            self.generic_visit(node)
+            return self._strip(node)
+
+        def visit_FunctionDef(self, node):
+            self.generic_visit(node)
+            return self._strip(node)
+
+        def visit_AsyncFunctionDef(self, node):
+            self.generic_visit(node)
+            return self._strip(node)
+
+        def visit_ClassDef(self, node):
+            self.generic_visit(node)
+            return self._strip(node)
+
+    cleaned = _DocstringRemover().visit(tree)
+    ast.fix_missing_locations(cleaned)
+    return ast.unparse(cleaned)
+
+
+def test_skeleton_purity_no_business_keywords():
+    forbidden = []
+    forbidden = [
+        
+        "FAQ",
+    ]
+    src_dir = _CORE / "src"
+    offenders = []
+    for py in src_dir.glob("*.py"):
+        raw = py.read_text(encoding="utf-8")
+        code_only = _strip_comments_and_docstrings(raw)
+        for kw in forbidden:
+            if kw in code_only:
+                offenders.append((py.name, kw))
+    assert offenders == [], f"Skeleton contains business keywords: {offenders}"

package/skills/trtc-ai-service/capabilities/conversation-core/web-demo/README.md

@@ -0,0 +1,48 @@
+# Web Demo · 3-Step Quick Start Guide
+
+> This directory is the minimal runnable verification page for conversation-core, **containing no business logic**.
+
+## Three Steps to Start
+
+```bash
+# 1. Install dependencies (first time)
+pip install -r capabilities/conversation-core/requirements.txt
+
+# 2. Configure three keys (interactive guide)
+python scripts/setup-credentials.py
+
+# 3. Launch the Demo
+bash start.sh
+# or: cd capabilities/conversation-core && python -m src.server
+```
+
+Open your browser and visit <http://localhost:3000>.
+
+## Verification Checklist
+
+After opening the page, check in the following order:
+
+1. The three indicator LEDs in the top status bar go from `gray` → `yellow (pending)` → `green`.
+2. Once all three LEDs are green, the "Start Conversation" button becomes clickable.
+3. Clicking it automatically calls `/api/v1/get_config` and `/api/v1/agent/start`; the console will output `task_id`.
+4. Send any text in the text input box; you can see the ServerPushText injection record in the TRTC console.
+
+## Troubleshooting
+
+Click "Recheck" in the top-right corner to force a connectivity refresh. On failure, the browser console will output structured diagnostics, e.g.:
+
+```json
+{
+  "tencent_cloud": { "status": "ok", "latency_ms": 120 },
+  "trtc":          { "status": "ok", "latency_ms": 12 },
+  "llm":           { "status": "failed", "error_code": "E003", "detail": "unauthorized: 401" }
+}
+```
+
+Cross-reference the `error_code` with the `INTEGRATION.md` troubleshooting dictionary to locate the issue.
+
+## Not in Scope for This Demo
+
+- Real audio capture and TRTC RTC room entry (handled by Phase 2 `frontend-spa` adapter or the integrator)
+- Business knowledge base / FAQ / tool calling (overlaid by standalone capability packages)
+- Digital human rendering, handoff, session summaries, etc. (overlaid by standalone capability packages)