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

cli/commands/agents/get/command.py

@@ -0,0 +1,37 @@
+"""Agents get command implementation."""
+
+import typer
+
+from cli.commands.agents.get.presenter import present_agent_details
+from cli.infrastructure.command import async_command, authenticated_client
+
+
+def agents_get_command(
+    agent: str = typer.Argument(
+        ...,
+        help="Agent name or UUID",
+    ),
+) -> None:
+    """Get details of a single agent.
+
+    Retrieves the full agent configuration including models and tools.
+    The agent can be specified by name or UUID.
+
+    Examples:
+        ai agents get my-agent
+        ai agents get 123e4567-89ab-cdef-0123-456789abcdef
+    """
+    _execute_get(agent_identifier=agent)
+
+
+@async_command
+async def _execute_get(agent_identifier: str) -> None:
+    """Execute get agent operation.
+
+    Args:
+        agent_identifier: Agent name or UUID
+    """
+    async with authenticated_client() as (_config, client):
+        response = await client.get_agent(agent_identifier)
+
+    present_agent_details(response)

cli/commands/agents/get/presenter.py

@@ -0,0 +1,32 @@
+"""Presenter for agents get command output."""
+
+from rich.table import Table
+
+from cli.infrastructure.output import OutputService
+from alloy_runtime_types.dtos.agents import GetAgentResponse
+
+
+def present_agent_details(response: GetAgentResponse) -> None:
+    """Present agent details with Rich formatting.
+
+    Args:
+        response: GetAgentResponse from server
+    """
+    output = OutputService.get()
+
+    output.success(f"Retrieved agent: {response.name}")
+
+    table = Table(show_header=False, box=None, padding=(0, 1))
+    table.add_column("Field", style="dim", width=20)
+    table.add_column("Value")
+
+    table.add_row("ID", str(response.id))
+    table.add_row("Name", response.name)
+    table.add_row("Description", response.description or "-")
+    table.add_row("Models", f"{len(response.models)} configured")
+    table.add_row("Tools", f"{len(response.tools)} configured")
+    table.add_row(
+        "Tags", ", ".join(t.tag_path for t in response.tags) if response.tags else "-"
+    )
+
+    output.console.print(table)

cli/commands/agents/list/__init__.py

@@ -0,0 +1 @@
+

cli/commands/agents/list/command.py

@@ -0,0 +1,54 @@
+"""Agents list command implementation."""
+
+from typing import Optional
+
+import typer
+
+from cli.commands.agents.list.presenter import present_agents_list
+from cli.infrastructure.command import async_command, authenticated_client
+
+
+def agents_list_command(
+    search: Optional[str] = typer.Option(
+        None,
+        "-s",
+        "--search",
+        help="Fuzzy search terms",
+    ),
+    limit: int = typer.Option(
+        50,
+        "-l",
+        "--limit",
+        min=1,
+        max=100,
+        help="Max results",
+    ),
+    offset: int = typer.Option(
+        0,
+        "--offset",
+        min=0,
+        help="Skip N results",
+    ),
+) -> None:
+    """List agents accessible to you.
+
+    Examples:
+        ai agents list
+        ai agents list -s "claude opus"
+        ai agents list -l 20
+        ai agents list -s bot -l 10 --offset 20
+    """
+    _execute_list(search=search, limit=limit, offset=offset)
+
+
+@async_command
+async def _execute_list(search: Optional[str], limit: int, offset: int) -> None:
+    """Execute list agents operation."""
+    async with authenticated_client() as (_config, client):
+        response = await client.list_agents(
+            search=search,
+            limit=limit,
+            offset=offset,
+        )
+
+    present_agents_list(response)

cli/commands/agents/list/presenter.py

@@ -0,0 +1,82 @@
+"""Presenter for agents list command output."""
+
+from alloy_runtime_types.dtos.agents import ListAgentsResponse
+
+from cli.infrastructure.output import OutputService
+from cli.infrastructure.renderers.list_renderer import ColumnConfig
+
+
+def _format_description(description: str | None) -> str:
+    """Format description for display, truncating if too long.
+
+    Args:
+        description: Optional description text
+
+    Returns:
+        Formatted description string
+    """
+    if not description:
+        return "-"
+    if len(description) > 120:
+        return description[:117] + "..."
+    return description
+
+
+def present_agents_list(response: ListAgentsResponse) -> None:
+    """Present list of agents with Rich table formatting.
+
+    Args:
+        response: List agents response from server
+    """
+    output = OutputService.get()
+
+    if not response.agents:
+        output.info("No agents found")
+        return
+
+    # Define table columns with compact layout configuration
+    # Line 1 (primary): ID, model count, created - machine-readable data
+    # Line 2 (detail): Name, description - human-readable content
+    columns = [
+        ColumnConfig(
+            source_field="id",
+            header_label="ID",
+            compact_line=1,
+            compact_style="cyan",
+        ),
+        ColumnConfig(
+            source_field="model_count",
+            header_label="Models",
+            align="right",
+            formatter=lambda x: f"{x} models" if x else "0 models",
+            compact_line=1,
+            compact_style="green",
+        ),
+        ColumnConfig(
+            source_field="created_at",
+            header_label="Created",
+            formatter=lambda x: x.strftime("%Y-%m-%d") if x else "-",
+            compact_line=1,
+            compact_style="blue",
+        ),
+        ColumnConfig(
+            source_field="name",
+            header_label="Name",
+            compact_line=2,
+            compact_style="white bold",
+        ),
+        ColumnConfig(
+            source_field="description",
+            header_label="Description",
+            formatter=_format_description,
+            compact_line=2,
+            compact_style="dim",
+        ),
+    ]
+
+    # Render table
+    output.table(
+        items=response.agents,  # type: ignore[arg-type]
+        title=f"Agents ({response.total})",
+        columns=columns,
+    )

cli/commands/agents/update/command.py

@@ -0,0 +1,435 @@
+"""Agent update command implementation."""
+
+import json
+from pathlib import Path
+from typing import Annotated, Any, Optional, cast
+from uuid import UUID
+
+import typer
+
+from cli.commands.agents.create.command import parse_tools
+from cli.commands.agents.update.presenter import present_agent_update_success
+from cli.commands.flag_utils import (
+    parse_tags,
+    require_exclusive,
+    require_together,
+    require_update_flags,
+    validate_provider,
+)
+from cli.infrastructure.command import async_command, authenticated_client
+from cli.infrastructure.file_content import FileContentError, resolve_content
+from alloy_runtime_types.dtos.agents import AgentModelConfig, UpdateAgentRequest
+from alloy_runtime_types.dtos.generation import GenerationParameters
+from alloy_runtime_sdk.exceptions.errors import NotFoundError
+
+
+REQUEST_HEADERS = Annotated[
+    Optional[list[str]],
+    typer.Option(
+        "-H",
+        "--header",
+        help="Request header (key:value). Repeatable.",
+    ),
+]
+
+
+def agents_update_command(
+    agent: str = typer.Argument(..., help="Agent name or UUID"),
+    name: Optional[str] = typer.Option(
+        None,
+        "-n",
+        "--name",
+        help="New name",
+    ),
+    description: Optional[str] = typer.Option(
+        None,
+        "-d",
+        "--description",
+        help="New description",
+    ),
+    provider: Optional[str] = typer.Option(
+        None,
+        "-p",
+        "--provider",
+        help="New provider (requires --model)",
+    ),
+    model: Optional[str] = typer.Option(
+        None,
+        "-M",
+        "--model",
+        help="New model (requires --provider)",
+    ),
+    tags: Optional[str] = typer.Option(
+        None,
+        "-t",
+        "--tags",
+        help="Comma-separated tags (replaces all existing tags)",
+    ),
+    clear_tags: bool = typer.Option(
+        False,
+        "--clear-tags",
+        help="Remove all tags from agent",
+    ),
+    temperature: Optional[float] = typer.Option(
+        None,
+        "-T",
+        "--temperature",
+        help="Temperature (0.0-2.0)",
+    ),
+    max_tokens: Optional[int] = typer.Option(
+        None,
+        "--max-tokens",
+        help="Max tokens to generate",
+    ),
+    top_p: Optional[float] = typer.Option(
+        None,
+        "--top-p",
+        help="Nucleus sampling (0.0-1.0)",
+    ),
+    top_k: Optional[int] = typer.Option(
+        None,
+        "--top-k",
+        help="Top-k sampling",
+    ),
+    frequency_penalty: Optional[float] = typer.Option(
+        None,
+        "--frequency-penalty",
+        help="Frequency penalty (-2.0 to 2.0)",
+    ),
+    presence_penalty: Optional[float] = typer.Option(
+        None,
+        "--presence-penalty",
+        help="Presence penalty (-2.0 to 2.0)",
+    ),
+    seed: Optional[int] = typer.Option(
+        None,
+        "--seed",
+        help="Random seed for reproducibility",
+    ),
+    stop: Optional[str] = typer.Option(
+        None,
+        "--stop",
+        help="Stop sequence(s). Comma-separated for multiple.",
+    ),
+    logprobs: Optional[bool] = typer.Option(
+        None,
+        "--logprobs/--no-logprobs",
+        help="Include log probabilities in response",
+    ),
+    top_logprobs: Optional[int] = typer.Option(
+        None,
+        "--top-logprobs",
+        help="Number of top log probs to return (1-20)",
+    ),
+    user: Optional[str] = typer.Option(
+        None,
+        "--user",
+        help="End-user ID for tracking",
+    ),
+    system_template_id: Optional[UUID] = typer.Option(
+        None,
+        "--system-template",
+        help="System template UUID",
+    ),
+    system_version_id: Optional[UUID] = typer.Option(
+        None,
+        "--system-version",
+        help="System instruction version UUID",
+    ),
+    input_schema_id: Optional[UUID] = typer.Option(
+        None,
+        "--input-schema",
+        help="Input schema UUID",
+    ),
+    output_schema_id: Optional[UUID] = typer.Option(
+        None,
+        "--output-schema",
+        help="Output schema UUID (mutually exclusive with --output-schema-def)",
+    ),
+    output_schema_def: Optional[str] = typer.Option(
+        None,
+        "--output-schema-def",
+        help="Inline output schema JSON (or @file.json). Mutually exclusive with --output-schema.",
+    ),
+    clear_description: bool = typer.Option(
+        False,
+        "--clear-description",
+        help="Clear description",
+    ),
+    headers: REQUEST_HEADERS = None,
+    tools: Optional[str] = typer.Option(
+        None,
+        "--tools",
+        help="JSON array of tool configs (or @file.json). Replaces all existing tools.",
+    ),
+    tools_file: Optional[Path] = typer.Option(
+        None,
+        "--tools-file",
+        help="Path to JSON file with tool configs. Replaces all existing tools.",
+        exists=True,
+        readable=True,
+    ),
+    clear_tools: bool = typer.Option(
+        False,
+        "--clear-tools",
+        help="Remove all tools from agent",
+    ),
+) -> None:
+    """Update an existing agent.
+
+    Only specified fields are updated; others are preserved.
+    To update the model, provide both --provider and --model.
+
+    Examples:
+        ai agents update my-agent -n "New Name"
+        ai agents update my-agent -d "Updated description"
+        ai agents update my-agent --clear-description
+        ai agents update my-agent -p anthropic -M claude-3-5-sonnet-20241022
+        ai agents update my-agent -T 0.9 --max-tokens 2000
+        ai agents update my-agent -t "new,tags"
+        ai agents update my-agent --clear-tags
+        ai agents update my-agent --tools '[{"tool_id": "web_search"}]'
+        ai agents update my-agent --clear-tools
+        ai agents update my-agent --top-p 0.9 --frequency-penalty 0.5
+        ai agents update my-agent --output-schema-def '{"type": "object"}'
+        ai agents update my-agent -H 'anthropic-beta:context-1m-2025-08-07'
+    """
+    require_together(("--provider", provider), ("--model", model))
+
+    require_exclusive(
+        ("--tools", tools),
+        ("--tools-file", tools_file),
+        ("--clear-tools", clear_tools),
+    )
+
+    require_exclusive(
+        ("--tags", tags),
+        ("--clear-tags", clear_tags),
+    )
+
+    require_exclusive(
+        ("--output-schema", output_schema_id),
+        ("--output-schema-def", output_schema_def),
+    )
+
+    try:
+        resolved_output_schema_def = resolve_content(output_schema_def)
+    except FileContentError as e:
+        raise typer.BadParameter(str(e))
+
+    parsed_headers: dict[str, str] | None = None
+    if headers:
+        parsed_headers = {}
+        for h in headers:
+            if ":" not in h:
+                raise typer.BadParameter(
+                    f"Invalid header format '{h}'. Use 'key:value' format."
+                )
+            key, value = h.split(":", 1)
+            parsed_headers[key.strip()] = value.strip()
+
+    stop_sequences: str | list[str] | None = None
+    if stop:
+        if "," in stop:
+            stop_sequences = [s.strip() for s in stop.split(",") if s.strip()]
+        else:
+            stop_sequences = stop
+
+    output_schema_dict: dict[str, Any] | None = None
+    if resolved_output_schema_def:
+        try:
+            parsed = json.loads(resolved_output_schema_def)
+            if not isinstance(parsed, dict):
+                raise typer.BadParameter("--output-schema-def must be a JSON object")
+            output_schema_dict = cast(dict[str, Any], parsed)
+        except json.JSONDecodeError as e:
+            raise typer.BadParameter(f"Invalid JSON in --output-schema-def: {e}")
+
+    require_update_flags(
+        ("--name", name),
+        ("--description", description),
+        ("--provider", provider),
+        ("--tags", tags),
+        ("--clear-tags", clear_tags),
+        ("--temperature", temperature),
+        ("--max-tokens", max_tokens),
+        ("--top-p", top_p),
+        ("--top-k", top_k),
+        ("--frequency-penalty", frequency_penalty),
+        ("--presence-penalty", presence_penalty),
+        ("--seed", seed),
+        ("--stop", stop),
+        ("--logprobs", logprobs),
+        ("--top-logprobs", top_logprobs),
+        ("--user", user),
+        ("--system-template", system_template_id),
+        ("--system-version", system_version_id),
+        ("--input-schema", input_schema_id),
+        ("--output-schema", output_schema_id),
+        ("--output-schema-def", output_schema_def),
+        ("--clear-description", clear_description),
+        ("--header", headers),
+        ("--tools", tools),
+        ("--tools-file", tools_file),
+        ("--clear-tools", clear_tools),
+    )
+
+    _execute_update(
+        agent_identifier=agent,
+        name=name,
+        description=description,
+        provider=provider,
+        model=model,
+        tags=tags,
+        clear_tags=clear_tags,
+        temperature=temperature,
+        max_tokens=max_tokens,
+        top_p=top_p,
+        top_k=top_k,
+        frequency_penalty=frequency_penalty,
+        presence_penalty=presence_penalty,
+        seed=seed,
+        stop_sequences=stop_sequences,
+        logprobs=logprobs,
+        top_logprobs=top_logprobs,
+        user=user,
+        system_template_id=system_template_id,
+        system_version_id=system_version_id,
+        input_schema_id=input_schema_id,
+        output_schema_id=output_schema_id,
+        output_schema_dict=output_schema_dict,
+        clear_description=clear_description,
+        headers=parsed_headers,
+        tools=tools,
+        tools_file=tools_file,
+        clear_tools=clear_tools,
+    )
+
+
+@async_command
+async def _execute_update(
+    agent_identifier: str,
+    name: Optional[str],
+    description: Optional[str],
+    provider: Optional[str],
+    model: Optional[str],
+    tags: Optional[str],
+    clear_tags: bool,
+    temperature: Optional[float],
+    max_tokens: Optional[int],
+    top_p: Optional[float],
+    top_k: Optional[int],
+    frequency_penalty: Optional[float],
+    presence_penalty: Optional[float],
+    seed: Optional[int],
+    stop_sequences: str | list[str] | None,
+    logprobs: Optional[bool],
+    top_logprobs: Optional[int],
+    user: Optional[str],
+    system_template_id: Optional[UUID],
+    system_version_id: Optional[UUID],
+    input_schema_id: Optional[UUID],
+    output_schema_id: Optional[UUID],
+    output_schema_dict: dict[str, Any] | None,
+    clear_description: bool,
+    headers: dict[str, str] | None,
+    tools: Optional[str],
+    tools_file: Optional[Path],
+    clear_tools: bool,
+) -> None:
+    """Execute the agent update operation."""
+    models: list[AgentModelConfig] | None = None
+    if provider is not None and model is not None:
+        provider_enum = validate_provider(provider)
+        models = [
+            AgentModelConfig(
+                provider_key=provider_enum,
+                provider_model_name=model,
+                preference_order=0,
+            )
+        ]
+
+    request_data: dict[str, Any] = {}
+
+    if name is not None:
+        request_data["name"] = name
+
+    if description is not None:
+        request_data["description"] = description
+    elif clear_description:
+        request_data["description"] = None
+
+    if models is not None:
+        request_data["models"] = models
+
+    if clear_tags:
+        request_data["tags"] = []
+    elif tags is not None:
+        request_data["tags"] = parse_tags(tags)
+
+    if system_template_id is not None:
+        request_data["system_instruction_template"] = str(system_template_id)
+
+    if system_version_id is not None:
+        request_data["system_instruction_version_id"] = str(system_version_id)
+
+    if input_schema_id is not None:
+        request_data["input_schema_id"] = str(input_schema_id)
+
+    if output_schema_id is not None:
+        request_data["output_schema_id"] = str(output_schema_id)
+
+    if output_schema_dict is not None:
+        request_data["output_schema"] = output_schema_dict
+
+    if headers is not None:
+        request_data["default_request_headers"] = headers
+
+    gen_params_fields = [
+        temperature,
+        max_tokens,
+        top_p,
+        top_k,
+        frequency_penalty,
+        presence_penalty,
+        seed,
+        stop_sequences,
+        logprobs,
+        top_logprobs,
+        user,
+    ]
+    if any(p is not None for p in gen_params_fields):
+        request_data["generation_params"] = GenerationParameters(
+            temperature=temperature,
+            max_tokens=max_tokens,
+            top_p=top_p,
+            top_k=top_k,
+            frequency_penalty=frequency_penalty,
+            presence_penalty=presence_penalty,
+            seed=seed,
+            stop=stop_sequences,
+            logprobs=logprobs,
+            top_logprobs=top_logprobs,
+            user=user,
+        )
+
+    if clear_tools:
+        request_data["tools"] = []
+    elif tools is not None or tools_file is not None:
+        tool_configs = parse_tools(tools, tools_file)
+        if tool_configs is not None:
+            request_data["tools"] = tool_configs
+
+    request = UpdateAgentRequest(**request_data)
+
+    async with authenticated_client() as (_, client):
+        try:
+            agent_data = await client.get_agent(agent_identifier)
+        except NotFoundError:
+            raise typer.BadParameter(
+                f"Agent '{agent_identifier}' not found. Use 'ai agents list' to see available agents."
+            )
+
+        response = await client.update_agent(agent_data.id, request)
+
+    present_agent_update_success(response)

cli/commands/agents/update/fields.py

@@ -0,0 +1,40 @@
+"""Field definitions for agent update presentation."""
+
+from alloy_runtime_types.dtos.agents import UpdateAgentResponse
+
+
+def format_models(response: UpdateAgentResponse) -> str:
+    """Format models list for display."""
+    return ", ".join(
+        f"{m.provider_key.value}:{m.provider_model_name}" for m in response.models
+    )
+
+
+def format_tools(response: UpdateAgentResponse) -> str:
+    """Format tools list for display."""
+    if not response.tools:
+        return "(none)"
+    return ", ".join(t.tool_id for t in response.tools)
+
+
+def format_tags(response: UpdateAgentResponse) -> str:
+    """Format tags list for display."""
+    if not response.tags:
+        return "(none)"
+    return ", ".join(t.tag_path for t in response.tags)
+
+
+def format_generation_params(response: UpdateAgentResponse) -> str:
+    """Format generation parameters for display."""
+    if not response.generation_params:
+        return "(default)"
+
+    params: list[str] = []
+    if response.generation_params.temperature is not None:
+        params.append(f"temp={response.generation_params.temperature}")
+    if response.generation_params.max_tokens is not None:
+        params.append(f"max_tokens={response.generation_params.max_tokens}")
+    if response.generation_params.reasoning_effort is not None:
+        params.append(f"reasoning={response.generation_params.reasoning_effort}")
+
+    return ", ".join(params) if params else "(default)"