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

cli/commands/shared_flags.py

@@ -0,0 +1,500 @@
+"""Shared CLI flag definitions for consistent flag naming across commands.
+
+This module provides reusable typer.Option instances that can be imported
+and used directly in command function signatures. This ensures:
+- Consistent short/long flag names across all commands
+- Consistent help text
+- No code duplication for common flag patterns
+
+Usage:
+    from cli.commands.shared_flags import SEARCH, LIMIT, TAGS
+
+    def my_command(
+        search: str | None = SEARCH,
+        limit: int = LIMIT,
+        tags: str | None = TAGS,
+    ) -> None:
+        ...
+
+Short Flag Convention:
+    -a  --agent          Agent name/UUID
+    -c  --content        Inline content
+    -d  --description    Description field
+    -e  --export         Export format
+    -f  --file           Input file path
+    -g  --group-by       Group results by field
+    -l  --limit          Result limit
+    -m  --message        User message
+    -n  --name           Name field
+    -o  --output         Output mode (console/clipboard/file)
+    -O  --output-file    Output file path (capital O)
+    -p  --provider       Provider key
+    -M  --model          Model name (capital M, avoids -m message conflict)
+    -s  --search         Search query
+    -t  --tags           Tags (comma-separated)
+    -T  --temperature    Temperature parameter (capital T)
+    -v  --var            Template variable
+    -V  --visibility     Visibility level (capital V)
+    -w  --where          Filter condition
+    -x  --exclude        Exclude pattern
+    -y  --yes            Skip confirmation (replaces --force)
+"""
+
+from typing import Annotated, Optional
+
+import typer
+
+# =============================================================================
+# PAGINATION FLAGS
+# =============================================================================
+
+LIMIT = typer.Option(
+    50,
+    "-l",
+    "--limit",
+    min=1,
+    max=100,
+    help="Max results to return",
+)
+
+OFFSET = typer.Option(
+    0,
+    "--offset",
+    min=0,
+    help="Skip N results",
+)
+
+CURSOR = typer.Option(
+    None,
+    "--cursor",
+    help="Pagination cursor from previous response",
+)
+
+
+# =============================================================================
+# SEARCH FLAGS
+# =============================================================================
+
+SEARCH = typer.Option(
+    None,
+    "-s",
+    "--search",
+    help="Fuzzy search terms",
+)
+
+
+# =============================================================================
+# OUTPUT FLAGS
+# =============================================================================
+
+OUTPUT_MODE = typer.Option(
+    "console",
+    "-o",
+    "--output",
+    help="Output: console, clipboard, or file",
+)
+
+OUTPUT_FILE = typer.Option(
+    None,
+    "-O",
+    "--output-file",
+    help="Output file path (for --output file)",
+)
+
+
+# =============================================================================
+# CONTENT INPUT FLAGS
+# =============================================================================
+
+FILE_INPUT = typer.Option(
+    None,
+    "-f",
+    "--file",
+    help="Read content from file",
+    exists=True,
+    readable=True,
+)
+
+CONTENT_INLINE = typer.Option(
+    None,
+    "-c",
+    "--content",
+    help="Inline content (or @file to read from file)",
+)
+
+
+# =============================================================================
+# COMMON ENTITY FLAGS
+# =============================================================================
+
+NAME = typer.Option(
+    ...,
+    "-n",
+    "--name",
+    help="Name",
+)
+
+NAME_OPTIONAL = typer.Option(
+    None,
+    "-n",
+    "--name",
+    help="Name",
+)
+
+DESCRIPTION = typer.Option(
+    None,
+    "-d",
+    "--description",
+    help="Description",
+)
+
+TAGS = typer.Option(
+    None,
+    "-t",
+    "--tags",
+    help="Comma-separated tags",
+)
+
+TAGS_REQUIRED = typer.Option(
+    ...,
+    "-t",
+    "--tags",
+    help="Comma-separated tags",
+)
+
+TAGS_LIST = Annotated[
+    Optional[list[str]],
+    typer.Option(
+        "-t",
+        "--tag",
+        help="Tag to include (repeatable)",
+    ),
+]
+
+EXCLUDE_TAGS = Annotated[
+    Optional[list[str]],
+    typer.Option(
+        "-x",
+        "--exclude",
+        help="Tag pattern to exclude (repeatable)",
+    ),
+]
+
+
+# =============================================================================
+# CONFIRMATION FLAGS
+# =============================================================================
+
+YES = typer.Option(
+    False,
+    "-y",
+    "--yes",
+    help="Skip confirmation prompt",
+)
+
+# =============================================================================
+# MODEL SELECTION FLAGS
+# =============================================================================
+
+AGENT = typer.Option(
+    None,
+    "-a",
+    "--agent",
+    help="Agent name or UUID",
+)
+
+AGENT_REQUIRED = typer.Option(
+    ...,
+    "-a",
+    "--agent",
+    help="Agent name or UUID",
+)
+
+PROVIDER = typer.Option(
+    None,
+    "-p",
+    "--provider",
+    help="Provider key (anthropic, openai, etc.)",
+)
+
+PROVIDER_REQUIRED = typer.Option(
+    ...,
+    "-p",
+    "--provider",
+    help="Provider key (anthropic, openai, etc.)",
+)
+
+MODEL = typer.Option(
+    None,
+    "-M",
+    "--model",
+    help="Model name",
+)
+
+MODEL_REQUIRED = typer.Option(
+    ...,
+    "-M",
+    "--model",
+    help="Model name",
+)
+
+
+# =============================================================================
+# GENERATION PARAMETER FLAGS
+# =============================================================================
+
+TEMPERATURE = typer.Option(
+    None,
+    "-T",
+    "--temperature",
+    help="Temperature (0.0-2.0)",
+)
+
+MAX_TOKENS = typer.Option(
+    None,
+    "--max-tokens",
+    help="Max tokens to generate",
+)
+
+REASONING_EFFORT = typer.Option(
+    None,
+    "--reasoning-effort",
+    help="Reasoning: none|minimal|low|medium|high",
+)
+
+
+# =============================================================================
+# MESSAGE FLAGS
+# =============================================================================
+
+MESSAGE = typer.Option(
+    None,
+    "-m",
+    "--message",
+    help="User message (or @file)",
+)
+
+MESSAGE_REQUIRED = typer.Option(
+    ...,
+    "-m",
+    "--message",
+    help="User message (or @file)",
+)
+
+SYSTEM_INSTRUCTION = typer.Option(
+    None,
+    "--system",
+    help="System instruction (or @file)",
+)
+
+
+# =============================================================================
+# TEMPLATE FLAGS
+# =============================================================================
+
+TEMPLATE_VAR = Annotated[
+    Optional[list[str]],
+    typer.Option(
+        "-v",
+        "--var",
+        help="Variable (key=value or key:=json). Repeatable.",
+    ),
+]
+
+VISIBILITY = typer.Option(
+    None,
+    "-V",
+    "--visibility",
+    help="Visibility: private, organization, public",
+)
+
+VISIBILITY_REQUIRED = typer.Option(
+    ...,
+    "-V",
+    "--visibility",
+    help="Visibility: private, organization, public",
+)
+
+CONTENT_TYPE = typer.Option(
+    None,
+    "--type",
+    help="Content type",
+)
+
+CONTENT_TYPE_REQUIRED = typer.Option(
+    ...,
+    "--type",
+    help="Content type",
+)
+
+
+# =============================================================================
+# SCOPE FLAGS
+# =============================================================================
+
+SCOPE = typer.Option(
+    None,
+    "--scope",
+    help="Scope: user, organization, global",
+)
+
+
+# =============================================================================
+# EXPORT FLAGS
+# =============================================================================
+
+EXPORT_FORMAT = typer.Option(
+    None,
+    "-e",
+    "--export",
+    help="Export format: markdown, xml, json, plain",
+)
+
+GROUP_BY = typer.Option(
+    None,
+    "-g",
+    "--group-by",
+    help="Group results by field",
+)
+
+
+# =============================================================================
+# FILTER FLAGS
+# =============================================================================
+
+WHERE = Annotated[
+    Optional[list[str]],
+    typer.Option(
+        "-w",
+        "--where",
+        help="Filter: field=value, field>=num. Repeatable.",
+    ),
+]
+
+
+# =============================================================================
+# SESSION FLAGS
+# =============================================================================
+
+SESSION_ID = typer.Option(
+    None,
+    "--session",
+    help="Session ID to resume",
+)
+
+SESSION_NAME = typer.Option(
+    None,
+    "-n",
+    "--name",
+    help="Name for new session",
+)
+
+
+# =============================================================================
+# SCHEMA FLAGS
+# =============================================================================
+
+SCHEMA_REF = typer.Option(
+    None,
+    "--schema",
+    help="Schema name or UUID",
+)
+
+SCHEMA_FORMAT = typer.Option(
+    None,
+    "--schema-format",
+    help="Schema format: json_schema, regex",
+)
+
+SCHEMA_DEF = typer.Option(
+    None,
+    "--schema-def",
+    help="Schema definition (or @file)",
+)
+
+
+# =============================================================================
+# CLEAR FLAGS (for update commands)
+# =============================================================================
+
+CLEAR_DESCRIPTION = typer.Option(
+    False,
+    "--clear-description",
+    help="Clear the description",
+)
+
+CLEAR_TAGS = typer.Option(
+    False,
+    "--clear-tags",
+    help="Remove all tags",
+)
+
+
+# =============================================================================
+# DISPLAY FLAGS
+# =============================================================================
+
+FULL_OUTPUT = typer.Option(
+    False,
+    "--full",
+    help="Show full content (no truncation)",
+)
+
+COPY_TO_CLIPBOARD = typer.Option(
+    False,
+    "--copy",
+    help="Copy to clipboard",
+)
+
+STREAM = typer.Option(
+    True,
+    "--stream/--no-stream",
+    help="Stream output",
+)
+
+SHOW_THINKING = typer.Option(
+    True,
+    "--thinking/--no-thinking",
+    help="Show thinking blocks",
+)
+
+
+# =============================================================================
+# CREDENTIAL FLAGS
+# =============================================================================
+
+CREDENTIAL_VALUE = typer.Option(
+    ...,
+    "--value",
+    help="API key value (will be encrypted)",
+)
+
+CREDENTIAL_VALUE_OPTIONAL = typer.Option(
+    None,
+    "--value",
+    help="API key value (will be encrypted)",
+)
+
+
+# =============================================================================
+# COUNT/CONCURRENT FLAGS
+# =============================================================================
+
+COUNT = typer.Option(
+    1,
+    "--count",
+    min=1,
+    max=10,
+    help="Number of concurrent executions",
+)
+
+
+# =============================================================================
+# UPSERT FLAG
+# =============================================================================
+
+UPSERT = typer.Option(
+    False,
+    "--upsert",
+    help="Return existing if name already exists",
+)

cli/commands/sync/command.py

@@ -0,0 +1,45 @@
+"""Sync command implementation - simplified."""
+
+from cli.commands.sync.presenter import present_sync_models_success
+from cli.infrastructure.command import async_command, authenticated_client
+from cli.infrastructure.console import get_console
+
+
+def sync_command() -> None:
+    """Sync AI models from provider sources.
+
+    Requires system admin privileges. This command pulls the latest model
+    information from configured AI providers and updates the local database.
+
+    The sync process:
+    1. Fetches models from Models.dev API
+    2. Fetches models from OpenRouter API
+    3. Upserts providers and provider models to database
+    4. Uses exact provider model names (no canonical name mapping)
+
+    Example:
+        ai2 sync models
+
+    Note:
+        This is an admin-only operation that requires appropriate credentials.
+    """
+    _execute_sync()
+
+
+@async_command
+async def _execute_sync() -> None:
+    """Execute sync operation.
+
+    Raises:
+        ConfigurationError: If environment variables are missing
+        AuthenticationError: If API key is invalid
+        ForbiddenError: If user lacks admin privileges
+        ServerError: If server returns 5xx error
+    """
+    console = get_console()
+    console.print("[bold blue]Fetching models from providers...[/]")
+
+    async with authenticated_client() as (_config, client):
+        response = await client.sync_models()
+
+    present_sync_models_success(response)

cli/commands/sync/presenter.py

@@ -0,0 +1,49 @@
+"""Presenter for sync command output."""
+
+from rich.table import Table
+from alloy_runtime_types.dtos.admin import SyncModelsResponse
+
+from cli.infrastructure.console import get_console
+from cli.infrastructure.output import print_success
+
+
+def present_sync_models_success(response: SyncModelsResponse) -> None:
+    """Present successful model sync results with Rich formatting.
+
+    Args:
+        response: Sync results from server
+    """
+    console = get_console()
+
+    # Print success message with summary
+    print_success(
+        f"Synced {response.total_models_synced} models from {response.total_providers_synced} providers"
+    )
+
+    # Create table for per-source breakdown
+    if response.by_source:
+        table = Table(
+            title="Sync Results by Source",
+            show_header=True,
+            header_style="bold magenta",
+        )
+        table.add_column("Source", style="cyan", no_wrap=True)
+        table.add_column("Models", style="white", justify="right")
+        table.add_column("Providers", style="white", justify="right")
+        table.add_column("Status", style="white")
+
+        # Add rows for each source
+        for source_name, result in response.by_source.items():
+            if result.error:
+                status = f"[red]✗ {result.error}[/red]"
+            else:
+                status = "[green]✓ Success[/green]"
+
+            table.add_row(
+                source_name,
+                str(result.models_synced),
+                str(result.providers_synced),
+                status,
+            )
+
+        console.print(table)

cli/commands/tags/__init__.py

@@ -0,0 +1 @@
+# Empty per project convention - import directly from submodules

cli/commands/tags/create/__init__.py

@@ -0,0 +1 @@
+# Empty per project convention - import directly from submodules

cli/commands/tags/create/command.py

@@ -0,0 +1,60 @@
+"""Tag create command implementation."""
+
+from typing import Optional
+
+import typer
+
+from cli.infrastructure.command import async_command, authenticated_client
+from cli.infrastructure.output import OutputService
+
+from alloy_runtime_types.dtos.tags import CreateTagRequest
+
+
+def tags_create_command(
+    tag_path: str = typer.Argument(
+        ...,
+        help="Hierarchical tag path (e.g., 'marketing.email.weekly')",
+    ),
+    display_name: Optional[str] = typer.Option(
+        None,
+        "-n",
+        "--name",
+        help="Human-friendly display name",
+    ),
+    description: Optional[str] = typer.Option(
+        None,
+        "-d",
+        "--description",
+        help="Tag description",
+    ),
+) -> None:
+    """Create a new tag.
+
+    Examples:
+        ai tags create marketing.email
+        ai tags create marketing.email.weekly -n "Weekly Emails"
+    """
+    _execute_create(
+        tag_path=tag_path,
+        display_name=display_name,
+        description=description,
+    )
+
+
+@async_command
+async def _execute_create(
+    tag_path: str,
+    display_name: Optional[str],
+    description: Optional[str],
+) -> None:
+    """Execute create tag operation."""
+    async with authenticated_client() as (_config, client):
+        request = CreateTagRequest(
+            tag_path=tag_path,
+            display_name=display_name,
+            description=description,
+        )
+        response = await client.create_tag(request)
+
+    output = OutputService.get()
+    output.success(f"Created tag: {response.tag.tag_path}")

cli/commands/tags/delete/__init__.py

@@ -0,0 +1 @@
+# Empty per project convention - import directly from submodules

cli/commands/tags/delete/command.py

@@ -0,0 +1,47 @@
+"""Tag delete command implementation."""
+
+from uuid import UUID
+
+import typer
+
+from cli.commands.flag_utils import validate_uuid
+from cli.commands.tags.delete.presenter import present_delete_result
+from cli.infrastructure.command import async_command, authenticated_client
+from cli.infrastructure.console import Confirm
+
+
+def tags_delete_command(
+    tag_id: str = typer.Argument(
+        ...,
+        help="Tag UUID",
+    ),
+    yes: bool = typer.Option(
+        False,
+        "-y",
+        "--yes",
+        help="Skip confirmation",
+    ),
+) -> None:
+    """Delete a tag.
+
+    Examples:
+        ai tags delete 123e4567-89ab-cdef-0123-456789abcdef
+        ai tags delete 123e4567-89ab... -y
+    """
+    tag_uuid = validate_uuid(tag_id, "tag")
+
+    if not yes:
+        confirmed = Confirm.ask(f"[yellow]Delete tag {tag_id}?[/yellow]")
+        if not confirmed:
+            raise typer.Abort()
+
+    _execute_delete(tag_id=tag_uuid)
+
+
+@async_command
+async def _execute_delete(tag_id: UUID) -> None:
+    """Execute delete tag operation."""
+    async with authenticated_client() as (_config, client):
+        response = await client.delete_tag(tag_id)
+
+    present_delete_result(response)