85 lines
2.1 KiB
Python
85 lines
2.1 KiB
Python
"""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."""
|
|
|