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

cli/commands/knowledge/collections/list/command.py

@@ -0,0 +1,41 @@
+"""Knowledge collections list command implementation."""
+
+import typer
+
+from cli.commands.knowledge.collections.list.presenter import present_collections_list
+from cli.infrastructure.command import async_command, authenticated_client
+
+
+def knowledge_collections_list_command(
+    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 knowledge collections.
+
+    Examples:
+        ai2 knowledge collections list
+        ai2 kb collections list -l 20
+        ai2 kb collections list --offset 10
+    """
+    _execute_list(limit=limit, offset=offset)
+
+
+@async_command
+async def _execute_list(limit: int, offset: int) -> None:
+    """Execute list collections operation."""
+    async with authenticated_client() as (_config, client):
+        response = await client.list_collections(limit=limit, offset=offset)
+
+    present_collections_list(response)

cli/commands/knowledge/collections/list/presenter.py

@@ -0,0 +1,68 @@
+"""Presenter for knowledge collections list command output."""
+
+from alloy_runtime_types.dtos.knowledge import ListCollectionsResponse
+
+from cli.infrastructure.output import OutputService
+from cli.infrastructure.renderers.list_renderer import ColumnConfig
+
+
+def present_collections_list(response: ListCollectionsResponse) -> None:
+    """Present list of collections with Rich table formatting.
+
+    Args:
+        response: List collections response from server
+    """
+    output = OutputService.get()
+
+    if not response.collections:
+        output.info("No collections found")
+        return
+
+    columns = [
+        ColumnConfig(
+            source_field="id",
+            header_label="ID",
+            compact_line=1,
+            compact_style="cyan",
+        ),
+        ColumnConfig(
+            source_field="section_strategy",
+            header_label="Strategy",
+            compact_line=1,
+            compact_style="green",
+        ),
+        ColumnConfig(
+            source_field="chunk_size_tokens",
+            header_label="Chunk Size",
+            align="right",
+            formatter=lambda x: f"{x} tokens",
+            compact_line=1,
+            compact_style="blue",
+        ),
+        ColumnConfig(
+            source_field="updated_at",
+            header_label="Updated",
+            formatter=lambda x: x.strftime("%Y-%m-%d") if x else "-",
+            compact_line=1,
+            compact_style="dim",
+        ),
+        ColumnConfig(
+            source_field="name",
+            header_label="Name",
+            compact_line=2,
+            compact_style="white bold",
+        ),
+        ColumnConfig(
+            source_field="description",
+            header_label="Description",
+            formatter=lambda x: x[:80] + "..." if x and len(x) > 80 else (x or "-"),
+            compact_line=2,
+            compact_style="dim",
+        ),
+    ]
+
+    output.table(
+        items=response.collections,  # type: ignore[arg-type]
+        title=f"Collections ({response.total})",
+        columns=columns,
+    )

cli/commands/knowledge/collections/update/command.py

@@ -0,0 +1,97 @@
+"""Knowledge collection update command implementation."""
+
+from typing import Optional
+
+import typer
+
+from cli.commands.flag_utils import require_update_flags, validate_uuid
+from cli.commands.knowledge.collections.update.presenter import (
+    present_collection_update_success,
+)
+from cli.infrastructure.command import async_command, authenticated_client
+from alloy_runtime_types.dtos.knowledge import UpdateCollectionRequest
+
+
+def knowledge_collections_update_command(
+    collection_id: str = typer.Argument(
+        ...,
+        help="Collection UUID or name to update",
+    ),
+    name: Optional[str] = typer.Option(
+        None,
+        "-n",
+        "--name",
+        help="New collection name",
+    ),
+    description: Optional[str] = typer.Option(
+        None,
+        "-d",
+        "--description",
+        help="New collection description",
+    ),
+    rerank_instruction: Optional[str] = typer.Option(
+        None,
+        "-r",
+        "--rerank-instruction",
+        help="New default instruction for Voyage AI reranking (max 500 chars)",
+    ),
+) -> None:
+    """Update a knowledge collection.
+
+    At least one update flag (--name, --description, or --rerank-instruction) is required.
+
+    Examples:
+        ai2 knowledge collections update <uuid> -n "New Name"
+        ai2 knowledge collections update <uuid> -d "Updated description"
+        ai2 kb collections update <uuid> -r "Prioritize recent documents"
+        ai2 kb collections update <uuid> -n "Docs" -d "Documentation" -r "Focus on API details"
+    """
+    require_update_flags(
+        ("--name", name),
+        ("--description", description),
+        ("--rerank-instruction", rerank_instruction),
+    )
+
+    _execute_update_from_flags(
+        collection_id=collection_id,
+        name=name,
+        description=description,
+        rerank_instruction=rerank_instruction,
+    )
+
+
+def _execute_update_from_flags(
+    collection_id: str,
+    name: Optional[str],
+    description: Optional[str],
+    rerank_instruction: Optional[str],
+) -> None:
+    """Build and execute collection update from command flags."""
+    # Validate collection ID if it looks like a UUID
+    # (Server accepts both UUID and name, so we only validate UUID format)
+    try:
+        validate_uuid(collection_id, "collection")
+    except typer.BadParameter:
+        # Not a UUID - treat as name, let server handle validation
+        pass
+
+    # Build request with only provided fields
+    request = UpdateCollectionRequest(
+        name=name,
+        description=description,
+        rerank_instruction=rerank_instruction,
+    )
+
+    _execute_update(collection_id, request)
+
+
+@async_command
+async def _execute_update(
+    collection_id: str,
+    request: UpdateCollectionRequest,
+) -> None:
+    """Execute the collection update with the given request."""
+    async with authenticated_client() as (_config, client):
+        response = await client.update_collection(collection_id, request)
+
+    present_collection_update_success(response)

cli/commands/knowledge/collections/update/presenter.py

@@ -0,0 +1,42 @@
+"""Presenter for collection update output."""
+
+from rich.panel import Panel
+from rich.table import Table
+
+from cli.infrastructure.formatting.fields import (
+    format_datetime,
+    format_optional,
+    format_uuid,
+)
+from cli.infrastructure.output import OutputService
+from alloy_runtime_types.dtos.knowledge import UpdateCollectionResponse
+
+
+def present_collection_update_success(response: UpdateCollectionResponse) -> None:
+    """Present successful collection update.
+
+    Args:
+        response: Collection update response from server
+    """
+    output = OutputService.get()
+
+    output.success("Collection updated successfully")
+
+    # Build a simple table for entity display
+    table = Table(show_header=False, box=None, padding=(0, 1))
+    table.add_column("Field", style="dim")
+    table.add_column("Value")
+
+    table.add_row("ID", format_uuid(response.id, short=False))
+    table.add_row("Name", response.name)
+    table.add_row("Description", format_optional(response.description))
+    table.add_row("Embedding Model", response.embedding_model)
+    table.add_row("Chunk Size", f"{response.chunk_size_tokens} tokens")
+    table.add_row("Chunk Overlap", f"{response.chunk_overlap_tokens} tokens")
+    table.add_row("Section Strategy", response.section_strategy)
+    table.add_row("Rerank Instruction", format_optional(response.rerank_instruction))
+    table.add_row("Created", format_datetime(response.created_at))
+    table.add_row("Updated", format_datetime(response.updated_at))
+
+    panel = Panel(table, title=f"Collection: {response.name}", border_style="green")
+    output.console.print(panel)

cli/commands/knowledge/documents/bulk_metadata/command.py

@@ -0,0 +1,119 @@
+"""Knowledge documents bulk metadata update command implementation."""
+
+import json
+from typing import Any, Optional, cast
+from uuid import UUID
+
+import typer
+
+from cli.commands.knowledge.documents.bulk_metadata.presenter import (
+    present_bulk_metadata_result,
+)
+from cli.commands.flag_utils import validate_uuid
+from cli.infrastructure.command import async_command, authenticated_client
+from cli.infrastructure.file_content import resolve_content_or_raise
+from alloy_runtime_types.dtos.knowledge import BulkUpdateDocumentMetadataRequest
+
+
+def knowledge_documents_bulk_metadata_command(
+    filter_: str = typer.Option(
+        ...,
+        "--filter",
+        help="JSONB containment filter to match documents (JSON or @file.json)",
+    ),
+    metadata: str = typer.Option(
+        ...,
+        "--metadata",
+        help="Metadata fields to apply (JSON or @file.json)",
+    ),
+    metadata_mode: str = typer.Option(
+        "merge",
+        "--metadata-mode",
+        help="Metadata update mode: 'merge' (default) or 'replace'",
+    ),
+    collection: Optional[str] = typer.Option(
+        None,
+        "-C",
+        "--collection",
+        help="Optional collection UUID to scope the update",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Preview matched count without updating",
+    ),
+) -> None:
+    """Bulk-update metadata across documents matching a filter.
+
+    Both --filter and --metadata accept a JSON string or @file reference.
+    Use --dry-run to preview how many documents match without modifying them.
+
+    Examples:
+        ai2 knowledge documents bulk-metadata \\
+            --filter '{"source": "slack"}' \\
+            --metadata '{"reviewed": true}'
+
+        ai2 kb documents bulk-metadata \\
+            --filter @filter.json --metadata @patch.json --dry-run
+
+        ai2 kb documents bulk-metadata \\
+            --filter '{"team": "eng"}' --metadata '{"archived": true}' \\
+            -C <collection-uuid>
+    """
+    _execute_bulk_metadata(
+        filter_raw=filter_,
+        metadata_raw=metadata,
+        metadata_mode=metadata_mode,
+        collection=collection,
+        dry_run=dry_run,
+    )
+
+
+def _parse_json_option(value: str, option_name: str) -> dict[str, Any]:
+    resolved = resolve_content_or_raise(value)
+    if resolved is None:
+        raise typer.BadParameter(f"{option_name} is required")
+
+    try:
+        result = json.loads(resolved)
+    except json.JSONDecodeError as e:
+        raise typer.BadParameter(f"Invalid JSON for {option_name}: {e}")
+    if not isinstance(result, dict):
+        raise typer.BadParameter(f"{option_name} must be a JSON object")
+    return cast(dict[str, Any], result)
+
+
+@async_command
+async def _execute_bulk_metadata(
+    filter_raw: str,
+    metadata_raw: str,
+    metadata_mode: str,
+    collection: Optional[str],
+    dry_run: bool,
+) -> None:
+    """Execute bulk document metadata update operation."""
+
+    if metadata_mode not in ("merge", "replace"):
+        raise typer.BadParameter(
+            f"Invalid metadata mode '{metadata_mode}'. Must be 'merge' or 'replace'."
+        )
+
+    filter_dict = _parse_json_option(filter_raw, "--filter")
+    metadata_dict = _parse_json_option(metadata_raw, "--metadata")
+
+    collection_id: UUID | None = None
+    if collection is not None:
+        collection_id = validate_uuid(collection, "collection")
+
+    request = BulkUpdateDocumentMetadataRequest(
+        filter=filter_dict,
+        patch=metadata_dict,
+        metadata_mode=metadata_mode,  # type: ignore[arg-type]
+        collection_id=collection_id,
+        dry_run=dry_run,
+    )
+
+    async with authenticated_client() as (_config, client):
+        response = await client.bulk_update_document_metadata(request)
+
+    present_bulk_metadata_result(response)

cli/commands/knowledge/documents/bulk_metadata/presenter.py

@@ -0,0 +1,36 @@
+"""Presenter for knowledge documents bulk metadata update command output."""
+
+from rich.panel import Panel
+from rich.table import Table
+
+from cli.infrastructure.output import OutputService
+from alloy_runtime_types.dtos.knowledge import BulkUpdateDocumentMetadataResponse
+
+
+def present_bulk_metadata_result(
+    response: BulkUpdateDocumentMetadataResponse,
+) -> None:
+    """Present bulk metadata update result.
+
+    Args:
+        response: BulkUpdateDocumentMetadataResponse from server
+    """
+    output = OutputService.get()
+
+    if response.dry_run:
+        output.info("Dry run — no documents modified")
+    else:
+        output.success(f"Updated metadata on {response.updated_count} document(s)")
+
+    table = Table(show_header=False, box=None, padding=(0, 1))
+    table.add_column("Field", style="dim")
+    table.add_column("Value")
+
+    table.add_row("Matched", str(response.matched_count))
+    table.add_row("Updated", str(response.updated_count))
+    table.add_row("Dry Run", str(response.dry_run))
+
+    border_style = "blue" if response.dry_run else "green"
+    title = "Bulk Metadata Dry Run" if response.dry_run else "Bulk Metadata Update"
+    panel = Panel(table, title=title, border_style=border_style)
+    output.console.print(panel)

cli/commands/knowledge/documents/delete/command.py

@@ -0,0 +1,47 @@
+"""Knowledge documents delete command implementation."""
+
+import typer
+
+from cli.commands.knowledge.documents.delete.presenter import present_delete_result
+from cli.infrastructure.command import async_command, authenticated_client
+from cli.infrastructure.console import Confirm
+
+
+def knowledge_documents_delete_command(
+    document: str = typer.Argument(
+        ...,
+        help="Document UUID",
+    ),
+    yes: bool = typer.Option(
+        False,
+        "-y",
+        "--yes",
+        help="Skip confirmation",
+    ),
+) -> None:
+    """Delete a document and all its chunks.
+
+    Permanently removes the document and all associated chunks and questions.
+
+    Examples:
+        ai2 knowledge documents delete 550e8400-e29b-41d4-a716-446655440000
+        ai2 kb documents delete 550e8400-e29b-41d4-a716-446655440000 -y
+    """
+    _execute_delete(document_id=document, skip_confirm=yes)
+
+
+@async_command
+async def _execute_delete(document_id: str, skip_confirm: bool) -> None:
+    """Execute delete document operation."""
+    if not skip_confirm:
+        confirmed = Confirm.ask(
+            f"[yellow]Delete document '{document_id}'?[/yellow] "
+            "This will delete all chunks and cannot be undone"
+        )
+        if not confirmed:
+            raise typer.Abort()
+
+    async with authenticated_client() as (_config, client):
+        response = await client.delete_document(document_id)
+
+    present_delete_result(response)

cli/commands/knowledge/documents/delete/presenter.py

@@ -0,0 +1,20 @@
+"""Presenter for knowledge document delete command output."""
+
+from cli.infrastructure.output import OutputService
+from alloy_runtime_types.dtos.knowledge import DeleteDocumentResponse
+
+
+def present_delete_result(response: DeleteDocumentResponse) -> None:
+    """Present document deletion result.
+
+    Args:
+        response: DeleteDocumentResponse from server
+    """
+    output = OutputService.get()
+
+    chunks_msg = (
+        f" ({response.chunks_deleted} chunks deleted)"
+        if response.chunks_deleted > 0
+        else ""
+    )
+    output.success(f"Document '{response.title}' deleted successfully{chunks_msg}")

cli/commands/knowledge/documents/get/command.py

@@ -0,0 +1,39 @@
+"""Knowledge documents get command implementation."""
+
+import typer
+
+from cli.commands.knowledge.documents.get.presenter import present_document_details
+from cli.infrastructure.command import async_command, authenticated_client
+
+
+def knowledge_documents_get_command(
+    document: str = typer.Argument(
+        ...,
+        help="Document UUID",
+    ),
+    include_content: bool = typer.Option(
+        False,
+        "-c",
+        "--include-content",
+        help="Include original document content",
+    ),
+) -> None:
+    """Get document details.
+
+    Examples:
+        ai2 knowledge documents get 550e8400-e29b-41d4-a716-446655440000
+        ai2 kb documents get 550e8400-e29b-41d4-a716-446655440000 -c
+    """
+    _execute_get(document_id=document, include_content=include_content)
+
+
+@async_command
+async def _execute_get(document_id: str, include_content: bool) -> None:
+    """Execute get document operation."""
+    async with authenticated_client() as (_config, client):
+        response = await client.get_document(
+            document_id=document_id,
+            include_content=include_content,
+        )
+
+    present_document_details(response, show_content=include_content)

cli/commands/knowledge/documents/get/presenter.py

@@ -0,0 +1,78 @@
+"""Presenter for knowledge document get command output."""
+
+import json
+
+from rich.panel import Panel
+from rich.table import Table
+
+from cli.infrastructure.formatting.fields import (
+    format_datetime,
+    format_uuid,
+)
+from cli.infrastructure.output import OutputService
+from alloy_runtime_types.dtos.knowledge import GetDocumentResponse
+
+
+def _format_status(status: str) -> str:
+    """Format processing status with color."""
+    status_colors = {
+        "completed": "[green]completed[/]",
+        "processing": "[yellow]processing[/]",
+        "pending": "[blue]pending[/]",
+        "failed": "[red]failed[/]",
+    }
+    return status_colors.get(status, status)
+
+
+def present_document_details(
+    response: GetDocumentResponse, show_content: bool = False
+) -> None:
+    """Present document details with Rich formatting.
+
+    Args:
+        response: GetDocumentResponse from server
+        show_content: Whether to show original content panel
+    """
+    output = OutputService.get()
+
+    table = Table(show_header=False, box=None, padding=(0, 1))
+    table.add_column("Field", style="dim")
+    table.add_column("Value")
+
+    table.add_row("ID", format_uuid(response.id, short=False))
+    table.add_row("Collection ID", format_uuid(response.collection_id, short=False))
+    table.add_row("Title", response.title)
+    table.add_row("Source Type", response.source_type)
+    table.add_row("Character Count", f"{response.character_count:,}")
+    table.add_row(
+        "Estimated Tokens",
+        f"{response.estimated_tokens:,}" if response.estimated_tokens else "-",
+    )
+    table.add_row("Processing Status", _format_status(response.processing_status))
+    if response.processing_error:
+        table.add_row("Processing Error", f"[red]{response.processing_error}[/]")
+    table.add_row("Chunks Count", str(response.chunks_count))
+    table.add_row("Chunks Failed", str(response.chunks_failed))
+    table.add_row("Questions Generated", str(response.questions_generated))
+    if response.metadata:
+        table.add_row("Metadata", json.dumps(response.metadata, indent=2))
+    table.add_row("Created At", format_datetime(response.created_at))
+    table.add_row("Updated At", format_datetime(response.updated_at))
+
+    panel = Panel(
+        table,
+        title=f"Document: {response.title}",
+        border_style="green",
+    )
+    output.console.print(panel)
+
+    if show_content and response.original_content:
+        content_panel = Panel(
+            response.original_content[:2000]
+            + ("..." if len(response.original_content) > 2000 else ""),
+            title="Original Content",
+            border_style="blue",
+        )
+        output.console.print(content_panel)
+    elif show_content and not response.original_content:
+        output.info("No original content available")