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

package/skills/trtc-ai-service/capabilities/tool-calling/manifest.yaml

@@ -0,0 +1,146 @@
+# tool-calling capability self-describing manifest
+# Type: capability (optional install)
+# Risk mitigation: P1 alpha/beta dual-track priority arbitration (manifest explicitly declares priority)
+
+name: "tool-calling"
+version: "1.0.0"
+type: "capability"
+description: "Business tool calling - alpha/beta dual-track (local function first, remote API as fallback) + result re-injection"
+
+dependencies:
+  - name: "conversation-core"
+    version: ">=1.0.0,<2.0.0"
+
+# ---------------------------------------------------------------------------
+# Injection extensions into skeleton
+# ---------------------------------------------------------------------------
+extensions:
+  - inject_at: "agent.before_push_text"
+    inline_code: |
+      # [tool-calling] intercept text injection: recognize "/tool name args" to trigger local tool call
+      from ._capability_loader import try_load_capability
+      _tc_dispatcher = try_load_capability("tool-calling", "src/dispatcher.py")
+      if _tc_dispatcher is not None:
+          _hijack = _tc_dispatcher.maybe_dispatch(text)
+          if _hijack is not None:
+              # Replace original text with tool result, ensuring LLM receives tool-augmented content
+              text = _hijack
+  - inject_at: "server.router_extension"
+    inline_code: |
+      # [tool-calling] mount sub-router
+      from ._capability_loader import try_load_capability as _try_load_capability
+      _tc_router_mod = _try_load_capability("tool-calling", "src/router.py")
+      if _tc_router_mod is not None and hasattr(_tc_router_mod, "router"):
+          app.include_router(
+              _tc_router_mod.router, prefix="/api/v1/tools", tags=["tool-calling"]
+          )
+
+# ---------------------------------------------------------------------------
+# Configuration interface (alpha/beta dual-track)
+# ---------------------------------------------------------------------------
+config:
+  priority:
+    description: "Priority arbitration rule: alpha | beta | manifest_order"
+    default: "alpha"
+  timeout_ms_alpha:
+    default: 1000
+  timeout_ms_beta:
+    default: 5000
+  retry_alpha:
+    default: 0
+  retry_beta:
+    default: 1
+  registry_file:
+    description: "Tool registration declaration file (YAML), supports hot-reload"
+    default: "capabilities/tool-calling/data/tools.yaml"
+
+# ---------------------------------------------------------------------------
+# API endpoints
+# ---------------------------------------------------------------------------
+endpoints:
+  - method: GET
+    path: /api/v1/tools/list
+    description: List registered alpha/beta tools and their priority
+  - method: POST
+    path: /api/v1/tools/invoke
+    description: "Explicit tool invocation (body shape: {name, params, priority?})"
+  - method: POST
+    path: /api/v1/tools/reload
+    description: "Hot-reload registry"
+
+# ---------------------------------------------------------------------------
+# Integration rules
+# ---------------------------------------------------------------------------
+integration:
+  mode: "auto"
+  auto_adapters:
+    - tech_stack: ["express", "koa", "fastify", "next"]
+      adapter: "node-backend"
+      description: "Register beta-track remote tool implementation in Node.js backend"
+    - tech_stack: ["flask", "fastapi", "django"]
+      adapter: "python-backend"
+      description: "Directly register alpha-track local function in Python backend"
+    - tech_stack: ["spring-boot", "quarkus"]
+      adapter: "java-backend"
+      description: "Expose beta-track REST endpoints via Filter"
+  fallback:
+    guided_templates:
+      - "../../auto_adapters/integration_templates/generic-backend.md"
+    manual_api:
+      rest_endpoint: "/api/v1/tools"
+
+security:
+  log_redaction:
+    enabled: true
+    patterns: ["api_key", "token", "credential", "authorization"]
+  injection_protection:
+    prompt_injection_guard: true   # Whitelist validation of tool trigger keywords before entering LLM
+  network:
+    enforce_https: true            # Beta-track remote calls enforce HTTPS
+
+# ---------------------------------------------------------------------------
+# Business contract (Phase 3 new; follows references/business-contract-spec.md v1.0 §5)
+# tool-calling uses its own contract section (alpha/beta/arbitration), not the port/adapter template.
+# Source code is not refactored in this phase (compromise strategy); only declares contract for contract-adapt.py consumption.
+# ---------------------------------------------------------------------------
+business_contract:
+  customization_sop: "INTERFACE_ADAPT.md"
+
+  # Alpha track: local function registration specification
+  alpha_track:
+    interface: "src.dispatcher.LocalToolHandler"          # Equivalent abstraction in existing dispatcher
+    registration_schema:
+      name: string                  # Tool name (globally unique, snake_case)
+      description: string           # One-line description for LLM consumption
+      parameters: object            # JSON Schema describing parameters
+      handler: callable             # Sync/async Python callable
+    invocation_schema:
+      input: object                 # Same schema as parameters
+      output: object                # User-defined return structure (must be JSON-serializable)
+    fail_fast: true                 # Local exceptions thrown immediately for arbitration decision
+
+  # Beta track: remote business API integration specification
+  beta_track:
+    interface: "src.dispatcher.RemoteToolClient"          # Remote HTTP/RPC client abstraction
+    api_schema:
+      method: enum[GET, POST, PUT, DELETE, PATCH]
+      path: string
+      request_schema: object        # JSON Schema
+      response_schema: object       # JSON Schema
+      auth: enum[bearer, api_key, none]
+    timeout_ms: 5000
+    retry:
+      max: 1
+      backoff_ms: 200
+
+  # Arbitration rules
+  arbitration:
+    default_priority: alpha         # alpha | beta | manifest_order
+    fallback_on_failure: true
+    timeout_ms: 3000                # Single-track call timeout; triggers fallback on expiry
+    merge_strategy: first_success   # first_success | alpha_then_beta_diff
+
+acceptance:
+  - "Provide ToolRegistry supporting simultaneous alpha/beta implementation declarations"
+  - "Default alpha-first; auto-degraded to beta on alpha failure/unavailability"
+  - "REST endpoints available immediately after skeleton startup"

package/skills/trtc-ai-service/capabilities/tool-calling/src/__init__.py

@@ -0,0 +1,8 @@
+"""tool-calling capability: alpha/beta dual-track tool calling.
+
+Core modules:
+- registry  Load tools from YAML registration declarations + Python entry points
+- dispatcher  Recognize and trigger calls from conversation text ("/tool name {json}")
+- router  REST endpoints
+"""
+__version__ = "1.0.0"

package/skills/trtc-ai-service/capabilities/tool-calling/src/dispatcher.py

@@ -0,0 +1,54 @@
+"""Text injection interceptor: recognize "/tool" invocations from the conversation stream.
+
+Expected text format:
+    /tool <name> {json_params}
+
+Example:
+    /tool get_order {"order_id": "A1234"}
+
+Dispatcher parses and calls ToolRegistry, returning the result as a structured string,
+which is then forwarded to the LLM by conversation-core's injection point.
+"""
+from __future__ import annotations
+
+import json
+import re
+from typing import Optional
+
+from .registry import get_loader
+
+_TOOL_RE = re.compile(r"^\s*/tool\s+([A-Za-z0-9_\-]{1,64})\s*(\{.*\})?\s*$", re.DOTALL)
+_MAX_TEXT_LEN = 4096
+
+
+def maybe_dispatch(text: str) -> Optional[str]:
+    """Recognize "/tool" trigger, return new text with tool result; return None when not triggered."""
+    if not text or len(text) > _MAX_TEXT_LEN:
+        return None
+    m = _TOOL_RE.match(text)
+    if not m:
+        return None
+    name = m.group(1)
+    raw_params = m.group(2) or "{}"
+    try:
+        params = json.loads(raw_params)
+        if not isinstance(params, dict):
+            params = {}
+    except json.JSONDecodeError:
+        params = {}
+    result = get_loader().call(name, params)
+    payload = {
+        "tool": result.tool,
+        "track": result.track,
+        "ok": result.ok,
+        "output": result.output,
+        "error": result.error,
+        "latency_ms": result.latency_ms,
+        "fallback_chain": result.fallback_chain,
+    }
+    # Return in convention block, making it easy for LLM system prompt to recognize tool results
+    return (
+        f"[tool_result name={result.tool} track={result.track} ok={result.ok}]\n"
+        + json.dumps(payload, ensure_ascii=False)
+        + "\n[/tool_result]"
+    )

package/skills/trtc-ai-service/capabilities/tool-calling/src/registry.py

@@ -0,0 +1,219 @@
+"""ToolRegistry loader.
+
+YAML declaration example:
+    priority: alpha            # alpha | beta | manifest_order
+    tools:
+      - name: get_order
+        alpha:
+          module: "capabilities.tool_calling.examples.local_tools"
+          function: "get_order"
+          timeout_ms: 800
+        beta:
+          endpoint: "https://internal.example.com/api/orders"
+          method: "POST"
+          timeout_ms: 5000
+        description: "Query order"
+
+Loading strategy:
+- Alpha-track functions loaded dynamically via ``importlib``; when a module is missing, the tool retains only the beta track.
+- Beta track is declaration-only; invocation is done by dispatcher injecting ``beta_invoker``.
+"""
+from __future__ import annotations
+
+import importlib
+import logging
+import os
+import threading
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+# Import arbitrator via relative path (Phase 2 shared infrastructure)
+import sys
+_PROJECT_ROOT = Path(__file__).resolve().parents[3]
+if str(_PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(_PROJECT_ROOT))
+from scripts.lib.arbitrator import (  # noqa: E402
+    AlphaTool,
+    BetaTool,
+    ToolCallResult,
+    ToolRegistry,
+)
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_REGISTRY_FILE = Path(
+    os.getenv(
+        "TC_REGISTRY_FILE",
+        str(Path(__file__).resolve().parent.parent / "data" / "tools.yaml"),
+    )
+)
+
+
+class ToolRegistryLoader:
+    def __init__(self, registry_file: Optional[Path] = None) -> None:
+        self._lock = threading.RLock()
+        self._registry_file = Path(registry_file) if registry_file else _DEFAULT_REGISTRY_FILE
+        self._registry: ToolRegistry = ToolRegistry()
+        self._descriptions: Dict[str, str] = {}
+        if self._registry_file.exists():
+            self.reload()
+
+    @property
+    def registry(self) -> ToolRegistry:
+        with self._lock:
+            return self._registry
+
+    def reload(self) -> int:
+        if not self._registry_file.exists():
+            return 0
+        raw = yaml.safe_load(self._registry_file.read_text(encoding="utf-8")) or {}
+        priority = (raw.get("priority") or "alpha").strip()
+        new_reg = ToolRegistry(default_priority=priority)
+        descriptions: Dict[str, str] = {}
+        for tool_def in raw.get("tools") or []:
+            name = str(tool_def.get("name") or "").strip()
+            if not name:
+                continue
+            descriptions[name] = str(tool_def.get("description", ""))
+            alpha_def = tool_def.get("alpha")
+            beta_def = tool_def.get("beta")
+            if alpha_def:
+                func = self._load_callable(alpha_def)
+                if func is not None:
+                    new_reg.register_alpha(
+                        AlphaTool(
+                            name=name,
+                            func=func,
+                            timeout_ms=int(alpha_def.get("timeout_ms", 1000)),
+                            description=descriptions[name],
+                        )
+                    )
+            if beta_def and beta_def.get("endpoint"):
+                new_reg.register_beta(
+                    BetaTool(
+                        name=name,
+                        endpoint=str(beta_def["endpoint"]),
+                        method=str(beta_def.get("method", "POST")),
+                        timeout_ms=int(beta_def.get("timeout_ms", 5000)),
+                        headers=dict(beta_def.get("headers") or {}),
+                        description=descriptions[name],
+                    )
+                )
+        with self._lock:
+            self._registry = new_reg
+            self._descriptions = descriptions
+        return len(descriptions)
+
+    def list_tools(self) -> List[Dict[str, Any]]:
+        with self._lock:
+            return self._registry.list_tools()
+
+    def call(
+        self,
+        name: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        priority: Optional[str] = None,
+    ) -> ToolCallResult:
+        return self._registry.call(
+            name,
+            params,
+            priority=priority,
+            beta_invoker=_default_beta_invoker,
+        )
+
+    @staticmethod
+    def _load_callable(alpha_def: Dict[str, Any]):
+        mod_name = alpha_def.get("module")
+        func_name = alpha_def.get("function")
+        if not mod_name or not func_name:
+            return None
+        module = None
+        try:
+            module = importlib.import_module(mod_name)
+        except ImportError:
+            # Fallback: capability directory name has hyphens (tool-calling), standard import cannot resolve it
+            # capabilities.tool_calling.* - switched to file-path-based loading (registry knows its own location).
+            module = ToolRegistryLoader._load_module_by_path(mod_name)
+        if module is None:
+            logger.warning("alpha tool module not loadable: %s", mod_name)
+            return None
+        return getattr(module, func_name, None)
+
+    @staticmethod
+    def _load_module_by_path(mod_name: str):
+        """Map dotted module name to file path within capability package and load.
+
+        Convention: module name like ``capabilities.tool_calling.examples.local_tools``,
+        take the ``examples`` segment and everything after as the path relative to ``<capability_root>``.
+        """
+        import importlib.util
+
+        cap_root = Path(__file__).resolve().parent.parent  # capabilities/tool-calling/
+        parts = mod_name.split(".")
+        # Strip capabilities.<cap> prefix (regardless of underscores / hyphens), keep the examples/... tail
+        tail: List[str] = []
+        seen_examples = False
+        for p in parts:
+            if p == "examples":
+                seen_examples = True
+            if seen_examples:
+                tail.append(p)
+        if not tail:
+            tail = parts[-2:]  # Fallback: take last two segments
+        file_path = cap_root.joinpath(*tail).with_suffix(".py")
+        if not file_path.is_file():
+            return None
+        qual = "_tc_local_" + "_".join(tail)
+        cached = sys.modules.get(qual)
+        if cached is not None:
+            return cached
+        spec = importlib.util.spec_from_file_location(qual, file_path)
+        if spec is None or spec.loader is None:
+            return None
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[qual] = module
+        try:
+            spec.loader.exec_module(module)
+        except Exception as exc:  # noqa: BLE001
+            sys.modules.pop(qual, None)
+            logger.warning("alpha tool file load failed %s: %s", file_path, exc)
+            return None
+        return module
+
+
+# ---------------------------------------------------------------------------
+# Beta-track default implementation: requests sync POST / GET
+# ---------------------------------------------------------------------------
+def _default_beta_invoker(tool: BetaTool, params: Dict[str, Any]) -> Any:
+    import requests  # Already in skeleton requirements
+
+    if not tool.endpoint.startswith("https://") and not tool.endpoint.startswith("http://localhost"):
+        # Security: except localhost debugging, beta-track enforces HTTPS (manifest.security.network.enforce_https)
+        raise RuntimeError(f"β endpoint must use HTTPS: {tool.endpoint}")
+    headers = {"Content-Type": "application/json", **tool.headers}
+    timeout = max(tool.timeout_ms, 100) / 1000.0
+    method = tool.method.upper()
+    if method == "GET":
+        resp = requests.get(tool.endpoint, params=params, headers=headers, timeout=timeout)
+    else:
+        resp = requests.request(
+            method, tool.endpoint, json=params, headers=headers, timeout=timeout
+        )
+    resp.raise_for_status()
+    ctype = resp.headers.get("Content-Type", "")
+    if "application/json" in ctype:
+        return resp.json()
+    return resp.text
+
+
+# ---------------------------------------------------------------------------
+# Global singleton (used by dispatcher / router)
+# ---------------------------------------------------------------------------
+_global_loader = ToolRegistryLoader()
+
+
+def get_loader() -> ToolRegistryLoader:
+    return _global_loader

package/skills/trtc-ai-service/capabilities/tool-calling/src/router.py

@@ -0,0 +1,50 @@
+"""tool-calling FastAPI sub-router."""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from .registry import get_loader
+
+router = APIRouter()
+
+
+class InvokeRequest(BaseModel):
+    name: str = Field(..., max_length=64)
+    params: Dict[str, Any] = Field(default_factory=dict)
+    priority: Optional[str] = Field(default=None, pattern="^(alpha|beta|manifest_order)$")
+
+
+@router.get("/list")
+def list_tools() -> dict:
+    return {"code": 0, "data": get_loader().list_tools()}
+
+
+@router.post("/invoke")
+def invoke(req: InvokeRequest) -> dict:
+    result = get_loader().call(req.name, req.params, priority=req.priority)
+    if not result.ok:
+        # 200 + ok=false or 502? Here we use 200; caller judges by ok field; beta network errors use 502
+        if result.track == "beta" and "Connection" in (result.error or ""):
+            raise HTTPException(status_code=502, detail=result.error)
+    return {
+        "code": 0 if result.ok else 1,
+        "msg": "success" if result.ok else result.error,
+        "data": {
+            "tool": result.tool,
+            "track": result.track,
+            "ok": result.ok,
+            "output": result.output,
+            "error": result.error,
+            "latency_ms": result.latency_ms,
+            "fallback_chain": result.fallback_chain,
+        },
+    }
+
+
+@router.post("/reload")
+def reload_registry() -> dict:
+    n = get_loader().reload()
+    return {"code": 0, "data": {"count": n}}