Use decoupled way for backend client

core/ports/backend.py

@@ -0,0 +1,84 @@
+"""Backend integration ports.
+
+These interfaces define the boundary between engine runtime logic and
+backend-side capabilities (config lookup, history persistence, retrieval,
+and tool resource discovery).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Protocol
+
+
+class AssistantConfigProvider(Protocol):
+    """Port for loading trusted assistant runtime configuration."""
+
+    async def fetch_assistant_config(self, assistant_id: str) -> Optional[Dict[str, Any]]:
+        """Fetch assistant configuration payload."""
+
+
+class HistoryWriter(Protocol):
+    """Port for persisting call and transcript history."""
+
+    async def create_call_record(
+        self,
+        *,
+        user_id: int,
+        assistant_id: Optional[str],
+        source: str = "debug",
+    ) -> Optional[str]:
+        """Create a call record and return backend call ID."""
+
+    async def add_transcript(
+        self,
+        *,
+        call_id: str,
+        turn_index: int,
+        speaker: str,
+        content: str,
+        start_ms: int,
+        end_ms: int,
+        confidence: Optional[float] = None,
+        duration_ms: Optional[int] = None,
+    ) -> bool:
+        """Append one transcript turn segment."""
+
+    async def finalize_call_record(
+        self,
+        *,
+        call_id: str,
+        status: str,
+        duration_seconds: int,
+    ) -> bool:
+        """Finalize a call record."""
+
+
+class KnowledgeSearcher(Protocol):
+    """Port for RAG / knowledge retrieval operations."""
+
+    async def search_knowledge_context(
+        self,
+        *,
+        kb_id: str,
+        query: str,
+        n_results: int = 5,
+    ) -> List[Dict[str, Any]]:
+        """Search a knowledge source and return ranked snippets."""
+
+
+class ToolResourceResolver(Protocol):
+    """Port for resolving tool metadata/configuration."""
+
+    async def fetch_tool_resource(self, tool_id: str) -> Optional[Dict[str, Any]]:
+        """Fetch tool resource configuration."""
+
+
+class BackendGateway(
+    AssistantConfigProvider,
+    HistoryWriter,
+    KnowledgeSearcher,
+    ToolResourceResolver,
+    Protocol,
+):
+    """Composite backend gateway interface used by engine services."""
+