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

package/skills/trtc-ai-service/capabilities/human-handoff/src/trigger.py

@@ -0,0 +1,25 @@
+"""trigger.py — compatibility facade.
+
+Keeps the `maybe_handoff` / `is_handoff_intent` public symbols for manifest.extensions
+(agent.before_push_text) to continue calling as `_hh_trigger.maybe_handoff(session_id, text)`,
+internally delegated to the refactored core.service.HandoffService.
+
+New code should use core.service / core.intent_detector directly; do not depend on this facade.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from .core.intent_detector import is_handoff_intent  # noqa: F401  (public API)
+from .core.service import get_default_service
+
+
+def maybe_handoff(session_id: str, text: str) -> Optional[str]:
+    """For conversation-core.before_push_text injection point use.
+
+    Signature fully consistent with original: returns None when not triggered; returns a string when text has been replaced with handoff script.
+    """
+    return get_default_service().maybe_handoff(session_id, text)
+
+
+__all__ = ["is_handoff_intent", "maybe_handoff"]

package/skills/trtc-ai-service/capabilities/knowledge-base/INTERFACE_ADAPT.md

@@ -0,0 +1,297 @@
+# knowledge-base Interface Adaptation SOP
+
+> When the user's existing knowledge base / FAQ / retrieval system API diverges from this capability's default contract, follow this document for scenario-specific operations.
+> Recommended: use `python scripts/contract-adapt.py knowledge-base` for automated generation; this document is the manual fallback.
+
+---
+
+## 1. Default Contract Overview
+
+This capability **calls** the user's knowledge base interfaces (outbound):
+
+| Contract | Method | Path | Purpose |
+|---|---|---|---|
+| `faq.search`  | POST   | `/faq/search`        | Keyword search |
+| `faq.list`    | GET    | `/faq`               | List all entries |
+| `faq.upsert`  | POST   | `/faq`               | Create / update |
+| `faq.delete`  | DELETE | `/faq/{entry_id}`    | Delete entry |
+
+Full field definitions in `manifest.yaml` `business_contract.external_apis`.
+
+---
+
+## 2. Three-Layer Defense Mechanism
+
+| Layer | Artifact Location | Applicable Scenario |
+|---|---|---|
+| **L1 Field Mapping** | Only field name / simple type differences | 90% of common cases |
+| **L2 Adapter Subclass** | Auth / path / error code differences | User's own KB system |
+| **L3 Full Custom Implementation** | Protocol-level differences (vector DB / GraphQL / gRPC) | Non-REST protocols |
+
+All layers land in `capabilities/knowledge-base/src/adapters/user_custom.py` and are enabled via `KB_ADAPTER=user_custom`.
+
+---
+
+## 3. L1 Field Mapping (most common)
+
+### 3.1 Applicability Check
+
+- User API is still REST + JSON
+- Only field name differences (within `adapter_slots` scope)
+
+### 3.2 Steps
+
+**Step 1**: Paste user's curl or OpenAPI
+
+```bash
+curl -X POST https://kb.example.com/api/v3/search \
+  -H 'X-Api-Key: xxx' \
+  -d '{
+    "keyword": "refund",
+    "limit": 3
+  }'
+# Response:
+# {
+#   "results": [
+#     { "doc_id": "k001", "title": "How to refund", "content": "...", "tags": ["refund"], "relevance": 0.92 }
+#   ]
+# }
+```
+
+**Step 2**: Write mapping table `capabilities/knowledge-base/src/adapters/user_custom_mapping.yaml`
+
+```yaml
+faq.search:
+  request:
+    query:  keyword              # Field name mapping
+    top_k:  limit
+  response:
+    # response is array form; transformer needs to map results[] to hits[]
+    hits:   results
+    "hits[].entry.id":       "results[].doc_id"
+    "hits[].entry.question": "results[].title"
+    "hits[].entry.answer":   "results[].content"
+    "hits[].entry.keywords": "results[].tags"
+    "hits[].score":          "results[].relevance"
+
+faq.list:
+  response:
+    items: data                  # User uses data not items
+    "items[].id":       "data[].doc_id"
+    "items[].question": "data[].title"
+    "items[].answer":   "data[].content"
+    "items[].keywords": "data[].tags"
+```
+
+**Step 3**: Generate adapter
+
+```bash
+python scripts/contract-adapt.py knowledge-base \
+  --base-url https://kb.example.com \
+  --auth-header "X-Api-Key" \
+  --mapping capabilities/knowledge-base/src/adapters/user_custom_mapping.yaml
+```
+
+**Step 4**: Enable
+
+```bash
+export KB_ADAPTER=user_custom
+export KB_REST_BASE_URL=https://kb.example.com
+export KB_REST_TOKEN=<your-api-key>
+```
+
+---
+
+## 4. L2 Adapter Subclass (auth / path style differences)
+
+### 4.1 Applicability Check
+
+- Auth method is not Bearer (e.g. `X-Api-Key`, signature-based auth)
+- Different path templates
+- Different response wrapping (e.g. `{ code, msg, data: { ... } }`)
+
+### 4.2 Template Code
+
+```python
+# capabilities/knowledge-base/src/adapters/user_custom.py
+from typing import List, Optional
+
+from ..core.models import FaqEntry, SearchHit
+from .default_rest import DefaultRestKbClient
+
+
+class UserCustomKbClient(DefaultRestKbClient):
+    """User's own KB system adapter (L2)."""
+
+    def _headers(self) -> dict:
+        h = {"Content-Type": "application/json"}
+        if self._token:
+            h["X-Api-Key"] = self._token       # Not Bearer
+        return h
+
+    def search(
+        self,
+        query: str,
+        *,
+        top_k: Optional[int] = None,
+        min_score: Optional[float] = None,
+    ) -> List[SearchHit]:
+        if not query.strip():
+            return []
+        payload = {
+            "keyword": query,                  # Field remapping
+            "limit": int(top_k or 3),
+        }
+        # User API path is different
+        data = self._post("/api/v3/search", payload)
+        results = data.get("results", []) if isinstance(data, dict) else (data or [])
+        hits: List[SearchHit] = []
+        for r in results:
+            hits.append(
+                SearchHit(
+                    entry=FaqEntry(
+                        id=str(r.get("doc_id", "")),
+                        question=str(r.get("title", "")),
+                        answer=str(r.get("content", "")),
+                        keywords=list(r.get("tags") or []),
+                        source="remote_api",
+                    ),
+                    score=float(r.get("relevance", 0.0)),
+                )
+            )
+        return hits
+
+    def list_all(self) -> List[FaqEntry]:
+        data = self._get("/api/v3/docs")
+        items = data.get("data", []) if isinstance(data, dict) else (data or [])
+        return [
+            FaqEntry(
+                id=str(it.get("doc_id", "")),
+                question=str(it.get("title", "")),
+                answer=str(it.get("content", "")),
+                keywords=list(it.get("tags") or []),
+                source="remote_api",
+            )
+            for it in items
+        ]
+
+
+def from_env() -> Optional["UserCustomKbClient"]:
+    import os
+    base = os.getenv("KB_REST_BASE_URL")
+    if not base:
+        return None
+    return UserCustomKbClient(
+        base_url=base,
+        token=os.getenv("KB_REST_TOKEN"),
+        timeout_ms=int(os.getenv("KB_REST_TIMEOUT_MS", "5000")),
+    )
+```
+
+---
+
+## 5. L3 Full Custom (vector DB / GraphQL / gRPC)
+
+### 5.1 Applicability Check
+
+- User uses vector database (Milvus / Pinecone / Qdrant) for semantic search
+- User uses GraphQL instead of REST
+- User uses gRPC
+
+### 5.2 Template Code (vector DB example)
+
+```python
+# capabilities/knowledge-base/src/adapters/user_custom.py
+from typing import List, Optional
+
+from ..core.models import FaqEntry, KbStats, SearchHit
+from ..ports.kb_client import KnowledgeBaseClient
+
+
+class UserCustomKbClient(KnowledgeBaseClient):
+    """Vector DB adapter example (L3: directly implements KnowledgeBaseClient)."""
+
+    def __init__(self, **kwargs):
+        # TODO Initialize vector DB client:
+        # self._milvus = MilvusClient(uri=...)
+        # self._embedder = SentenceTransformer(...)
+        ...
+
+    def search(self, query, *, top_k=None, min_score=None) -> List[SearchHit]:
+        # TODO Call embedder + vector retrieval
+        # vec = self._embedder.encode(query)
+        # results = self._milvus.search(vec, top_k=top_k or 3)
+        results = []
+        return [
+            SearchHit(
+                entry=FaqEntry(id=r["id"], question=r["q"], answer=r["a"]),
+                score=float(r["distance"]),
+            )
+            for r in results
+        ]
+
+    def list_all(self) -> List[FaqEntry]:
+        # TODO Vector DBs may not support enumeration; return empty or raise NotSupported
+        return []
+
+    def upsert(self, entry: FaqEntry) -> FaqEntry:
+        # TODO Write vectors
+        return entry
+
+    def delete(self, entry_id: str) -> bool:
+        # TODO
+        return False
+
+    def stats(self) -> KbStats:
+        return KbStats(backend="vector_db", entry_count=-1)
+
+
+def from_env():
+    import os
+    return UserCustomKbClient(
+        endpoint=os.getenv("KB_VECTOR_ENDPOINT", ""),
+        api_key=os.getenv("KB_VECTOR_TOKEN", ""),
+    )
+```
+
+---
+
+## 6. Switch / Verify
+
+### 6.1 Enable user_custom
+
+```bash
+export KB_ADAPTER=user_custom
+# Takes effect after service restart
+```
+
+### 6.2 Unit Self-Check
+
+```bash
+python -c "
+from capabilities.knowledge_base.src.adapters.factory import build_default
+c = build_default()
+print('adapter:', type(c).__name__)
+hits = c.search('refund')
+for h in hits:
+    print(' ', h.score, h.entry.question)
+"
+```
+
+### 6.3 End-to-End
+
+```bash
+curl -X POST http://localhost:3000/api/v1/kb/search \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"refund","top_k":3}'
+```
+
+---
+
+## 7. Security Checklist
+
+- [ ] `KB_REST_BASE_URL` must use https:// (localhost excepted)
+- [ ] Default reject private network addresses
+- [ ] Auth token only from environment variables
+- [ ] User-uploaded FAQ content sanitized via `_strip_html` (built into router)
+- [ ] Remote exceptions do not print response bodies

package/skills/trtc-ai-service/capabilities/knowledge-base/README.md

@@ -0,0 +1,51 @@
+# knowledge-base · FAQ Retrieval Capability
+
+> Adds minimal FAQ retrieval to the conversation-core skeleton with zero external dependencies.
+
+## Install
+
+```bash
+# From repo root
+python scripts/add-capability.py knowledge-base
+```
+
+## Configuration
+
+| Env Variable | Default | Description |
+|:---|:---|:---|
+| `KB_DATA_FILE` | `capabilities/knowledge-base/data/faq.json` | FAQ data file |
+| `KB_TOP_K`    | `3`   | Max entries to backfill per query |
+| `KB_MIN_SCORE`| `0.1` | Hit threshold (entries below this are not injected) |
+
+## REST API
+
+| Method | Path | Purpose |
+|:---|:---|:---|
+| GET  | `/api/v1/kb/list`    | List all entries |
+| POST | `/api/v1/kb/search`  | Keyword search |
+| POST | `/api/v1/kb/upsert`  | Create / update |
+| DELETE | `/api/v1/kb/{id}`  | Delete |
+| POST | `/api/v1/kb/reload`  | Hot-reload from file |
+
+## Injection Strategy
+
+- `agent.before_start`: Append matched FAQ entries to the end of LLM `instructions`.
+- `server.router_extension`: Mount `/api/v1/kb/*` sub-router.
+
+## Data Format
+
+```json
+[
+  {
+    "id": "faq_xxx",
+    "question": "What ...?",
+    "answer": "...",
+    "keywords": ["alias1", "alias2"]
+  }
+]
+```
+
+## Security
+
+- HTML tags are automatically stripped when writing entries (XSS defense).
+- Length limits: `question ≤ 1024`, `answer ≤ 4096`, `query ≤ 256`.

package/skills/trtc-ai-service/capabilities/knowledge-base/data/faq.json

@@ -0,0 +1,20 @@
+[
+  {
+    "id": "faq_shipping_time",
+    "question": "What is the typical shipping time?",
+    "answer": "Standard shipping takes 3-5 business days; express shipping arrives within 1-2 business days.",
+    "keywords": ["shipping", "delivery", "tracking", "logistics"]
+  },
+  {
+    "id": "faq_return_policy",
+    "question": "How do I return a product?",
+    "answer": "Return requests can be filed within 30 days of delivery. Visit Account > Orders to initiate a return.",
+    "keywords": ["return", "refund", "exchange", "money back"]
+  },
+  {
+    "id": "faq_change_address",
+    "question": "Can I change the shipping address after ordering?",
+    "answer": "You can update the shipping address before the order enters the picking stage. Use Order Detail > Modify Address.",
+    "keywords": ["address", "modify", "change shipping", "update address"]
+  }
+]

package/skills/trtc-ai-service/capabilities/knowledge-base/manifest.yaml

@@ -0,0 +1,211 @@
+# knowledge-base capability self-describing manifest
+# Type: capability (optional install)
+
+name: "knowledge-base"
+version: "1.1.0"
+type: "capability"
+description: "FAQ retrieval + keyword matching (Phase 3 refactored to ports/adapters/core three-layer architecture)"
+
+# ---------------------------------------------------------------------------
+# Dependencies: only depends on the generic skeleton; no external databases
+# ---------------------------------------------------------------------------
+dependencies:
+  - name: "conversation-core"
+    version: ">=1.0.0,<2.0.0"
+
+# ---------------------------------------------------------------------------
+# Injection extensions into skeleton (maintains full Phase 2 compatibility; retriever.py is now a facade)
+# ---------------------------------------------------------------------------
+extensions:
+  # Prepend matched FAQ results to instructions before start_agent
+  - inject_at: "agent.before_start"
+    inline_code: |
+      # [knowledge-base] inject FAQ context if any user keywords present
+      if config is not None and getattr(config, "instructions", None):
+          from ._capability_loader import try_load_capability
+          _kb = try_load_capability("knowledge-base", "src/retriever.py")
+          if _kb is not None:
+              try:
+                  config.instructions = _kb.attach_faq_to_instructions(config.instructions)
+              except Exception as _kb_exc:  # noqa: BLE001
+                  logger.warning("knowledge-base FAQ injection failed: %s", _kb_exc)
+  # Mount sub-router after server.include_router
+  - inject_at: "server.router_extension"
+    inline_code: |
+      # [knowledge-base] mount sub-router
+      from ._capability_loader import try_load_capability as _try_load_capability
+      _kb_router_mod = _try_load_capability("knowledge-base", "src/router.py")
+      if _kb_router_mod is not None and hasattr(_kb_router_mod, "router"):
+          app.include_router(
+              _kb_router_mod.router, prefix="/api/v1/kb", tags=["knowledge-base"]
+          )
+
+# ---------------------------------------------------------------------------
+# Configuration interface
+# ---------------------------------------------------------------------------
+config:
+  data_file:
+    description: "FAQ data file path (JSON), used only by local_json adapter"
+    default: "capabilities/knowledge-base/data/faq.json"
+    env: "KB_DATA_FILE"
+  matcher:
+    description: "Matching strategy: keyword | tfidf | hybrid (local_json adapter defaults to tfidf)"
+    default: "tfidf"
+  top_k:
+    description: "Maximum number of FAQ entries to backfill"
+    default: 3
+    env: "KB_TOP_K"
+  min_score:
+    description: "Score threshold; entries below this threshold are not injected"
+    default: 0.1
+    env: "KB_MIN_SCORE"
+  adapter:
+    description: "Which KnowledgeBaseClient implementation to use: local_json | mock | default_rest | user_custom"
+    default: "local_json"
+    env: "KB_ADAPTER"
+
+# ---------------------------------------------------------------------------
+# API endpoints
+# ---------------------------------------------------------------------------
+endpoints:
+  - method: GET
+    path: /api/v1/kb/list
+    description: List all knowledge entries
+  - method: POST
+    path: /api/v1/kb/search
+    description: "Keyword search FAQ (body shape: {query, top_k?})"
+  - method: POST
+    path: /api/v1/kb/upsert
+    description: "Create or update entry (body shape: {id, question, answer, keywords[]})"
+  - method: DELETE
+    path: /api/v1/kb/{entry_id}
+    description: "Delete entry"
+  - method: POST
+    path: /api/v1/kb/reload
+    description: "Reload data from external source"
+  - method: GET
+    path: /api/v1/kb/stats
+    description: "Returns backend / entry count / load time (Phase 3 new)"
+
+# ---------------------------------------------------------------------------
+# Business contract (Phase 3 new; follows references/business-contract-spec.md v1.0)
+# ---------------------------------------------------------------------------
+business_contract:
+  port_class: "src.ports.kb_client.KnowledgeBaseClient"
+  default_adapter: "src.adapters.local_json.LocalJsonKbClient"
+  mock_adapter: "src.adapters.mock.MockKbClient"
+  customization_sop: "INTERFACE_ADAPT.md"
+  external_apis:
+    - name: faq.search
+      direction: outbound
+      method: POST
+      path: /faq/search
+      description: "Perform keyword search against external FAQ service"
+      request_schema:
+        query: string
+        top_k: int
+        min_score: float
+      response_schema:
+        hits:
+          - entry:
+              id: string
+              question: string
+              answer: string
+              keywords: string[]
+            score: float
+      adapter_slots:
+        - request.query
+        - request.top_k
+        - response.hits
+      auth:
+        type: bearer
+        location: header
+        name: Authorization
+      timeout_ms: 5000
+
+    - name: faq.list
+      direction: outbound
+      method: GET
+      path: /faq
+      description: "List all FAQ entries"
+      request_schema: {}
+      response_schema:
+        items:
+          - id: string
+            question: string
+            answer: string
+            keywords: string[]
+      adapter_slots:
+        - response.items
+      timeout_ms: 5000
+
+    - name: faq.upsert
+      direction: outbound
+      method: POST
+      path: /faq
+      description: "Create or update FAQ entry"
+      request_schema:
+        id: string
+        question: string
+        answer: string
+        keywords: string[]
+      response_schema:
+        id: string
+        question: string
+        answer: string
+        keywords: string[]
+      adapter_slots:
+        - request.id
+        - request.question
+        - request.answer
+        - request.keywords
+      timeout_ms: 5000
+
+    - name: faq.delete
+      direction: outbound
+      method: DELETE
+      path: /faq/{entry_id}
+      description: "Delete FAQ entry"
+      request_schema:
+        entry_id: string
+      response_schema:
+        deleted: string
+      adapter_slots:
+        - request.entry_id
+      timeout_ms: 3000
+
+# ---------------------------------------------------------------------------
+# Integration rules
+# ---------------------------------------------------------------------------
+integration:
+  mode: "auto"
+  auto_adapters:
+    - tech_stack: ["react", "vue", "angular"]
+      adapter: "frontend-spa"
+      description: "Inject an FAQ editor panel component into SPA"
+  fallback:
+    guided_templates:
+      - "../../auto_adapters/integration_templates/generic-frontend.md"
+    manual_api:
+      rest_endpoint: "/api/v1/kb"
+      sdk_packages: []
+
+# ---------------------------------------------------------------------------
+# Security
+# ---------------------------------------------------------------------------
+security:
+  log_redaction:
+    enabled: true
+    patterns: ["api_key", "token", "credential", "authorization"]
+  input_validation:
+    max_query_length: 256
+    forbid_html_tags: true     # Strip HTML when writing entries to prevent injection
+  network:
+    enforce_https: true        # default_rest adapter enforces HTTPS for non-localhost
+
+acceptance:
+  - "Provide keyword/tfidf retrieval interface with minimal implementation"
+  - "API endpoints available immediately after skeleton startup"
+  - "Instructions injection does not modify skeleton files; solely via manifest.extensions"
+  - "Switching KB_ADAPTER requires no business code changes (local_json / mock / default_rest / user_custom)"
+  - "default_rest adapter rejects private network addresses (except localhost)"

package/skills/trtc-ai-service/capabilities/knowledge-base/src/__init__.py

@@ -0,0 +1,8 @@
+"""knowledge-base capability: FAQ retrieval + keyword matching.
+
+Minimal implementation:
+- Data source: local JSON file (hot-reloadable)
+- Matching: keyword weighted scoring + optional TF-IDF (stop-word filtering)
+- Zero external dependencies, pure Python implementation
+"""
+__version__ = "1.0.0"

package/skills/trtc-ai-service/capabilities/knowledge-base/src/adapters/__init__.py

@@ -0,0 +1,9 @@
+"""knowledge-base adapter implementations."""
+from .factory import build_default, get_client, reset_client, set_client
+
+__all__ = [
+    "build_default",
+    "get_client",
+    "reset_client",
+    "set_client",
+]