alloy-runtime-cli 0.1.0__py3-none-any.whl

cli/tui/app.py

@@ -0,0 +1,199 @@
+"""Unified Alloy Runtime Terminal Application.
+
+This module provides the main Textual application that serves as the unified TUI
+for Alloy Runtime. It uses a screen-based architecture where each main view
+(Chat, Agents, Templates, Content, Schemas) is a proper Textual Screen.
+
+The app uses:
+- Screen stack for navigation between main views
+- AppStore for shared state following Textual's "App as Store" pattern
+- Priority bindings for global navigation that work regardless of focus
+"""
+
+from typing import Literal
+
+from textual.app import App
+
+from cli.tui.app_store import AppStore
+from cli.tui.chat.screen import ChatScreen
+from cli.tui.screens.agents import AgentsScreen
+from cli.tui.screens.content import ContentScreen
+from cli.tui.screens.dashboard import DashboardScreen
+from cli.tui.screens.schemas import SchemasScreen
+from cli.tui.screens.templates import TemplatesScreen
+from cli.tui.screens.tool_configs import ToolConfigsScreen
+from cli.tui.widgets.status_footer import StatusFooter
+from alloy_runtime_sdk.logging.config import get_logger
+
+logger = get_logger(__name__)
+
+SeverityLevel = Literal["information", "warning", "error"]
+
+
+class AlloyRuntimeApp(App[None]):
+    """Unified Alloy Runtime Terminal Application.
+
+    A full-featured TUI that provides:
+    - Screen-based navigation between major sections
+    - Consistent keyboard shortcuts across all views (c/a/t/s/m for switching)
+    - Integrated chat, browse, and create workflows
+    - Simple shared store accessible via self.app.store
+
+    Navigation:
+    - c: Chat screen
+    - a: Agents screen
+    - t: Templates screen
+    - m: Content (media) screen
+    - s: Schemas screen
+    - d: Dashboard overlay
+    - ?: Help modal
+
+    All screens inherit from NavScreen which provides these navigation bindings
+    as priority bindings, ensuring they work regardless of focus state.
+    """
+
+    CSS_PATH = [
+        "styles/app.tcss",
+        "styles/browser.tcss",
+        "styles/chat.tcss",
+        "styles/modals.tcss",
+        "styles/forms.tcss",
+        "styles/dashboard.tcss",
+    ]
+
+    # No bindings at app level - all bindings are on screens
+    # This avoids conflicts and ensures proper screen isolation
+    BINDINGS = []
+
+    # Register screens with the app
+    SCREENS = {
+        "chat": ChatScreen,
+        "agents": AgentsScreen,
+        "templates": TemplatesScreen,
+        "content": ContentScreen,
+        "schemas": SchemasScreen,
+        "tool_configs": ToolConfigsScreen,
+    }
+
+    theme: str = "tokyo-night"  # type: ignore[assignment]
+
+    def __init__(self, api_url: str, api_key: str):
+        """Initialize the Alloy Runtime app.
+
+        Args:
+            api_url: Base API URL for the server
+            api_key: API key for authentication
+        """
+        super().__init__()
+        # Create the simple store - screens access via self.app.store
+        self.store = AppStore(api_url=api_url, api_key=api_key)
+        # Track current screen for navigation
+        self._current_screen_id: str = "chat"
+        logger.info("tui_app_initialized", api_url=api_url)
+
+    def on_mount(self) -> None:
+        """Set up initial state on startup."""
+        logger.info("tui_app_mounted")
+        # Push the dashboard screen first, then the chat screen
+        # Dashboard will be shown as an overlay
+        self.push_screen("chat")
+        self.push_screen(DashboardScreen(), self._on_dashboard_dismiss)
+
+    def _on_dashboard_dismiss(self, screen_id: str | None) -> None:
+        """Handle dashboard dismissal by switching to the selected screen.
+
+        Args:
+            screen_id: The screen ID to navigate to (e.g., "chat", "agents"), or None if dismissed without selection
+        """
+        if screen_id is None:
+            return
+
+        # Extract just the screen name from tab-* format if needed
+        if screen_id.startswith("tab-"):
+            screen_id = screen_id[4:]  # Remove "tab-" prefix
+
+        logger.info("dashboard_dismissed", target_screen=screen_id)
+        self.switch_to_screen(screen_id)
+
+    def switch_to_screen(self, screen_id: str) -> None:
+        """Switch to a different screen.
+
+        This method handles screen switching by:
+        1. Popping the current screen
+        2. Pushing the new screen
+
+        Args:
+            screen_id: The ID of the screen to switch to (chat, agents, templates, content, schemas)
+        """
+        if screen_id == self._current_screen_id:
+            return  # Already on this screen
+
+        if screen_id not in self.SCREENS:
+            logger.warning("unknown_screen_id", screen_id=screen_id)
+            return
+
+        logger.info(
+            "switching_screen", from_screen=self._current_screen_id, to_screen=screen_id
+        )
+
+        # Use switch_screen for clean transitions
+        self._current_screen_id = screen_id
+        self.switch_screen(screen_id)  # pyright: ignore[reportUnknownMemberType]
+
+    def notify(
+        self,
+        message: str,
+        *,
+        title: str = "",
+        severity: SeverityLevel = "information",
+        timeout: float | None = None,
+        markup: bool = True,
+    ) -> None:
+        """Show a notification in the status footer instead of a toast.
+
+        This overrides the default App.notify() to route notifications
+        to our vim-style StatusFooter widget if available.
+
+        Args:
+            message: The notification message
+            title: Optional title (ignored for status bar)
+            severity: One of "information", "warning", "error"
+            timeout: Seconds before clearing (default varies by severity)
+            markup: Whether message contains markup (ignored for status bar)
+        """
+        # Errors get longer display time (6s) so users can read them
+        if timeout is not None:
+            effective_timeout = timeout
+        elif severity == "error":
+            effective_timeout = 6.0
+        else:
+            effective_timeout = 2.0
+        try:
+            footer = self.screen.query_one(StatusFooter)
+            footer.show_notification(
+                message, severity=severity, timeout=effective_timeout
+            )
+        except Exception:
+            # Fall back to parent if footer not found
+            super().notify(
+                message, title=title, severity=severity, timeout=timeout, markup=markup
+            )
+
+    async def on_unmount(self) -> None:
+        """Clean up on app exit."""
+        logger.info("tui_app_shutting_down")
+        await self.store.close()
+        logger.info("tui_app_shutdown_complete")
+
+
+def run_app(api_url: str, api_key: str) -> None:
+    """Run the Alloy Runtime Terminal app.
+
+    Args:
+        api_url: Base API URL for the server
+        api_key: API key for authentication
+    """
+    logger.info("tui_app_starting", api_url=api_url)
+    app = AlloyRuntimeApp(api_url=api_url, api_key=api_key)
+    app.run()
+    logger.info("tui_app_exited")

cli/tui/app_store.py

@@ -0,0 +1,73 @@
+"""Simple application store for shared state.
+
+This module provides a minimal store that holds:
+- API credentials (read-only config)
+- Shared ApiClient instance (lazy initialization)
+- Agent cache for cross-screen sharing
+
+This replaces the previous ELM-style architecture with Textual's
+recommended "App as Store" pattern - simple and direct.
+"""
+
+from alloy_runtime_sdk.api_client.client import ApiClient
+from alloy_runtime_types.dtos.agents import AgentSummary
+
+
+class AppStore:
+    """Simple app-wide store for shared state.
+
+    Usage:
+        store = AppStore(api_url="...", api_key="...")
+        client = await store.get_client()
+
+    Screens access via self.app.store (Textual's recommended pattern).
+    """
+
+    def __init__(self, api_url: str, api_key: str) -> None:
+        """Initialize the store.
+
+        Args:
+            api_url: Base URL for the API server
+            api_key: API key for authentication
+        """
+        self.api_url = api_url.rstrip("/")
+        self.api_key = api_key
+        self._client: ApiClient | None = None
+        self._client_entered: bool = False
+
+        # Cross-screen cache for agent picker in chat
+        self.agent_cache: list[AgentSummary] = []
+
+    async def get_client(self) -> ApiClient:
+        """Get the shared server client instance.
+
+        Creates and connects on first use, reuses thereafter.
+
+        Returns:
+            Connected ApiClient instance
+
+        Raises:
+            Exception: If connection fails
+        """
+        if self._client is None:
+            self._client = ApiClient(
+                base_url=self.api_url,
+                api_key=self.api_key,
+                timeout=30.0,
+            )
+
+        if not self._client_entered:
+            await self._client.__aenter__()
+            self._client_entered = True
+
+        return self._client
+
+    async def close(self) -> None:
+        """Close the client connection.
+
+        Should be called when the application exits.
+        """
+        if self._client and self._client_entered:
+            await self._client.__aexit__(None, None, None)
+            self._client_entered = False
+            self._client = None

cli/tui/chat/commands/base.py

@@ -0,0 +1,65 @@
+"""Base command protocol and utilities for chat commands.
+
+Commands encapsulate async operations, making them:
+- Testable in isolation with mocked dependencies
+- Reusable across different contexts (UI, CLI, scripts)
+- Single-responsibility focused
+"""
+
+from dataclasses import dataclass
+from typing import Generic, Protocol, TypeVar
+
+T = TypeVar("T")
+U = TypeVar("U")
+
+
+class Command(Protocol[T]):
+    """Protocol for chat commands.
+
+    Commands are dataclasses that encapsulate all dependencies needed
+    to execute an async operation. They return a CommandResult with
+    the outcome.
+
+    Example:
+        @dataclass
+        class SendMessageCommand:
+            client: ApiClient
+            store: ChatStore
+            session_id: UUID
+            message: str
+
+            async def execute(self) -> CommandResult[str]:
+                # ... implementation
+    """
+
+    async def execute(self) -> "CommandResult[T]":
+        """Execute the command and return result."""
+        ...
+
+
+@dataclass(frozen=True)
+class CommandResult(Generic[T]):
+    """Result wrapper for command execution.
+
+    Provides a consistent way to handle success/failure without exceptions
+    bubbling up to the UI layer.
+
+    Attributes:
+        success: Whether the command succeeded.
+        data: The result data if successful.
+        error: Error message if failed.
+    """
+
+    success: bool
+    data: T | None = None
+    error: str | None = None
+
+    @classmethod
+    def ok(cls: type["CommandResult[U]"], data: U) -> "CommandResult[U]":
+        """Create a successful result."""
+        return cls(success=True, data=data)
+
+    @classmethod
+    def fail(cls: type["CommandResult[U]"], error: str) -> "CommandResult[U]":
+        """Create a failed result."""
+        return cls(success=False, error=error)

cli/tui/chat/commands/create_session.py

@@ -0,0 +1,135 @@
+"""Command for creating a new chat session."""
+
+from dataclasses import dataclass
+from uuid import UUID
+
+from alloy_runtime_sdk.api_client.client import ApiClient
+from alloy_runtime_types.dtos.sessions import CreateSessionRequest
+from alloy_runtime_sdk.logging.config import get_logger
+
+from cli.tui.chat.commands.base import CommandResult
+from cli.tui.chat.store import ChatStore
+from cli.tui.chat.types import ChatPhase
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class CreateSessionResult:
+    """Result data for create session operation.
+
+    Supports both agent mode and direct model mode.
+
+    Attributes:
+        session_id: ID of the newly created session.
+        session_name: Name of the session.
+        agent_id: ID of the agent (agent mode).
+        agent_name: Name of the agent (agent mode).
+        provider_key: Provider key (model mode).
+        provider_model_name: Model name (model mode).
+        system_instruction: System instruction (model mode).
+    """
+
+    session_id: UUID
+    session_name: str | None
+    # Agent mode
+    agent_id: UUID | None = None
+    agent_name: str | None = None
+    # Model mode
+    provider_key: str | None = None
+    provider_model_name: str | None = None
+    system_instruction: str | None = None
+
+
+@dataclass
+class CreateSessionCommand:
+    """Command to create a new chat session.
+
+    Supports two modes:
+    - Agent mode: Uses agent_id/agent_name
+    - Model mode: Uses provider_key/provider_model_name/system_instruction
+
+    This command:
+    1. Transitions store to CREATING_SESSION phase
+    2. Sends create request to the API
+    3. Updates store with new session context
+    4. Clears any existing messages
+    5. Transitions back to IDLE
+
+    Attributes:
+        client: Server client for API calls.
+        store: Chat store for state management.
+        name: Optional name for the session.
+        agent_id: ID of the agent to use (agent mode).
+        agent_name: Name of the agent (agent mode).
+        provider_key: Provider key (model mode).
+        provider_model_name: Model name (model mode).
+        system_instruction: System instruction (model mode).
+    """
+
+    client: ApiClient
+    store: ChatStore
+    name: str | None
+    # Agent mode
+    agent_id: UUID | None = None
+    agent_name: str | None = None
+    # Model mode
+    provider_key: str | None = None
+    provider_model_name: str | None = None
+    system_instruction: str | None = None
+
+    async def execute(self) -> CommandResult[CreateSessionResult]:
+        """Execute the create session operation.
+
+        Returns:
+            CommandResult with new session data on success.
+        """
+        logger.info(
+            "create_session_starting",
+            agent_id=str(self.agent_id) if self.agent_id else None,
+            agent_name=self.agent_name,
+            model=self.provider_model_name,
+        )
+        self.store.set_phase(ChatPhase.CREATING_SESSION)
+
+        try:
+            # Create session request - agent is optional
+            # For model mode, we don't associate an agent with the session
+            request = CreateSessionRequest(
+                name=self.name,
+                agent=str(self.agent_id) if self.agent_id else None,
+            )
+            session = await self.client.create_session(request)
+
+            # Update store with new session
+            self.store.set_session(
+                session_id=session.id,
+                session_name=self.name,
+                agent_id=self.agent_id,
+                agent_name=self.agent_name,
+                message_count=0,
+                provider_key=self.provider_key,
+                model_name=self.provider_model_name,
+                system_instruction=self.system_instruction,
+            )
+            self.store.set_messages([])
+            self.store.set_phase(ChatPhase.IDLE)
+
+            logger.info("create_session_completed", session_id=str(session.id))
+            return CommandResult[CreateSessionResult](
+                success=True,
+                data=CreateSessionResult(
+                    session_id=session.id,
+                    session_name=self.name,
+                    agent_id=self.agent_id,
+                    agent_name=self.agent_name,
+                    provider_key=self.provider_key,
+                    provider_model_name=self.provider_model_name,
+                    system_instruction=self.system_instruction,
+                ),
+            )
+
+        except Exception as e:
+            logger.warning("create_session_failed", error=str(e))
+            self.store.set_phase(ChatPhase.IDLE)
+            return CommandResult[CreateSessionResult](success=False, error=str(e))

cli/tui/chat/commands/load_session.py

@@ -0,0 +1,119 @@
+"""Command for loading a chat session and its messages."""
+
+from dataclasses import dataclass
+from uuid import UUID
+
+from alloy_runtime_sdk.api_client.client import ApiClient
+from alloy_runtime_types.dtos.sessions import MessageResponse
+from alloy_runtime_sdk.logging.config import get_logger
+
+from cli.tui.chat.commands.base import CommandResult
+from cli.tui.chat.store import ChatStore
+from cli.tui.chat.types import ChatPhase
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class LoadSessionResult:
+    """Result data for load session operation.
+
+    Attributes:
+        session_id: ID of the loaded session.
+        session_name: Name of the session.
+        agent_id: ID of the agent (extracted from messages).
+        agent_name: Name of the agent (if available).
+        messages: List of messages in the session.
+        total_messages: Total message count.
+    """
+
+    session_id: UUID
+    session_name: str | None
+    agent_id: UUID | None
+    agent_name: str | None
+    messages: list[MessageResponse]
+    total_messages: int
+
+
+@dataclass
+class LoadSessionCommand:
+    """Command to load a chat session and its messages.
+
+    This command:
+    1. Transitions store to LOADING_SESSION phase
+    2. Fetches session data from the API
+    3. Extracts agent info from messages
+    4. Updates store with session context and messages
+    5. Transitions back to IDLE
+
+    Attributes:
+        client: Server client for API calls.
+        store: Chat store for state management.
+        session_id: ID of the session to load.
+        message_limit: Maximum number of messages to fetch.
+    """
+
+    client: ApiClient
+    store: ChatStore
+    session_id: UUID
+    message_limit: int = 100
+
+    async def execute(self) -> CommandResult[LoadSessionResult]:
+        """Execute the load session operation.
+
+        Returns:
+            CommandResult with session data on success.
+        """
+        logger.info("load_session_starting", session_id=str(self.session_id))
+        self.store.set_phase(ChatPhase.LOADING_SESSION)
+
+        try:
+            session = await self.client.get_session(
+                self.session_id, limit=self.message_limit
+            )
+
+            # Extract agent info from messages
+            agent_id = None
+            agent_name = None
+            for msg in reversed(session.messages):
+                if msg.role == "assistant" and msg.agent_execution:
+                    exec_meta = msg.agent_execution
+                    if exec_meta.agent_id:
+                        agent_id = exec_meta.agent_id
+                    break
+
+            # Update store with session data
+            self.store.set_session(
+                session_id=self.session_id,
+                session_name=session.name,
+                agent_id=agent_id,
+                agent_name=agent_name,
+                message_count=session.total_messages,
+            )
+            self.store.set_messages(list(session.messages))
+            self.store.set_phase(ChatPhase.IDLE)
+
+            logger.info(
+                "load_session_completed",
+                session_id=str(self.session_id),
+                session_name=session.name,
+                message_count=len(session.messages),
+            )
+            return CommandResult[LoadSessionResult](
+                success=True,
+                data=LoadSessionResult(
+                    session_id=self.session_id,
+                    session_name=session.name,
+                    agent_id=agent_id,
+                    agent_name=agent_name,
+                    messages=list(session.messages),
+                    total_messages=session.total_messages,
+                ),
+            )
+
+        except Exception as e:
+            logger.warning(
+                "load_session_failed", session_id=str(self.session_id), error=str(e)
+            )
+            self.store.set_phase(ChatPhase.IDLE)
+            return CommandResult[LoadSessionResult](success=False, error=str(e))