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

package/skills/trtc-ai-oral-coach/auto_adapters/python/README.md

@@ -0,0 +1,49 @@
+# Python Adapter — Oral Coach Client
+
+> Auto-generated by ai-oral-coach auto_adapters/python.
+> This adapter generates `coach_client.py` — a headless Python client for backend aggregation.
+
+## What's generated
+
+| File | Contents |
+|:---|:---|
+| `coach_client.py` | `CoachClient` class — full API wrapper (config / agent control / coach capabilities / KB) |
+
+## Usage
+
+```python
+from coach_client import CoachClient
+
+# Initialize
+coach = CoachClient(base_url="http://localhost:8000")
+
+# Health check
+coach.health()  # → { status: "ok", tencent_cloud: ok, trtc: ok, llm: ok }
+
+# Get TRTC credentials (your frontend uses these to enter room)
+config = coach.get_config("student_001")
+# → { sdkAppId, roomId, userId, userSig, agentUserId, ... }
+
+# Start agent (after frontend enters room)
+result = coach.start_agent(
+    room_id=config["roomId"],
+    scenario="travel",
+    level="intermediate",
+    style="friend",
+    agent_config=config.get("agentConfig"),
+)
+
+# Coach capabilities (call from your backend as needed)
+correction = coach.correct("I go to park yesterday")
+suggestions = coach.suggest("What did you do last weekend?")
+report = coach.generate_report(transcript=[...], duration_sec=120)
+
+# Graceful end
+coach.farewell(lang="en")
+```
+
+## Dependencies
+
+```bash
+pip install requests
+```

package/skills/trtc-ai-oral-coach/auto_adapters/python/coach_client.py.tpl

@@ -0,0 +1,185 @@
+# coach_client.py
+# Auto-generated by ai-oral-coach auto_adapters/python
+# Python client wrapper — full oral coach API coverage for backend aggregation.
+#
+# Usage:
+#   from coach_client import CoachClient
+#   coach = CoachClient(base_url="http://localhost:8000")
+#   health = coach.health()
+#   config = coach.get_config("student_001")
+#   result = coach.start_agent(room_id="...", scenario="travel", level="intermediate", style="friend", agent_config=config["agent_config"])
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional
+
+import requests
+
+
+DEFAULT_BASE_URL = "${SKELETON_BASE_URL}"
+API_PREFIX = "${API_PREFIX}"
+
+
+class CoachClient:
+    """Headless client for the AI Oral Coach backend.
+
+    All coach capabilities (correct / suggest / report / scene) are exposed as
+    methods. TRTC room entry is handled by your own TRTC SDK — this client
+    provides the credentials and control-plane API.
+    """
+
+    def __init__(self, base_url: str = DEFAULT_BASE_URL, api_key: Optional[str] = None):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.session = requests.Session()
+        if api_key:
+            self.session.headers["Authorization"] = f"Bearer {api_key}"
+        self.session.headers["Content-Type"] = "application/json"
+        self.task_id: Optional[str] = None
+
+    # ─── HTTP helpers ──────────────────────────────────────────────
+
+    def _post(self, path: str, body: dict = None) -> dict:
+        url = f"{self.base_url}{API_PREFIX}{path}"
+        resp = self.session.post(url, json=body or {}, timeout=(5, 30))
+        resp.raise_for_status()
+        return resp.json()
+
+    def _get(self, path: str) -> dict:
+        url = f"{self.base_url}{API_PREFIX}{path}"
+        resp = self.session.get(url, timeout=5)
+        resp.raise_for_status()
+        return resp.json()
+
+    # ─── Core ──────────────────────────────────────────────────────
+
+    def health(self) -> dict:
+        """Health check — returns { status, tencent_cloud, trtc, llm }."""
+        return self._get("/health")
+
+    def get_config(self, user_id: str) -> dict:
+        """Get UserSig + room credentials. Call before entering TRTC room."""
+        return self._post("/config", {"userid": user_id})
+
+    # ─── Agent Control ─────────────────────────────────────────────
+
+    def start_agent(
+        self,
+        room_id: str,
+        scenario: str = "travel",
+        level: str = "intermediate",
+        style: str = "friend",
+        agent_config: Optional[dict] = None,
+    ) -> dict:
+        """Start the voice coach agent (requires room already joined via TRTC SDK)."""
+        body: Dict[str, Any] = {
+            "RoomId": room_id,
+            "Scenario": scenario,
+            "Level": level,
+            "Style": style,
+        }
+        if agent_config:
+            body["AgentConfig"] = agent_config
+        data = self._post("/agent/start", body)
+        self.task_id = data.get("TaskId") or data.get("task_id")
+        return data
+
+    def stop_agent(self) -> dict:
+        """Stop the current agent session."""
+        return self._post("/agent/stop", {"TaskId": self.task_id})
+
+    def farewell(self, lang: str = "en", text: str = None) -> dict:
+        """Graceful farewell — triggers closing remarks + auto-stop."""
+        body: Dict[str, Any] = {"TaskId": self.task_id, "Lang": lang}
+        if text:
+            body["FarewellText"] = text
+        return self._post("/agent/farewell", body)
+
+    def invoke(self, text: str = "") -> dict:
+        """Push-to-talk: manually trigger AI reply."""
+        return self._post("/agent/invoke", {"TaskId": self.task_id, "Text": text})
+
+    # ─── Coach Capabilities ────────────────────────────────────────
+
+    def generate_scene(
+        self,
+        field: str,
+        scenario: str = "travel",
+        level: str = "intermediate",
+        style: str = "friend",
+        language: str = "en",
+        context: dict = None,
+    ) -> dict:
+        """Generate a random scene element (aiRole / myRole / scene)."""
+        body = {
+            "Field": field,
+            "Scenario": scenario,
+            "Level": level,
+            "Style": style,
+            "Language": language,
+        }
+        if context:
+            body["Context"] = context
+        return self._post("/scene/generate", body)
+
+    def correct(
+        self,
+        sentence: str,
+        scenario: str = "travel",
+        level: str = "intermediate",
+        ui_language: str = "en",
+    ) -> dict:
+        """Correct a single spoken sentence — returns corrected, explanation, grammar tips."""
+        return self._post("/correct", {
+            "UserSentence": sentence,
+            "Scenario": scenario,
+            "Level": level,
+            "UILanguage": ui_language,
+        })
+
+    def suggest(
+        self,
+        last_message: str,
+        scenario: str = "travel",
+        level: str = "intermediate",
+        style: str = "friend",
+    ) -> dict:
+        """Get 3 reply suggestions based on AI's last message."""
+        return self._post("/suggest", {
+            "AiLastMessage": last_message,
+            "Scenario": scenario,
+            "Level": level,
+            "Style": style,
+        })
+
+    def generate_report(
+        self,
+        transcript: List[dict],
+        duration_sec: int,
+        scenario: str = "travel",
+        level: str = "intermediate",
+        style: str = "friend",
+        language: str = "en",
+    ) -> dict:
+        """Generate a 4-dimension analysis report.
+
+        Args:
+            transcript: [{speaker, text, timestamp}, ...]
+            duration_sec: Session duration in seconds
+            language: en | zh
+        """
+        return self._post("/report", {
+            "Scenario": scenario,
+            "Level": level,
+            "Style": style,
+            "DurationSec": duration_sec,
+            "Transcript": transcript,
+            "Language": language,
+        })
+
+    # ─── Knowledge Base (optional) ─────────────────────────────────
+
+    def retrieve_kb(self, query: str, top_k: int = 3) -> dict:
+        """Retrieve KB segments (only works if custom-learning-kb is configured)."""
+        return self._post("/kb/retrieve", {"query": query, "top_k": top_k})

package/skills/trtc-ai-oral-coach/auto_adapters/web/README.md

@@ -0,0 +1,46 @@
+# Web Adapter — Oral Coach Headless Client
+
+> Auto-generated by ai-oral-coach auto_adapters/web.
+> This adapter generates `oral-coach-client.js` — a **headless** client module.
+> It handles HTTP API calls and TRTC custom message routing. No UI components.
+
+## What's generated
+
+| File | Contents |
+|:---|:---|
+| `oral-coach-client.js` | `OralCoachClient` class — full API wrapper (config / agent control / coach capabilities / KB) |
+
+## What you need to provide
+
+- **TRTC Web SDK** (`trtc-sdk-v5` or `trtc-js-sdk`): room entry, audio publish, custom message handling
+- **Your UI layer**: render subtitles, AI status, report, suggestions — the client provides data via callbacks
+
+## Integration flow
+
+```
+1. coach = new OralCoachClient({ userId: '...' })
+2. config = await coach.getConfig()           # GET /api/v1/config → UserSig, roomId
+3. Your code: use TRTC SDK to enter room with config
+4. coach.start({ roomId, scenario, level, style, agentConfig })  # POST /api/v1/agent/start
+5. Practice loop:
+   - coach.correct(sentence)                  # POST /api/v1/correct
+   - coach.suggest(lastAIMessage)             # POST /api/v1/suggest
+   - coach.invoke(text)                       # POST /api/v1/agent/invoke (push-to-talk)
+6. coach.generateReport({ transcript, durationSec })  # POST /api/v1/report
+7. coach.farewell()                           # POST /api/v1/agent/farewell
+
+TRTC hooks:
+  onCustomMessage(cmd, data) → coach.handleTRTCMessage(cmd, data)
+```
+
+## Callback hooks (override in your UI)
+
+```js
+coach.onSubtitle = (text) => { /* render subtitle in your UI */ };
+coach.onAIStatus = (status) => { /* show listening/speaking/thinking */ };
+coach.onCorrectReady = (result) => { /* display correction card */ };
+coach.onSuggestReady = (hints) => { /* display suggestion chips */ };
+coach.onReportReady = (report) => { /* render 4-dimension report */ };
+coach.onSceneReady = (scene) => { /* update setup screen */ };
+coach.onError = (err) => { /* handle errors gracefully */ };
+```

package/skills/trtc-ai-oral-coach/auto_adapters/web/oral-coach-client.js.tpl

@@ -0,0 +1,210 @@
+// oral-coach-client.js
+// Auto-generated by ai-oral-coach auto_adapters/web
+// Headless client — your UI, our APIs. No UI components emitted.
+//
+// Usage:
+//   import { OralCoachClient } from './oral-coach-client.js';
+//   const coach = new OralCoachClient({ baseUrl: '${SKELETON_BASE_URL}', userId: 'student_001' });
+//   await coach.init();
+//   const { config } = await coach.getConfig();
+//   // ... use TRTC SDK to enter room with config ...
+//   await coach.start({ scenario: 'travel', level: 'intermediate', style: 'friend', roomId: config.roomId, agentConfig: config.agentConfig });
+//   // ... coach callbacks fire: onSubtitle / onAIStatus ...
+
+const DEFAULT_BASE_URL = '${SKELETON_BASE_URL}';
+const API_PREFIX = '${API_PREFIX}';
+
+class OralCoachClient {
+  /**
+   * @param {Object} opts
+   * @param {string} [opts.baseUrl]  Coach backend URL
+   * @param {string} opts.userId     Unique user identifier
+   * @param {Object} [opts.trtc]     TRTC SDK instance (if you manage it yourself)
+   */
+  constructor(opts = {}) {
+    this.baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+    this.userId = opts.userId || `user_${Date.now()}`;
+    this.taskId = null;
+    this.sessionId = null;
+    this._config = null;
+
+    // Callback hooks — override these in your UI layer
+    this.onSubtitle = (text) => {};        // CMD 10000: AI speech text
+    this.onAIStatus = (status) => {};      // CMD 10001: listening | speaking | thinking
+    this.onError = (err) => { console.error('[OralCoach]', err); };
+    this.onReportReady = (report) => {};   // After report generated
+    this.onCorrectReady = (result) => {};  // After quick-correct
+    this.onSuggestReady = (hints) => {};   // After reply-suggestion
+    this.onSceneReady = (scene) => {};     // After scene/generate
+  }
+
+  // ─── HTTP helpers ──────────────────────────────────────────
+
+  async _post(path, body = {}) {
+    const url = `${this.baseUrl}${API_PREFIX}${path}`;
+    const resp = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    if (!resp.ok) {
+      const err = await resp.text().catch(() => resp.statusText);
+      throw new Error(`POST ${path}: ${resp.status} ${err}`);
+    }
+    return resp.json();
+  }
+
+  async _get(path) {
+    const url = `${this.baseUrl}${API_PREFIX}${path}`;
+    const resp = await fetch(url);
+    if (!resp.ok) throw new Error(`GET ${path}: ${resp.status}`);
+    return resp.json();
+  }
+
+  // ─── Core: Config & Health ──────────────────────────────────
+
+  /** Get UserSig + room credentials. Call once before entering room. */
+  async getConfig() {
+    const data = await this._post('/config', { userid: this.userId });
+    this._config = data;
+    return data;
+  }
+
+  /** Health check — returns { status, tencent_cloud, trtc, llm } */
+  async health() {
+    return this._get('/health');
+  }
+
+  // ─── Agent Control ──────────────────────────────────────────
+
+  /**
+   * Start the voice coach agent (requires room already joined via TRTC SDK).
+   * @param {Object} params
+   * @param {string} params.roomId        TRTC room ID
+   * @param {string} params.scenario      travel | work | study | free
+   * @param {string} params.level         beginner | intermediate | advanced
+   * @param {string} params.style         friend | listener
+   * @param {Object} params.agentConfig   { UserId, UserSig, TargetUserId }
+   */
+  async start({ roomId, scenario, level, style, agentConfig }) {
+    const data = await this._post('/agent/start', {
+      RoomId: roomId,
+      Scenario: scenario,
+      Level: level,
+      Style: style,
+      AgentConfig: agentConfig,
+    });
+    this.taskId = data.TaskId || data.task_id;
+    this.sessionId = data.SessionId || data.session_id;
+    return data;
+  }
+
+  /** Stop the current agent session. */
+  async stop() {
+    return this._post('/agent/stop', { TaskId: this.taskId });
+  }
+
+  /** Graceful farewell — triggers closing remarks + auto-stop. */
+  async farewell(lang = 'en') {
+    return this._post('/agent/farewell', { TaskId: this.taskId, Lang: lang });
+  }
+
+  /** Push-to-talk: manually trigger AI reply (no voice input needed). */
+  async invoke(text) {
+    return this._post('/agent/invoke', { TaskId: this.taskId, Text: text || '' });
+  }
+
+  // ─── Coach Capabilities ─────────────────────────────────────
+
+  /**
+   * Generate a random scene element (aiRole / myRole / scene description).
+   * @param {string} field       aiRole | myRole | scene
+   * @param {Object} context     { Scenario, Level, Style, Language }
+   */
+  async generateScene(field, context = {}) {
+    const data = await this._post('/scene/generate', { Field: field, ...context });
+    this.onSceneReady(data);
+    return data;
+  }
+
+  /**
+   * Correct a single spoken sentence.
+   * @param {string} sentence   The user's spoken sentence
+   * @param {Object} context    { Scenario, Level, UILanguage? }
+   */
+  async correct(sentence, context = {}) {
+    const data = await this._post('/correct', {
+      UserSentence: sentence,
+      Scenario: context.Scenario || 'travel',
+      Level: context.Level || 'intermediate',
+      UILanguage: context.UILanguage || 'en',
+    });
+    this.onCorrectReady(data);
+    return data;
+  }
+
+  /**
+   * Get 3 reply suggestions based on AI's last message.
+   * @param {string} lastMessage  AI's most recent utterance
+   * @param {Object} context      { Scenario, Level, Style }
+   */
+  async suggest(lastMessage, context = {}) {
+    const data = await this._post('/suggest', {
+      AiLastMessage: lastMessage,
+      Scenario: context.Scenario || 'travel',
+      Level: context.Level || 'intermediate',
+      Style: context.Style || 'friend',
+    });
+    this.onSuggestReady(data);
+    return data;
+  }
+
+  /**
+   * Generate a 4-dimension analysis report.
+   * @param {Object} params
+   * @param {Array}  params.transcript   [{speaker, text, timestamp}]
+   * @param {number} params.durationSec  Session duration in seconds
+   * @param {string} params.level        beginner | intermediate | advanced
+   * @param {string} params.style        friend | listener
+   * @param {string} params.scenario     travel | work | study | free
+   * @param {string} params.language     en | zh
+   */
+  async generateReport({ transcript, durationSec, level, style, scenario, language = 'en' }) {
+    const data = await this._post('/report', {
+      Scenario: scenario || 'travel',
+      Level: level || 'intermediate',
+      Style: style || 'friend',
+      DurationSec: durationSec,
+      Transcript: transcript,
+      Language: language,
+    });
+    this.onReportReady(data);
+    return data;
+  }
+
+  // ─── Knowledge Base (optional) ──────────────────────────────
+
+  /** Retrieve KB segments (only works if custom-learning-kb is configured). */
+  async retrieveKb(query, topK = 3) {
+    return this._post('/kb/retrieve', { query, top_k: topK });
+  }
+
+  // ─── TRTC Custom Message Handler ────────────────────────────
+  // Call this from your TRTC SDK onCustomMessage callback.
+
+  handleTRTCMessage(cmd, data) {
+    switch (cmd) {
+      case 10000:  // Subtitle
+        this.onSubtitle(typeof data === 'string' ? data : data?.text || '');
+        break;
+      case 10001:  // AI Status
+        this.onAIStatus(typeof data === 'string' ? data : data?.status || '');
+        break;
+      default:
+        break;
+    }
+  }
+}
+
+export { OralCoachClient };
+export default OralCoachClient;

package/skills/trtc-ai-oral-coach/capabilities/ability-report/manifest.yaml

@@ -0,0 +1,52 @@
+# ability-report —— 4 维能力分析报告
+name: ability-report
+version: "1.0.0"
+type: capability
+description: "练习结束时，把整段 transcript 生成 4 维能力分析（流利度/词汇/语法/完整度）+ 高光句 + 替代表达 + 下一步建议。双语并行。"
+
+dependencies:
+  - { name: conversation-core, version: ">=1.0.0,<2.0.0" }
+
+extensions:
+  - inject_at: server.router_extension
+    inline_code: |
+      from ._capability_loader import try_load_capability as _try
+      _m = _try("ability-report", "src/router.py")
+      if _m is not None and hasattr(_m, "router"):
+          app.include_router(_m.router, prefix="/api/v1/report", tags=["ability-report"])
+
+config:
+  max_transcript_turns: { default: 200 }                       # 上限，防滥用
+  languages:            { default: ["en", "zh"] }              # 双语并行生成
+  adapter:              { default: "default", env: "AR_ADAPTER" }
+
+endpoints:
+  - method: POST
+    path: /api/v1/report
+    description: "提交 transcript → 返回 4 维能力报告（{Reports:{en,zh}}）"
+
+business_contract:
+  port_class: "src.ports.evaluator.Evaluator"
+  default_adapter: "src.adapters.default.LLMEvaluator"
+  customization_sop: "references/evaluator-port.md#1-evaluator-port"
+  external_apis:
+    - name: report.generate
+      direction: inbound
+      method: POST
+      path: /api/v1/report
+      request_schema:  { scenario: string, level: string, style: string, durationSec: int, transcript: "array", language: string }
+      # 自由文本字段为目标语言；引用学习者原话保留英文
+      response_schema:
+        Reports:
+          en: "{ summary, abilityAnalysis{fluency,vocabulary,grammar,completeness}, mistakes[], betterExpressions[], nextSuggestions[] }"
+          zh: "{ 同 en 结构 }"
+
+integration:
+  auto_adapters:
+    - { tech_stack: ["react","vue","angular"], adapter: frontend-spa }
+    - { tech_stack: ["express","next"],        adapter: node-backend }
+    - { tech_stack: ["flask","fastapi"],        adapter: python-backend }
+
+acceptance:
+  - "提交 transcript 返回 4 维能力分析，无数字评分"
+  - "JSON 解析失败时走兜底骨架（至少 summary 不为空）"

package/skills/trtc-ai-oral-coach/capabilities/ability-report/src/__init__.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+"""ability-report 能力包。"""

package/skills/trtc-ai-oral-coach/capabilities/ability-report/src/adapters/__init__.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+"""adapters 子包。"""