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

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

@@ -0,0 +1,209 @@
+"""DefaultRestKbClient — call external FAQ / search API per business_contract default contract.
+
+Corresponding contracts:
+- POST   /faq/search             faq.search
+- GET    /faq                    faq.list
+- POST   /faq                    faq.upsert
+- DELETE /faq/{entry_id}         faq.delete
+
+Environment variables:
+- KB_REST_BASE_URL    FAQ service base URL
+- KB_REST_TOKEN       Bearer Token (optional)
+- KB_REST_TIMEOUT_MS  Timeout (default 5000)
+
+Security: consistent with human-handoff default_rest — only https / localhost; reject private networks.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import re
+from typing import List, Optional
+from urllib.parse import urlparse
+
+try:
+    import requests  # type: ignore
+except ImportError:  # pragma: no cover
+    requests = None  # type: ignore
+
+from ..core.models import FaqEntry, KbStats, SearchHit
+from ..ports.kb_client import KnowledgeBaseClient
+
+
+logger = logging.getLogger(__name__)
+
+
+_PRIVATE_PATTERNS = [
+    re.compile(r"^9\."),
+    re.compile(r"^10\."),
+    re.compile(r"^11\."),
+    re.compile(r"^21\."),
+    re.compile(r"^30\."),
+    re.compile(r"^169\.254\."),
+    re.compile(r"^172\.(1[6-9]|2[0-9]|3[01])\."),
+    re.compile(r"^192\.168\."),
+]
+
+
+def _is_localhost(host: str) -> bool:
+    return host in {"localhost", "127.0.0.1", "::1"}
+
+
+def _is_private(host: str) -> bool:
+    return any(p.match(host) for p in _PRIVATE_PATTERNS)
+
+
+def _validate_base_url(url: str) -> str:
+    parsed = urlparse(url)
+    if parsed.scheme not in {"http", "https"}:
+        raise ValueError(f"unsupported scheme: {parsed.scheme}")
+    host = parsed.hostname or ""
+    if not host:
+        raise ValueError("empty host in KB_REST_BASE_URL")
+    if parsed.scheme == "http" and not _is_localhost(host):
+        raise ValueError(
+            "non-HTTPS KB_REST_BASE_URL only allowed for localhost"
+        )
+    if _is_private(host):
+        raise ValueError(
+            f"access to private network host '{host}' is denied"
+        )
+    return url.rstrip("/")
+
+
+class DefaultRestKbClient(KnowledgeBaseClient):
+    """Call external FAQ service per default REST contract."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        token: Optional[str] = None,
+        timeout_ms: int = 5000,
+    ) -> None:
+        if requests is None:
+            raise RuntimeError(
+                "requests library is required for DefaultRestKbClient"
+            )
+        self._base = _validate_base_url(base_url)
+        self._token = token
+        self._timeout = max(0.5, timeout_ms / 1000.0)
+        self._session = requests.Session()
+
+    # ------------------------------------------------------------------
+    def search(
+        self,
+        query: str,
+        *,
+        top_k: Optional[int] = None,
+        min_score: Optional[float] = None,
+    ) -> List[SearchHit]:
+        if not query or not query.strip():
+            return []
+        payload: dict = {"query": query}
+        if top_k is not None:
+            payload["top_k"] = int(top_k)
+        if min_score is not None:
+            payload["min_score"] = float(min_score)
+        data = self._post("/faq/search", payload)
+        items = data if isinstance(data, list) else data.get("hits", [])
+        hits: List[SearchHit] = []
+        for it in items or []:
+            entry = it.get("entry") if isinstance(it, dict) else None
+            if entry is None and isinstance(it, dict) and "question" in it:
+                entry = it
+                score = float(it.get("score", 0.0))
+            else:
+                score = float(it.get("score", 0.0)) if isinstance(it, dict) else 0.0
+            if not entry:
+                continue
+            hits.append(
+                SearchHit(
+                    entry=FaqEntry.from_dict({**entry, "source": "remote_api"}),
+                    score=score,
+                )
+            )
+        return hits
+
+    def list_all(self) -> List[FaqEntry]:
+        data = self._get("/faq")
+        items = data if isinstance(data, list) else data.get("items", [])
+        return [FaqEntry.from_dict({**it, "source": "remote_api"}) for it in items]
+
+    def upsert(self, entry: FaqEntry) -> FaqEntry:
+        if not entry.id or not entry.question:
+            raise ValueError("id and question are required")
+        data = self._post("/faq", entry.to_dict())
+        return FaqEntry.from_dict({**data, "source": "remote_api"})
+
+    def delete(self, entry_id: str) -> bool:
+        url = self._base + f"/faq/{entry_id}"
+        resp = self._session.delete(
+            url, headers=self._headers(), timeout=self._timeout
+        )
+        if resp.status_code == 404:
+            return False
+        if resp.status_code >= 400:
+            raise RuntimeError(
+                f"remote kb service returned HTTP {resp.status_code}"
+            )
+        return True
+
+    def stats(self) -> KbStats:
+        try:
+            items = self.list_all()
+            return KbStats(
+                backend="remote_api",
+                entry_count=len(items),
+                data_source=self._base,
+            )
+        except Exception:  # noqa: BLE001
+            return KbStats(backend="remote_api", entry_count=-1, data_source=self._base)
+
+    # ------------------------------------------------------------------
+    def _headers(self) -> dict:
+        h = {"Content-Type": "application/json"}
+        if self._token:
+            h["Authorization"] = f"Bearer {self._token}"
+        return h
+
+    def _get(self, path: str):
+        resp = self._session.get(
+            self._base + path, headers=self._headers(), timeout=self._timeout
+        )
+        return self._handle(resp)
+
+    def _post(self, path: str, payload: dict):
+        resp = self._session.post(
+            self._base + path,
+            json=payload,
+            headers=self._headers(),
+            timeout=self._timeout,
+        )
+        return self._handle(resp)
+
+    @staticmethod
+    def _handle(resp):
+        if resp.status_code >= 400:
+            raise RuntimeError(
+                f"remote kb service returned HTTP {resp.status_code}"
+            )
+        try:
+            data = resp.json()
+        except ValueError as exc:
+            raise RuntimeError("remote kb service returned non-JSON") from exc
+        if isinstance(data, dict) and "data" in data and isinstance(data["data"], (dict, list)):
+            return data["data"]
+        return data
+
+
+# ---------------------------------------------------------------------------
+def from_env() -> Optional[DefaultRestKbClient]:
+    base = os.getenv("KB_REST_BASE_URL")
+    if not base:
+        return None
+    return DefaultRestKbClient(
+        base_url=base,
+        token=os.getenv("KB_REST_TOKEN"),
+        timeout_ms=int(os.getenv("KB_REST_TIMEOUT_MS", "5000")),
+    )

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

@@ -0,0 +1,86 @@
+"""adapter factory: selects KnowledgeBaseClient implementation based on environment variable.
+
+Environment variable `KB_ADAPTER`:
+    local_json    Default local JSON file search (production-ready, zero dependencies)
+    mock          Built-in demo FAQ (for Recipe video recording)
+    default_rest  Call remote FAQ service per business_contract default contract
+    user_custom   User integration wizard generated implementation
+
+When not set or invalid, fall back to local_json (keeps behavior compatibility with Phase 2).
+"""
+from __future__ import annotations
+
+import logging
+import os
+from typing import Optional
+
+from ..ports.kb_client import KnowledgeBaseClient
+
+
+logger = logging.getLogger(__name__)
+
+
+_VALID = ("local_json", "mock", "default_rest", "user_custom")
+
+
+def _build(name: str) -> Optional[KnowledgeBaseClient]:
+    if name == "local_json":
+        from .local_json import from_env as build_local
+        return build_local()
+    if name == "mock":
+        from .mock import from_env as build_mock
+        return build_mock()
+    if name == "default_rest":
+        from .default_rest import from_env as build_rest
+        c = build_rest()
+        if c is None:
+            logger.warning(
+                "KB_ADAPTER=default_rest but KB_REST_BASE_URL is empty; "
+                "falling back to local_json"
+            )
+        return c
+    if name == "user_custom":
+        try:
+            from .user_custom import from_env as build_custom  # type: ignore
+        except ImportError:
+            logger.warning(
+                "KB_ADAPTER=user_custom but src/adapters/user_custom.py is missing; "
+                "run scripts/contract-adapt.py knowledge-base to generate it"
+            )
+            return None
+        return build_custom()
+    return None
+
+
+def build_default() -> KnowledgeBaseClient:
+    name = (os.getenv("KB_ADAPTER") or "local_json").strip().lower()
+    if name not in _VALID:
+        logger.warning("KB_ADAPTER=%s is not recognised; using local_json", name)
+        name = "local_json"
+    client = _build(name)
+    if client is None:
+        from .local_json import from_env as build_local
+        client = build_local()
+    return client
+
+
+# ---------------------------------------------------------------------------
+_singleton: Optional[KnowledgeBaseClient] = None
+
+
+def get_client() -> KnowledgeBaseClient:
+    global _singleton
+    if _singleton is None:
+        _singleton = build_default()
+    return _singleton
+
+
+def set_client(client: KnowledgeBaseClient) -> None:
+    """For testing only: inject a custom client."""
+    global _singleton
+    _singleton = client
+
+
+def reset_client() -> None:
+    global _singleton
+    _singleton = None

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

@@ -0,0 +1,172 @@
+"""LocalJsonKbClient — default local implementation.
+
+Zero external dependencies. Reads FAQ from JSON file + TF-IDF scoring. Migrated from the original retriever.py implementation as the "default out-of-the-box" version.
+"""
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from ..core.models import FaqEntry, KbStats, SearchHit
+from ..core.scoring import build_df, tfidf_score, tokenize
+from ..ports.kb_client import KnowledgeBaseClient
+
+
+class LocalJsonKbClient(KnowledgeBaseClient):
+    """FAQ retriever based on local JSON file."""
+
+    def __init__(
+        self,
+        data_file: Optional[str | Path] = None,
+        *,
+        min_score: float = 0.1,
+        top_k: int = 3,
+    ) -> None:
+        self._lock = threading.RLock()
+        self._entries: List[FaqEntry] = []
+        self._df: Dict[str, int] = {}
+        self._min_score = float(min_score)
+        self._top_k = int(top_k)
+        self._data_file: Optional[Path] = (
+            Path(data_file) if data_file else None
+        )
+        self._loaded_at: Optional[float] = None
+        if self._data_file and self._data_file.exists():
+            self.reload()
+
+    # ------------------------------------------------------------------
+    # KnowledgeBaseClient required implementations
+    # ------------------------------------------------------------------
+    def search(
+        self,
+        query: str,
+        *,
+        top_k: Optional[int] = None,
+        min_score: Optional[float] = None,
+    ) -> List[SearchHit]:
+        if not query or not query.strip():
+            return []
+        k = top_k or self._top_k
+        threshold = float(min_score) if min_score is not None else self._min_score
+        q_tokens = tokenize(query)
+        if not q_tokens:
+            return []
+        with self._lock:
+            n = max(1, len(self._entries))
+            hits: List[SearchHit] = []
+            for entry in self._entries:
+                score = tfidf_score(entry, q_tokens, df=self._df, n_docs=n)
+                if score >= threshold:
+                    hits.append(SearchHit(entry=entry, score=score))
+            hits.sort(key=lambda h: h.score, reverse=True)
+            return hits[:k]
+
+    def list_all(self) -> List[FaqEntry]:
+        with self._lock:
+            return [
+                FaqEntry(
+                    id=e.id,
+                    question=e.question,
+                    answer=e.answer,
+                    keywords=list(e.keywords),
+                    source=e.source or "local_json",
+                )
+                for e in self._entries
+            ]
+
+    def upsert(self, entry: FaqEntry) -> FaqEntry:
+        if not entry.id or not entry.question:
+            raise ValueError("id and question are required")
+        with self._lock:
+            for i, e in enumerate(self._entries):
+                if e.id == entry.id:
+                    self._entries[i] = entry
+                    self._rebuild_df()
+                    self._persist()
+                    return entry
+            self._entries.append(entry)
+            self._rebuild_df()
+            self._persist()
+            return entry
+
+    def delete(self, entry_id: str) -> bool:
+        with self._lock:
+            before = len(self._entries)
+            self._entries = [e for e in self._entries if e.id != entry_id]
+            removed = before != len(self._entries)
+            if removed:
+                self._rebuild_df()
+                self._persist()
+            return removed
+
+    def stats(self) -> KbStats:
+        with self._lock:
+            return KbStats(
+                backend="local_json",
+                entry_count=len(self._entries),
+                loaded_at=self._loaded_at,
+                data_source=str(self._data_file) if self._data_file else None,
+            )
+
+    def reload(self) -> int:
+        if not self._data_file or not self._data_file.exists():
+            return 0
+        raw = json.loads(self._data_file.read_text(encoding="utf-8"))
+        with self._lock:
+            self._entries = [FaqEntry.from_dict(item) for item in raw]
+            for e in self._entries:
+                e.source = e.source or "local_json"
+            self._rebuild_df()
+            self._loaded_at = time.time()
+        return len(self._entries)
+
+    # ------------------------------------------------------------------
+    @property
+    def data_file(self) -> Optional[Path]:
+        return self._data_file
+
+    @property
+    def min_score(self) -> float:
+        return self._min_score
+
+    @property
+    def top_k(self) -> int:
+        return self._top_k
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+    def _rebuild_df(self) -> None:
+        self._df = build_df(self._entries)
+
+    def _persist(self) -> None:
+        if not self._data_file:
+            return
+        # Ensure directory exists
+        self._data_file.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self._data_file.with_suffix(self._data_file.suffix + ".tmp")
+        tmp.write_text(
+            json.dumps(
+                [e.to_dict() for e in self._entries],
+                ensure_ascii=False,
+                indent=2,
+            ),
+            encoding="utf-8",
+        )
+        os.replace(tmp, self._data_file)
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+def from_env() -> LocalJsonKbClient:
+    default_file = Path(__file__).resolve().parent.parent.parent / "data" / "faq.json"
+    return LocalJsonKbClient(
+        data_file=os.getenv("KB_DATA_FILE", str(default_file)),
+        min_score=float(os.getenv("KB_MIN_SCORE", "0.1")),
+        top_k=int(os.getenv("KB_TOP_K", "3")),
+    )

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

@@ -0,0 +1,91 @@
+"""MockKbClient — mock implementation for Recipe demo recording.
+
+Inherits LocalJsonKbClient; seeds embedded demo FAQ into memory on construction (no disk file dependency).
+
+Applicable scenarios:
+- User's first Recipe launch works out of the box even before data/faq.json has been filled in
+- Stable data for video demos, won't break due to external file changes
+"""
+from __future__ import annotations
+
+import os
+from typing import List
+
+from ..core.models import FaqEntry
+from .local_json import LocalJsonKbClient
+
+
+_DEMO_FAQ: List[dict] = [
+    {
+        "id": "demo_refund",
+        "question": "How do I request a refund?",
+        "answer": "Go to My Orders, pick the item, tap Request refund and fill in the reason. Once approved, the amount returns to your original payment within 1-3 business days.",
+        "keywords": ["refund", "money back", "return", "cancel order"],
+        "source": "demo_seed",
+    },
+    {
+        "id": "demo_logistics",
+        "question": "How long does shipping take?",
+        "answer": "Standard items ship within 48 hours. Major cities receive in 3-5 days; remote areas 5-7 days. You can track shipments in real time under My Orders.",
+        "keywords": ["shipping", "delivery", "tracking", "where is my package", "logistics"],
+        "source": "demo_seed",
+    },
+    {
+        "id": "demo_invoice",
+        "question": "How can I get an invoice?",
+        "answer": "Tick \"Need invoice\" at checkout and fill in your billing details. For existing orders, open the order in My Orders and tap Request invoice. E-invoices are emailed within 24 hours.",
+        "keywords": ["invoice", "receipt", "billing", "tax"],
+        "source": "demo_seed",
+    },
+    {
+        "id": "demo_size",
+        "question": "What if the size doesn't fit?",
+        "answer": "We offer 7-day free size exchange — return shipping is on us. Open My Orders, tap Exchange size and follow the instructions. If your size is out of stock you can request a refund and re-order.",
+        "keywords": ["size", "exchange", "doesn't fit", "wrong size"],
+        "source": "demo_seed",
+    },
+    {
+        "id": "demo_after_sale",
+        "question": "What is the warranty period?",
+        "answer": "All products carry a 1-year warranty. Electronics may be replaced within 30 days; after 30 days the manufacturer's warranty policy applies. Provide your order ID and a description of the issue and we'll open a ticket for you.",
+        "keywords": ["warranty", "after-sale", "repair", "broken", "defective"],
+        "source": "demo_seed",
+    },
+]
+
+
+class MockKbClient(LocalJsonKbClient):
+    """Mock implementation for demos."""
+
+    is_mock = True
+
+    def __init__(
+        self,
+        *,
+        min_score: float = 0.05,    # More lenient threshold for demos
+        top_k: int = 3,
+        seed_demo_data: bool = True,
+    ) -> None:
+        # No data_file specified — data is entirely memory-resident
+        super().__init__(
+            data_file=None,
+            min_score=min_score,
+            top_k=top_k,
+        )
+        if seed_demo_data:
+            self._seed()
+
+    def _seed(self) -> None:
+        for raw in _DEMO_FAQ:
+            entry = FaqEntry.from_dict(raw)
+            self._entries.append(entry)
+        self._rebuild_df()
+
+
+# ---------------------------------------------------------------------------
+def from_env() -> MockKbClient:
+    return MockKbClient(
+        min_score=float(os.getenv("KB_MIN_SCORE", "0.05")),
+        top_k=int(os.getenv("KB_TOP_K", "3")),
+        seed_demo_data=os.getenv("KB_MOCK_SEED", "1") not in ("0", "false", "False"),
+    )

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

@@ -0,0 +1,12 @@
+"""knowledge-base core module."""
+from .models import FaqEntry, KbStats, SearchHit
+from .service import KbService, get_default_service, reset_default_service
+
+__all__ = [
+    "FaqEntry",
+    "KbService",
+    "KbStats",
+    "SearchHit",
+    "get_default_service",
+    "reset_default_service",
+]

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

@@ -0,0 +1,77 @@
+"""knowledge-base core models.
+
+Defines unified domain models:
+- FaqEntry  Knowledge entry (id / question / answer / keywords / source)
+- SearchHit Search hit (with score)
+- KbStats   Knowledge base statistics (entry count / data source type / load time)
+
+All adapters must use this module's data structures as transport objects.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+@dataclass
+class FaqEntry:
+    """A single FAQ knowledge entry."""
+
+    id: str
+    question: str
+    answer: str
+    keywords: List[str] = field(default_factory=list)
+    # Optional: annotate entry source (local_json / remote_api / user_uploaded etc.), useful for dashboard display
+    source: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "question": self.question,
+            "answer": self.answer,
+            "keywords": list(self.keywords),
+            **({"source": self.source} if self.source else {}),
+        }
+
+    @classmethod
+    def from_dict(cls, raw: dict) -> "FaqEntry":
+        return cls(
+            id=str(raw.get("id") or raw.get("question", ""))[:64] or "auto",
+            question=str(raw.get("question", "")).strip(),
+            answer=str(raw.get("answer", "")).strip(),
+            keywords=[
+                str(k).strip()
+                for k in (raw.get("keywords") or [])
+                if str(k).strip()
+            ],
+            source=raw.get("source"),
+        )
+
+
+@dataclass
+class SearchHit:
+    """Search hit."""
+
+    entry: FaqEntry
+    score: float
+
+    def to_dict(self) -> dict:
+        return {"entry": self.entry.to_dict(), "score": round(float(self.score), 4)}
+
+
+@dataclass
+class KbStats:
+    """Knowledge base statistics (dashboard use)."""
+
+    backend: str                    # "local_json" / "remote_api" / "mock" / "user_custom"
+    entry_count: int
+    loaded_at: Optional[float] = None
+    data_source: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        return {
+            "backend": self.backend,
+            "entry_count": self.entry_count,
+            "loaded_at": self.loaded_at,
+            "data_source": self.data_source,
+        }