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

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

@@ -0,0 +1,73 @@
+"""Tokenization + scoring utilities: migrated from original retriever.py.
+
+No external dependencies, pure Python:
+- Chinese: character bigram splitting
+- English: word-level splitting
+- TF-IDF scoring (keywords weighted 3x)
+"""
+from __future__ import annotations
+
+import math
+import re
+from typing import Dict, Iterable, List
+
+from .models import FaqEntry
+
+
+_WORD_RE = re.compile(r"[A-Za-z0-9_]+")
+_CN_RE = re.compile(r"[\u4e00-\u9fff]+")
+
+
+def tokenize(text: str) -> List[str]:
+    """Mixed Chinese/English tokenization."""
+    if not text:
+        return []
+    text = text.lower()
+    tokens: List[str] = []
+    tokens.extend(_WORD_RE.findall(text))
+    for blob in _CN_RE.findall(text):
+        if len(blob) == 1:
+            tokens.append(blob)
+        else:
+            tokens.extend(blob[i : i + 2] for i in range(len(blob) - 1))
+    return tokens
+
+
+def doc_tokens(entry: FaqEntry) -> List[str]:
+    """Generate token list for scoring a single entry (keywords weighted 3x)."""
+    toks = tokenize(entry.question) + tokenize(entry.answer)
+    for kw in entry.keywords:
+        toks.extend(tokenize(kw) * 3)
+    return toks
+
+
+def build_df(entries: Iterable[FaqEntry]) -> Dict[str, int]:
+    """Build document frequency table."""
+    df: Dict[str, int] = {}
+    for e in entries:
+        for t in set(doc_tokens(e)):
+            df[t] = df.get(t, 0) + 1
+    return df
+
+
+def tfidf_score(
+    entry: FaqEntry,
+    q_tokens: List[str],
+    *,
+    df: Dict[str, int],
+    n_docs: int,
+) -> float:
+    """TF-IDF score (normalized to [0, 1])."""
+    d_tokens = doc_tokens(entry)
+    if not d_tokens:
+        return 0.0
+    tf: Dict[str, int] = {}
+    for t in d_tokens:
+        tf[t] = tf.get(t, 0) + 1
+    score = 0.0
+    for t in q_tokens:
+        if t not in tf:
+            continue
+        idf = math.log((n_docs + 1) / (1 + df.get(t, 0))) + 1
+        score += (tf[t] / len(d_tokens)) * idf
+    return max(0.0, min(score, 1.0))

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

@@ -0,0 +1,78 @@
+"""KbService — Application service layer, combining KnowledgeBaseClient with instruction concatenation logic.
+
+Only depends on ports (KnowledgeBaseClient interface); does not know the specific backend.
+"""
+from __future__ import annotations
+
+from typing import List, Optional
+
+from ..ports.kb_client import KnowledgeBaseClient
+from .models import FaqEntry, KbStats, SearchHit
+
+
+class KbService:
+
+    def __init__(self, *, client: KnowledgeBaseClient) -> None:
+        self._client = client
+
+    # ------------------------------------------------------------------
+    def search(
+        self,
+        query: str,
+        *,
+        top_k: Optional[int] = None,
+        min_score: Optional[float] = None,
+    ) -> List[SearchHit]:
+        return self._client.search(query, top_k=top_k, min_score=min_score)
+
+    def list_all(self) -> List[FaqEntry]:
+        return self._client.list_all()
+
+    def upsert(self, entry: FaqEntry) -> FaqEntry:
+        return self._client.upsert(entry)
+
+    def delete(self, entry_id: str) -> bool:
+        return self._client.delete(entry_id)
+
+    def stats(self) -> KbStats:
+        return self._client.stats()
+
+    def reload(self) -> int:
+        return self._client.reload()
+
+    # ------------------------------------------------------------------
+    # For injection into conversation-core.before_start: concatenate search results into instructions
+    # ------------------------------------------------------------------
+    def attach_faq_to_instructions(
+        self,
+        instructions: str,
+        *,
+        max_hits: int = 3,
+    ) -> str:
+        if not instructions:
+            return instructions
+        hits = self._client.search(instructions, top_k=max_hits)
+        if not hits:
+            return instructions
+        block = ["", "# Retrieved Knowledge (auto-injected by knowledge-base capability)"]
+        for h in hits:
+            block.append(f"- Q: {h.entry.question}")
+            block.append(f"  A: {h.entry.answer}")
+        return instructions + "\n" + "\n".join(block)
+
+
+# ---------------------------------------------------------------------------
+_default_service: Optional[KbService] = None
+
+
+def get_default_service() -> KbService:
+    global _default_service
+    if _default_service is None:
+        from ..adapters.factory import get_client
+        _default_service = KbService(client=get_client())
+    return _default_service
+
+
+def reset_default_service() -> None:
+    global _default_service
+    _default_service = None

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

@@ -0,0 +1,4 @@
+"""knowledge-base abstract ports module."""
+from .kb_client import KnowledgeBaseClient
+
+__all__ = ["KnowledgeBaseClient"]

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

@@ -0,0 +1,61 @@
+"""knowledge-base abstract port (Port).
+
+Aligned with manifest.yaml.business_contract.external_apis:
+- search   -> faq.search
+- list_all -> faq.list
+- upsert   -> faq.upsert
+- delete   -> faq.delete
+
+All concrete implementations (local_json / default_rest / mock / user_custom) must inherit this ABC.
+The core layer only depends on this interface.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import List, Optional
+
+from ..core.models import FaqEntry, KbStats, SearchHit
+
+
+class KnowledgeBaseClient(ABC):
+    """Unified interface contract for knowledge base backends."""
+
+    # ------------------------------------------------------------------
+    # Aligned with business_contract
+    # ------------------------------------------------------------------
+    @abstractmethod
+    def search(
+        self,
+        query: str,
+        *,
+        top_k: Optional[int] = None,
+        min_score: Optional[float] = None,
+    ) -> List[SearchHit]:
+        """Search for matching FAQ entries. Corresponds to business_contract.faq.search."""
+
+    @abstractmethod
+    def list_all(self) -> List[FaqEntry]:
+        """List all entries. Corresponds to business_contract.faq.list."""
+
+    @abstractmethod
+    def upsert(self, entry: FaqEntry) -> FaqEntry:
+        """Create or update a single entry. Corresponds to business_contract.faq.upsert."""
+
+    @abstractmethod
+    def delete(self, entry_id: str) -> bool:
+        """Delete a single entry. Corresponds to business_contract.faq.delete."""
+
+    # ------------------------------------------------------------------
+    # Dashboard helper methods (default implementation; remote backends may not override)
+    # ------------------------------------------------------------------
+    def stats(self) -> KbStats:
+        """Return statistics (defaults to live calculation based on list_all)."""
+        items = self.list_all()
+        return KbStats(
+            backend=type(self).__name__,
+            entry_count=len(items),
+        )
+
+    def reload(self) -> int:
+        """Reload data from external source. Default no-op; local implementations can override to re-read files."""
+        return len(self.list_all())

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

@@ -0,0 +1,56 @@
+"""retriever.py — compatibility facade.
+
+Keeps the original `attach_faq_to_instructions` / `get_retriever` / `FaqEntry` / `SearchHit`
+public symbols for manifest.extensions (agent.before_start) and external callers to continue using.
+
+New code should use directly:
+- adapters.factory.get_client()        Get KnowledgeBaseClient instance
+- core.service.get_default_service()   Get KbService instance
+"""
+from __future__ import annotations
+
+import warnings
+
+from .core.models import FaqEntry, SearchHit  # noqa: F401  (public API)
+from .core.service import get_default_service
+
+
+def attach_faq_to_instructions(instructions: str) -> str:
+    """For use by conversation-core.before_start injection point.
+
+    Keeps old signature: single instructions parameter, returns concatenated instructions.
+    """
+    return get_default_service().attach_faq_to_instructions(instructions)
+
+
+# --------------------------------------------------------------------
+# Deprecated shim: original FaqRetriever global instance / class
+# --------------------------------------------------------------------
+def get_retriever():
+    """[DEPRECATED] Return KnowledgeBaseClient instance.
+
+    Old FaqRetriever class method names (list_entries/upsert/delete/search/reload)
+    have corresponding methods on the new client (list_all/upsert/delete/search/reload),
+    though some signatures differ slightly (list_entries -> list_all).
+    """
+    warnings.warn(
+        "knowledge_base.retriever.get_retriever() is deprecated; "
+        "use adapters.factory.get_client() or core.service.get_default_service() instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    from .adapters.factory import get_client
+    return get_client()
+
+
+# Legacy alias
+FaqRetriever = "FaqRetriever (deprecated; use adapters.local_json.LocalJsonKbClient)"
+
+
+__all__ = [
+    "FaqEntry",
+    "FaqRetriever",
+    "SearchHit",
+    "attach_faq_to_instructions",
+    "get_retriever",
+]

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

@@ -0,0 +1,85 @@
+"""knowledge-base FastAPI sub-router.
+
+Mounted on skeleton: app.include_router(router, prefix="/api/v1/kb")
+
+Refactoring notes:
+- All business logic delegated to core.service.KbService
+- Response fields remain fully consistent with Phase 2 (using SearchHit.to_dict / FaqEntry.to_dict)
+"""
+from __future__ import annotations
+
+import re
+from typing import List, Optional
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from .core.models import FaqEntry
+from .core.service import get_default_service
+
+
+router = APIRouter()
+
+
+_HTML_TAG_RE = re.compile(r"<[^>]+>")
+
+
+def _strip_html(s: str) -> str:
+    return _HTML_TAG_RE.sub("", s).strip()
+
+
+class UpsertRequest(BaseModel):
+    id: str = Field(..., max_length=64)
+    question: str = Field(..., max_length=1024)
+    answer: str = Field(..., max_length=4096)
+    keywords: List[str] = Field(default_factory=list)
+
+
+class SearchRequest(BaseModel):
+    query: str = Field(..., max_length=256)
+    top_k: Optional[int] = Field(default=None, ge=1, le=20)
+
+
+@router.get("/list")
+def list_entries() -> dict:
+    items = get_default_service().list_all()
+    return {"code": 0, "data": [e.to_dict() for e in items]}
+
+
+@router.post("/search")
+def search(req: SearchRequest) -> dict:
+    hits = get_default_service().search(req.query, top_k=req.top_k)
+    return {"code": 0, "data": [h.to_dict() for h in hits]}
+
+
+@router.post("/upsert")
+def upsert(req: UpsertRequest) -> dict:
+    entry = FaqEntry(
+        id=req.id.strip(),
+        question=_strip_html(req.question),
+        answer=_strip_html(req.answer),
+        keywords=[_strip_html(k) for k in (req.keywords or []) if k.strip()],
+    )
+    if not entry.id or not entry.question:
+        raise HTTPException(status_code=400, detail="id and question are required")
+    saved = get_default_service().upsert(entry)
+    return {"code": 0, "data": saved.to_dict()}
+
+
+@router.delete("/{entry_id}")
+def delete(entry_id: str) -> dict:
+    ok = get_default_service().delete(entry_id)
+    if not ok:
+        raise HTTPException(status_code=404, detail=f"entry not found: {entry_id}")
+    return {"code": 0, "data": {"deleted": entry_id}}
+
+
+@router.post("/reload")
+def reload_data() -> dict:
+    n = get_default_service().reload()
+    return {"code": 0, "data": {"count": n}}
+
+
+@router.get("/stats")
+def stats() -> dict:
+    return {"code": 0, "data": get_default_service().stats().to_dict()}

package/skills/trtc-ai-service/capabilities/session-summary/INTERFACE_ADAPT.md

@@ -0,0 +1,99 @@
+# session-summary Interface Adaptation SOP
+
+> Session summary + structured summary write-back to CRM / ticketing / data platform.
+> This capability's source code has not been refactored to ports/adapters/core in this release (Phase 1 compromise).
+
+---
+
+## 1. Default Contract Overview
+
+| Contract | Method | Path | Purpose |
+|---|---|---|---|
+| `summary.write_to_crm`  | POST | `/sessions/{session_id}/summary` | Write finalized summary to user's CRM / ticketing system |
+| `summary.llm_summarize` | —   | Reuses conversation-core `llm.chat_completions` | LLM secondary summarization, no separate adaptation needed |
+
+Full field details in `manifest.yaml.business_contract.external_apis`.
+
+---
+
+## 2. Default Behavior
+
+session-summary currently **only writes to local files by default** (path `data/<session_id>.json`),
+and does not actively write to any remote system. This means:
+
+- Integrators need to scan the `data/` directory themselves or call `/api/v1/summary/{session_id}` to pull
+- No outbound calls are enabled, keeping security risk low
+- Suitable as a "draft state"; integrators plug into business systems on demand
+
+---
+
+## 3. Enabling CRM Write-Back
+
+### 3.1 Configure Default Contract
+
+```bash
+# Enable CRM write-back + user's CRM API fully matches default contract
+export SS_CRM_WRITE_ENABLED=1
+export SS_CRM_BASE_URL=https://crm.example.com
+export SS_CRM_TOKEN=sk-xxx
+```
+
+> The current capability source code has **not implemented** the `SS_CRM_*` environment variable logic;
+> you need to write an adapter subclass per §4 below before enabling. After Phase 4's full refactor, this will become out-of-the-box.
+
+### 3.2 Custom Field Mapping
+
+If the user's CRM API has different field names (e.g. `summary` / `priority` / `tags`), write a simple
+webhook middleware layer or append an HTTP call at the end of `recorder.py`'s `finalize_session` function.
+
+Reference code snippet (manually append to `src/recorder.py`'s finalize section):
+
+```python
+import os, requests
+def _maybe_write_crm(session_id: str, summary_payload: dict):
+    base = os.getenv("SS_CRM_BASE_URL")
+    if not base or os.getenv("SS_CRM_WRITE_ENABLED") != "1":
+        return
+    # Field remapping example
+    body = {
+        "session_id": session_id,
+        "summary": summary_payload.get("topic"),       # User's field is called summary
+        "priority": summary_payload.get("outcome"),    # User's field is called priority
+        "tags": summary_payload.get("next_actions"),
+    }
+    requests.post(
+        f"{base}/sessions/{session_id}/summary",
+        json=body,
+        headers={"Authorization": f"Bearer {os.getenv('SS_CRM_TOKEN', '')}"},
+        timeout=5,
+    )
+```
+
+---
+
+## 4. Phase 4 Plan: Full ports/adapters Refactor
+
+The following will be introduced in the future:
+
+```
+capabilities/session-summary/src/
+├── ports/
+│   └── crm_client.py          # ABC: write_summary / query_summary
+└── adapters/
+    ├── local_file.py          # Default implementation: local disk only (current behavior)
+    ├── default_rest.py        # Calls per default CRM contract
+    ├── mock.py                # Mock for demos
+    └── user_custom.py         # User integration wizard generator
+```
+
+At that time, `SS_ADAPTER=user_custom` will support direct switching without manually modifying recorder.py.
+
+---
+
+## 5. Security Checklist
+
+- [ ] CRM write-back auto-redacts sensitive fields (`secret_id` / `api_key` / `token` etc.)
+- [ ] `SS_CRM_BASE_URL` must use https:// (localhost excepted)
+- [ ] Reject private network addresses
+- [ ] Disk file permissions enforced to 0600 (declared in manifest.security.storage)
+- [ ] Summary transcripts filter out sensitive user PII (phone / ID numbers) — current capability **not implemented**; user's business layer must handle this

package/skills/trtc-ai-service/capabilities/session-summary/README.md

@@ -0,0 +1,47 @@
+# session-summary · Session Summary + Structured Abstract
+
+> Auto-archives turn records for each session on top of conversation-core,
+> and produces structured summaries (topics / intents / next_actions) after calling `finalize`.
+
+## Install
+
+```bash
+python scripts/add-capability.py session-summary
+```
+
+## Configuration
+
+| Env Variable | Default | Description |
+|:---|:---|:---|
+| `SS_STORAGE_DIR`    | `capabilities/session-summary/data/` | Summary landing directory (permissions 0600) |
+| `SS_RETENTION_DAYS` | `30` | Retention days; auto-cleanup after expiry |
+| `SS_LLM_SUMMARY`    | `true` | Whether to call LLM for secondary summarization (depends on `LLM_API_KEY`) |
+
+## REST API
+
+| Method | Path | Purpose |
+|:---|:---|:---|
+| GET  | `/api/v1/summary/_list?_offset=0&_limit=20` | Recent summary list |
+| GET  | `/api/v1/summary/{session_id}` | Single session summary details |
+| POST | `/api/v1/summary/{session_id}/finalize` | Close session and trigger summary |
+
+## Summary Output
+
+```json
+{
+  "topics":       ["order", "shipping"],
+  "user_intents": ["When will my order ship?"],
+  "next_actions": ["Please update my address"],
+  "highlights":   ["12 turns recorded"],
+  "engine":       "heuristic",
+  "model":        null
+}
+```
+
+LLM path falls back to local heuristic implementation on failure, ensuring offline availability.
+
+## Security
+
+- Disk file permissions enforced to `0600`
+- Sensitive fields (`secret_id / api_key / token / credential`) redacted before writing
+- Transcript text max length `4096`

package/skills/trtc-ai-service/capabilities/session-summary/data/test_session.json

@@ -0,0 +1,18 @@
+{
+  "session_id": "test_session",
+  "opened_at": 1780905036.267712,
+  "closed_at": null,
+  "turns": [
+    {
+      "role": "user",
+      "text": "Can you check the delivery status of order A1234?",
+      "ts": 1780905036.26798
+    },
+    {
+      "role": "assistant",
+      "text": "Usually 3-5 business days.",
+      "ts": 1780905036.2682061
+    }
+  ],
+  "summary": null
+}