atlas-chat 0.1.0__py3-none-any.whl

atlas/interfaces/events.py

@@ -0,0 +1,134 @@
+"""Event publisher interface for transport-agnostic UI updates."""
+
+from typing import Any, Dict, Protocol
+
+
+class EventPublisher(Protocol):
+    """
+    Protocol for publishing events to UI/clients.
+
+    Provides transport-agnostic interface for sending various update types
+    to connected clients (e.g., via WebSocket, SSE, HTTP streaming, etc.).
+
+    This interface lives in the interfaces layer to avoid circular dependencies
+    and keep the application layer decoupled from atlas.infrastructure concerns.
+    """
+
+    async def publish_chat_response(
+        self,
+        message: str,
+        has_pending_tools: bool = False,
+    ) -> None:
+        """
+        Publish a chat response message.
+
+        Args:
+            message: Response text from assistant
+            has_pending_tools: Whether tools are still executing
+        """
+        pass
+
+    async def publish_response_complete(self) -> None:
+        """Signal that the response is complete."""
+        pass
+
+    async def publish_agent_update(
+        self,
+        update_type: str,
+        **kwargs: Any
+    ) -> None:
+        """
+        Publish an agent-specific update.
+
+        Args:
+            update_type: Type of agent update (agent_start, agent_turn_start, etc.)
+            **kwargs: Additional data specific to the update type
+        """
+        pass
+
+    async def publish_tool_start(
+        self,
+        tool_name: str,
+        **kwargs: Any
+    ) -> None:
+        """
+        Publish notification that a tool is starting.
+
+        Args:
+            tool_name: Name of the tool being executed
+            **kwargs: Additional tool execution metadata
+        """
+        pass
+
+    async def publish_tool_complete(
+        self,
+        tool_name: str,
+        result: Any,
+        **kwargs: Any
+    ) -> None:
+        """
+        Publish notification that a tool has completed.
+
+        Args:
+            tool_name: Name of the tool that completed
+            result: Tool execution result
+            **kwargs: Additional tool execution metadata
+        """
+        pass
+
+    async def publish_files_update(
+        self,
+        files: Dict[str, Any]
+    ) -> None:
+        """
+        Publish update about session files.
+
+        Args:
+            files: Dictionary of file information
+        """
+        pass
+
+    async def publish_canvas_content(
+        self,
+        content: str,
+        content_type: str = "text/html",
+        **kwargs: Any
+    ) -> None:
+        """
+        Publish content for canvas display.
+
+        Args:
+            content: Content to display in canvas
+            content_type: MIME type of content
+            **kwargs: Additional canvas metadata
+        """
+        pass
+
+    async def send_json(self, data: Dict[str, Any]) -> None:
+        """
+        Send raw JSON message.
+
+        Args:
+            data: Dictionary to send as JSON
+        """
+        pass
+
+    async def publish_elicitation_request(
+        self,
+        elicitation_id: str,
+        tool_call_id: str,
+        tool_name: str,
+        message: str,
+        response_schema: Dict[str, Any]
+    ) -> None:
+        """
+        Publish an elicitation request to the user.
+
+        Args:
+            elicitation_id: Unique identifier for this elicitation
+            tool_call_id: ID of the tool call that requested elicitation
+            tool_name: Name of the tool requesting input
+            message: Prompt message to display to the user
+            response_schema: JSON schema defining expected response structure
+        """
+        pass

atlas/interfaces/llm.py

@@ -0,0 +1,54 @@
+"""LLM interface protocols."""
+
+from typing import Dict, List, Protocol, runtime_checkable
+
+from atlas.modules.llm.models import LLMResponse as LLMResponse
+
+
+@runtime_checkable
+class LLMProtocol(Protocol):
+    """Protocol for LLM interactions."""
+
+    async def call_plain(
+        self,
+        model_name: str,
+        messages: List[Dict[str, str]],
+        temperature: float = 0.7,
+    ) -> str:
+        """Plain LLM call without tools or RAG."""
+        ...
+
+    async def call_with_tools(
+        self,
+        model_name: str,
+        messages: List[Dict[str, str]],
+        tools_schema: List[Dict],
+        tool_choice: str = "auto",
+        temperature: float = 0.7,
+    ) -> LLMResponse:
+        """LLM call with tool support."""
+        ...
+
+    async def call_with_rag(
+        self,
+        model_name: str,
+        messages: List[Dict[str, str]],
+        data_sources: List[str],
+        user_email: str,
+        temperature: float = 0.7,
+    ) -> str:
+        """LLM call with RAG integration."""
+        ...
+
+    async def call_with_rag_and_tools(
+        self,
+        model_name: str,
+        messages: List[Dict[str, str]],
+        data_sources: List[str],
+        tools_schema: List[Dict],
+        user_email: str,
+        tool_choice: str = "auto",
+        temperature: float = 0.7,
+    ) -> LLMResponse:
+        """LLM call with both RAG and tools."""
+        ...

atlas/interfaces/rag.py

@@ -0,0 +1,40 @@
+"""RAG interface protocols."""
+
+from typing import Dict, List, Protocol, runtime_checkable
+
+from atlas.modules.rag.client import DataSource, RAGResponse
+
+
+@runtime_checkable
+class RAGClientProtocol(Protocol):
+    """Protocol for RAG client implementations.
+
+    Defines the interface that all RAG clients must implement,
+    enabling dependency injection and easier testing.
+    """
+
+    async def discover_data_sources(self, user_name: str) -> List[DataSource]:
+        """Discover data sources accessible by a user.
+
+        Args:
+            user_name: The username to discover data sources for.
+
+        Returns:
+            List of DataSource objects the user can access.
+        """
+        pass
+
+    async def query_rag(
+        self, user_name: str, data_source: str, messages: List[Dict]
+    ) -> RAGResponse:
+        """Query RAG endpoint for a response with metadata.
+
+        Args:
+            user_name: The username making the query.
+            data_source: The data source to query.
+            messages: List of message dictionaries with role and content.
+
+        Returns:
+            RAGResponse containing content and optional metadata.
+        """
+        pass

atlas/interfaces/sessions.py

@@ -0,0 +1,75 @@
+"""Session repository interface."""
+
+from typing import Optional, Protocol
+from uuid import UUID
+
+from atlas.domain.sessions.models import Session
+
+
+class SessionRepository(Protocol):
+    """
+    Port for session storage and retrieval.
+
+    Abstracts session persistence from the application layer,
+    allowing different storage implementations (in-memory, Redis, DB, etc.).
+    """
+
+    async def get(self, session_id: UUID) -> Optional[Session]:
+        """
+        Retrieve a session by ID.
+
+        Args:
+            session_id: Unique session identifier
+
+        Returns:
+            Session if found, None otherwise
+        """
+        pass
+
+    async def create(self, session: Session) -> Session:
+        """
+        Create and store a new session.
+
+        Args:
+            session: Session to create
+
+        Returns:
+            Created session
+        """
+        pass
+
+    async def update(self, session: Session) -> Session:
+        """
+        Update an existing session.
+
+        Args:
+            session: Session to update
+
+        Returns:
+            Updated session
+        """
+        pass
+
+    async def delete(self, session_id: UUID) -> bool:
+        """
+        Delete a session.
+
+        Args:
+            session_id: ID of session to delete
+
+        Returns:
+            True if deleted, False if not found
+        """
+        pass
+
+    async def exists(self, session_id: UUID) -> bool:
+        """
+        Check if a session exists.
+
+        Args:
+            session_id: Session ID to check
+
+        Returns:
+            True if session exists, False otherwise
+        """
+        pass

atlas/interfaces/tools.py

@@ -0,0 +1,57 @@
+"""Tools interface protocols."""
+
+from typing import Any, Dict, List, Optional, Protocol, runtime_checkable
+
+from atlas.domain.messages.models import ToolCall, ToolResult
+
+
+@runtime_checkable
+class ToolProtocol(Protocol):
+    """Protocol for individual tools."""
+
+    @property
+    def name(self) -> str:
+        """Tool name."""
+        ...
+
+    @property
+    def description(self) -> str:
+        """Tool description."""
+        ...
+
+    def get_schema(self) -> Dict[str, Any]:
+        """Get tool schema for LLM."""
+        ...
+
+    async def execute(self, arguments: Dict[str, Any]) -> ToolResult:
+        """Execute the tool with given arguments."""
+        ...
+
+
+@runtime_checkable
+class ToolManagerProtocol(Protocol):
+    """Protocol for tool management."""
+
+    def get_available_tools(self) -> List[str]:
+        """Get list of available tool names."""
+        ...
+
+    def get_tools_schema(self, tool_names: List[str]) -> List[Dict[str, Any]]:
+        """Get schemas for specified tools."""
+        ...
+
+    async def execute_tool(
+        self,
+        tool_call: ToolCall,
+        context: Optional[Dict[str, Any]] = None
+    ) -> ToolResult:
+        """Execute a tool call."""
+        ...
+
+    async def execute_tool_calls(
+        self,
+        tool_calls: List[ToolCall],
+        context: Optional[Dict[str, Any]] = None
+    ) -> List[ToolResult]:
+        """Execute multiple tool calls."""
+        ...

atlas/interfaces/transport.py

@@ -0,0 +1,24 @@
+"""Transport interface protocols."""
+
+from typing import Any, Dict, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ChatConnectionProtocol(Protocol):
+    """Protocol for chat connections (WebSocket abstraction)."""
+
+    async def send_json(self, data: Dict[str, Any]) -> None:
+        """Send JSON data to the client."""
+        ...
+
+    async def receive_json(self) -> Dict[str, Any]:
+        """Receive JSON data from the client."""
+        ...
+
+    async def accept(self) -> None:
+        """Accept the connection."""
+        ...
+
+    async def close(self) -> None:
+        """Close the connection."""
+        ...