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

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

@@ -0,0 +1,53 @@
+"""Knowledge synthesis delete command implementation."""
+
+import typer
+
+from cli.commands.flag_utils import validate_uuid
+from cli.commands.knowledge.synthesis.delete.presenter import (
+    present_synthesis_delete_success,
+)
+from cli.infrastructure.command import async_command, authenticated_client
+
+
+def knowledge_synthesis_delete_command(
+    synthesis_id: str = typer.Argument(
+        ...,
+        help="Synthesis UUID to delete",
+    ),
+    yes: bool = typer.Option(
+        False,
+        "-y",
+        "--yes",
+        help="Skip confirmation prompt",
+    ),
+) -> None:
+    """Delete a synthesis.
+
+    This permanently removes the synthesis, its collection associations,
+    and its source tracking records.
+
+    Examples:
+        ai2 knowledge synthesis delete <synthesis-uuid>
+        ai2 kb synthesis delete <uuid> --yes
+    """
+    # Validate synthesis UUID
+    validate_uuid(synthesis_id, "synthesis")
+
+    # Confirm deletion unless --yes flag provided
+    if not yes:
+        confirm = typer.confirm(
+            f"Are you sure you want to delete synthesis {synthesis_id}?"
+        )
+        if not confirm:
+            raise typer.Abort()
+
+    _execute_delete(synthesis_id)
+
+
+@async_command
+async def _execute_delete(synthesis_id: str) -> None:
+    """Execute synthesis deletion."""
+    async with authenticated_client() as (_config, client):
+        response = await client.delete_synthesis(synthesis_id)
+
+    present_synthesis_delete_success(response)

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

@@ -0,0 +1,31 @@
+"""Presenter for synthesis delete output."""
+
+from rich.panel import Panel
+from rich.table import Table
+
+from cli.infrastructure.formatting.fields import format_uuid
+from cli.infrastructure.output import OutputService
+from alloy_runtime_types.dtos.knowledge import DeleteSynthesisResponse
+
+
+def present_synthesis_delete_success(response: DeleteSynthesisResponse) -> None:
+    """Present successful synthesis deletion.
+
+    Args:
+        response: Delete synthesis response from server
+    """
+    output = OutputService.get()
+
+    output.success("Synthesis deleted successfully")
+
+    # Build a simple table for deleted entity info
+    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("Title", response.title)
+    table.add_row("Topic", response.topic)
+
+    panel = Panel(table, title="Deleted Synthesis", border_style="red")
+    output.console.print(panel)

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

@@ -0,0 +1,55 @@
+"""Knowledge synthesis get command implementation."""
+
+import typer
+
+from cli.commands.flag_utils import validate_uuid
+from cli.commands.knowledge.synthesis.get.presenter import present_synthesis_details
+from cli.infrastructure.command import async_command, authenticated_client
+
+
+def knowledge_synthesis_get_command(
+    synthesis_id: str = typer.Argument(
+        ...,
+        help="Synthesis UUID",
+    ),
+    output: str = typer.Option(
+        "panel",
+        "-o",
+        "--output",
+        help="Output format: 'panel' or 'json'",
+    ),
+) -> None:
+    """Get synthesis details.
+
+    Returns the full synthesis details including content (if completed),
+    status, staleness information, and source tracking.
+
+    Examples:
+        ai2 knowledge synthesis get <synthesis-uuid>
+        ai2 kb synthesis get <uuid> --output json
+    """
+    _execute_get_from_flags(synthesis_id=synthesis_id, output=output)
+
+
+def _execute_get_from_flags(synthesis_id: str, output: str) -> None:
+    """Validate flags and execute get."""
+    # Validate synthesis UUID
+    validate_uuid(synthesis_id, "synthesis")
+
+    # Validate output format
+    output_format = output.lower()
+    if output_format not in ("panel", "json"):
+        raise typer.BadParameter(
+            f"Invalid output format '{output}'. Valid: panel, json"
+        )
+
+    _execute_get(synthesis_id, output_format)
+
+
+@async_command
+async def _execute_get(synthesis_id: str, output_format: str) -> None:
+    """Execute synthesis get."""
+    async with authenticated_client() as (_config, client):
+        response = await client.get_synthesis(synthesis_id)
+
+    present_synthesis_details(response, output_format)

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

@@ -0,0 +1,114 @@
+"""Presenter for synthesis get output."""
+
+import json
+
+from rich.markdown import Markdown
+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 GetSynthesisResponse
+
+
+def present_synthesis_details(
+    response: GetSynthesisResponse, output_format: str
+) -> None:
+    """Present synthesis details.
+
+    Args:
+        response: Get synthesis response from server
+        output_format: Output format ('panel' or 'json')
+    """
+    output = OutputService.get()
+
+    if output_format == "json":
+        # JSON output
+        data = {
+            "id": str(response.id),
+            "topic": response.topic,
+            "title": response.title,
+            "status": response.status,
+            "synthesis_content": response.synthesis_content,
+            "error_message": response.error_message,
+            "is_stale": response.is_stale,
+            "staleness_reason": response.staleness_reason,
+            "source_chunk_count": response.source_chunk_count,
+            "collection_ids": [str(c) for c in response.collection_ids],
+            "synthesizer_agent_id": str(response.synthesizer_agent_id)
+            if response.synthesizer_agent_id
+            else None,
+            "execution_id": str(response.execution_id)
+            if response.execution_id
+            else None,
+            "metadata": response.metadata,
+            "created_at": response.created_at.isoformat(),
+            "updated_at": response.updated_at.isoformat(),
+        }
+        output.console.print_json(json.dumps(data))
+        return
+
+    # Panel output
+    # Build metadata table
+    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("Title", response.title)
+    table.add_row("Topic", response.topic)
+
+    # Status with color
+    status = response.status
+    if status == "completed":
+        status_display = f"[green]{status}[/green]"
+    elif status == "failed":
+        status_display = f"[red]{status}[/red]"
+    elif status == "processing":
+        status_display = f"[yellow]{status}[/yellow]"
+    else:
+        status_display = f"[dim]{status}[/dim]"
+    table.add_row("Status", status_display)
+
+    # Staleness
+    if response.is_stale:
+        stale_display = (
+            f"[yellow]Yes[/yellow] - {response.staleness_reason or 'Unknown reason'}"
+        )
+    else:
+        stale_display = "[green]No[/green]"
+    table.add_row("Stale", stale_display)
+
+    table.add_row("Source Chunks", str(response.source_chunk_count))
+    table.add_row("Collections", str(len(response.collection_ids)))
+
+    if response.synthesizer_agent_id:
+        table.add_row("Agent", format_uuid(response.synthesizer_agent_id, short=True))
+    if response.execution_id:
+        table.add_row("Execution", format_uuid(response.execution_id, short=True))
+
+    table.add_row("Created", format_datetime(response.created_at))
+    table.add_row("Updated", format_datetime(response.updated_at))
+
+    if response.error_message:
+        table.add_row("Error", f"[red]{response.error_message}[/red]")
+
+    # Show metadata if present
+    if response.metadata:
+        table.add_row("Metadata", str(response.metadata))
+
+    panel = Panel(table, title=f"Synthesis: {response.title}", border_style="blue")
+    output.console.print(panel)
+
+    # Show content if completed
+    if response.synthesis_content:
+        output.console.print()
+        content_panel = Panel(
+            Markdown(response.synthesis_content),
+            title="Synthesis Content",
+            border_style="green",
+        )
+        output.console.print(content_panel)

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

@@ -0,0 +1,132 @@
+"""Knowledge synthesis list command implementation."""
+
+from typing import Optional
+
+import typer
+
+from cli.commands.flag_utils import validate_uuid
+from cli.commands.knowledge.synthesis.list.presenter import present_syntheses_list
+from cli.infrastructure.command import async_command, authenticated_client
+
+
+def knowledge_synthesis_list_command(
+    collection: Optional[str] = typer.Option(
+        None,
+        "-C",
+        "--collection",
+        help="Filter by collection UUID",
+    ),
+    status: Optional[str] = typer.Option(
+        None,
+        "-s",
+        "--status",
+        help="Filter by status: pending, processing, completed, failed",
+    ),
+    include_stale: bool = typer.Option(
+        True,
+        "--include-stale/--no-stale",
+        help="Include stale syntheses (default: include)",
+    ),
+    limit: int = typer.Option(
+        50,
+        "-l",
+        "--limit",
+        min=1,
+        max=100,
+        help="Maximum results (1-100)",
+    ),
+    offset: int = typer.Option(
+        0,
+        "--offset",
+        min=0,
+        help="Pagination offset",
+    ),
+    output: str = typer.Option(
+        "table",
+        "-o",
+        "--output",
+        help="Output format: 'table' or 'json'",
+    ),
+) -> None:
+    """List syntheses for the organization.
+
+    Supports filtering by collection, status, and staleness.
+    Results are ordered by creation date (newest first).
+
+    Examples:
+        ai2 knowledge synthesis list
+        ai2 kb synthesis list -C <collection-uuid>
+        ai2 kb synthesis list --status completed --no-stale
+        ai2 kb synthesis list -l 10 --output json
+    """
+    _execute_list_from_flags(
+        collection=collection,
+        status=status,
+        include_stale=include_stale,
+        limit=limit,
+        offset=offset,
+        output=output,
+    )
+
+
+def _execute_list_from_flags(
+    collection: Optional[str],
+    status: Optional[str],
+    include_stale: bool,
+    limit: int,
+    offset: int,
+    output: str,
+) -> None:
+    """Validate flags and execute list."""
+    # Validate collection ID if provided
+    collection_id: str | None = None
+    if collection:
+        validate_uuid(collection, "collection")
+        collection_id = collection
+
+    # Validate status if provided
+    if status:
+        valid_statuses = ["pending", "processing", "completed", "failed"]
+        if status.lower() not in valid_statuses:
+            raise typer.BadParameter(
+                f"Invalid status '{status}'. Valid: {', '.join(valid_statuses)}"
+            )
+        status = status.lower()
+
+    # Validate output format
+    output_format = output.lower()
+    if output_format not in ("table", "json"):
+        raise typer.BadParameter(
+            f"Invalid output format '{output}'. Valid: table, json"
+        )
+
+    _execute_list(
+        collection_id=collection_id,
+        status=status,
+        include_stale=include_stale,
+        limit=limit,
+        offset=offset,
+        output_format=output_format,
+    )
+
+
+@async_command
+async def _execute_list(
+    collection_id: str | None,
+    status: str | None,
+    include_stale: bool,
+    limit: int,
+    offset: int,
+    output_format: str,
+) -> None:
+    """Execute synthesis list."""
+    async with authenticated_client() as (_config, client):
+        response = await client.list_syntheses(
+            collection_id=collection_id,
+            status=status,
+            include_stale=include_stale,
+            limit=limit,
+            offset=offset,
+        )
+
+    present_syntheses_list(response, output_format)

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

@@ -0,0 +1,84 @@
+"""Presenter for synthesis list output."""
+
+import json
+
+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 ListSynthesesResponse
+
+
+def present_syntheses_list(response: ListSynthesesResponse, output_format: str) -> None:
+    """Present synthesis list results.
+
+    Args:
+        response: List syntheses response from server
+        output_format: Output format ('table' or 'json')
+    """
+    output = OutputService.get()
+
+    if output_format == "json":
+        # JSON output
+        data = {
+            "syntheses": [
+                {
+                    "id": str(s.id),
+                    "topic": s.topic,
+                    "title": s.title,
+                    "status": s.status,
+                    "is_stale": s.is_stale,
+                    "source_chunk_count": s.source_chunk_count,
+                    "collection_ids": [str(c) for c in s.collection_ids],
+                    "created_at": s.created_at.isoformat(),
+                    "updated_at": s.updated_at.isoformat(),
+                }
+                for s in response.syntheses
+            ],
+            "total": response.total,
+        }
+        output.console.print_json(json.dumps(data))
+        return
+
+    # Table output
+    if not response.syntheses:
+        output.info("No syntheses found")
+        return
+
+    table = Table(title=f"Syntheses ({response.total} total)")
+    table.add_column("ID", style="dim")
+    table.add_column("Title")
+    table.add_column("Status")
+    table.add_column("Stale", justify="center")
+    table.add_column("Sources", justify="right")
+    table.add_column("Created")
+
+    for synthesis in response.syntheses:
+        # Status styling
+        status = synthesis.status
+        if status == "completed":
+            status_display = f"[green]{status}[/green]"
+        elif status == "failed":
+            status_display = f"[red]{status}[/red]"
+        elif status == "processing":
+            status_display = f"[yellow]{status}[/yellow]"
+        else:
+            status_display = f"[dim]{status}[/dim]"
+
+        # Stale indicator
+        stale_display = (
+            "[yellow]⚠[/yellow]" if synthesis.is_stale else "[green]✓[/green]"
+        )
+
+        table.add_row(
+            format_uuid(synthesis.id, short=True),
+            synthesis.title[:40] + "..."
+            if len(synthesis.title) > 40
+            else synthesis.title,
+            status_display,
+            stale_display,
+            str(synthesis.source_chunk_count),
+            format_datetime(synthesis.created_at),
+        )
+
+    output.console.print(table)

cli/commands/knowledge/synthesis/refresh/command.py

@@ -0,0 +1,42 @@
+"""Knowledge synthesis refresh command implementation."""
+
+import typer
+
+from cli.commands.flag_utils import validate_uuid
+from cli.commands.knowledge.synthesis.refresh.presenter import (
+    present_synthesis_refresh_success,
+)
+from cli.infrastructure.command import async_command, authenticated_client
+
+
+def knowledge_synthesis_refresh_command(
+    synthesis_id: str = typer.Argument(
+        ...,
+        help="Synthesis UUID to refresh",
+    ),
+) -> None:
+    """Refresh a synthesis.
+
+    Regenerates the synthesis content using the same topic, agent, and template.
+    Use this to update a stale synthesis or to get updated results after
+    new documents have been added to the source collections.
+
+    Cannot refresh a synthesis that is currently processing.
+
+    Examples:
+        ai2 knowledge synthesis refresh <synthesis-uuid>
+        ai2 kb synthesis refresh <uuid>
+    """
+    # Validate synthesis UUID
+    validate_uuid(synthesis_id, "synthesis")
+
+    _execute_refresh(synthesis_id)
+
+
+@async_command
+async def _execute_refresh(synthesis_id: str) -> None:
+    """Execute synthesis refresh."""
+    async with authenticated_client() as (_config, client):
+        response = await client.refresh_synthesis(synthesis_id)
+
+    present_synthesis_refresh_success(response)

cli/commands/knowledge/synthesis/refresh/presenter.py

@@ -0,0 +1,33 @@
+"""Presenter for synthesis refresh output."""
+
+from rich.panel import Panel
+from rich.table import Table
+
+from cli.infrastructure.formatting.fields import format_uuid
+from cli.infrastructure.output import OutputService
+from alloy_runtime_types.dtos.knowledge import RefreshSynthesisResponse
+
+
+def present_synthesis_refresh_success(response: RefreshSynthesisResponse) -> None:
+    """Present successful synthesis refresh.
+
+    Args:
+        response: Refresh synthesis response from server
+    """
+    output = OutputService.get()
+
+    output.success("Synthesis refresh queued")
+
+    # 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("Synthesis ID", format_uuid(response.synthesis_id, short=False))
+    table.add_row("Status", f"[yellow]{response.status}[/yellow]")
+    table.add_row("Message", response.message)
+
+    panel = Panel(table, title="Synthesis Refresh Started", border_style="green")
+    output.console.print(panel)
+
+    output.info(f"Poll status with: ai2 kb synthesis get {response.synthesis_id}")

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

@@ -0,0 +1,76 @@
+"""Knowledge synthesis update command implementation."""
+
+from typing import Optional
+
+import typer
+
+from cli.commands.knowledge.synthesis.update.presenter import (
+    present_synthesis_update_result,
+)
+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 UpdateSynthesisRequest
+
+
+def knowledge_synthesis_update_command(
+    synthesis_id: str = typer.Argument(
+        ...,
+        help="Synthesis UUID",
+    ),
+    title: Optional[str] = typer.Option(
+        None,
+        "--title",
+        help="New title for the synthesis",
+    ),
+    content: Optional[str] = typer.Option(
+        None,
+        "--content",
+        help="New synthesis content (or @file)",
+    ),
+) -> None:
+    """Update a synthesis document.
+
+    Update synthesis properties like title or content.
+    At least one of --title or --content must be provided.
+
+    The --content flag accepts a text string or @file reference.
+
+    Examples:
+        ai2 knowledge synthesis update <uuid> --title "New Title"
+        ai2 kb synthesis update <uuid> --content @updated.md
+        ai2 kb synthesis update <uuid> --title "New Title" --content "Updated content"
+    """
+    _execute_update(
+        synthesis_id=synthesis_id,
+        title=title,
+        content_raw=content,
+    )
+
+
+@async_command
+async def _execute_update(
+    synthesis_id: str,
+    title: Optional[str],
+    content_raw: Optional[str],
+) -> None:
+    """Execute synthesis update operation."""
+
+    resolved_content = resolve_content_or_raise(content_raw)
+
+    if title is None and resolved_content is None:
+        raise typer.BadParameter(
+            "At least one of --title or --content must be provided"
+        )
+
+    request = UpdateSynthesisRequest(
+        title=title,
+        synthesis_content=resolved_content,
+    )
+
+    async with authenticated_client() as (_config, client):
+        response = await client.update_synthesis(
+            synthesis_id=synthesis_id,
+            request=request,
+        )
+
+    present_synthesis_update_result(response)

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

@@ -0,0 +1,41 @@
+"""Presenter for knowledge synthesis update command output."""
+
+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 UpdateSynthesisResponse
+
+
+def present_synthesis_update_result(
+    response: UpdateSynthesisResponse,
+) -> None:
+    """Present synthesis update result.
+
+    Args:
+        response: UpdateSynthesisResponse from server
+    """
+    output = OutputService.get()
+
+    output.success(f"Synthesis '{response.title}' updated")
+
+    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("Title", response.title)
+    table.add_row("Topic", response.topic)
+    table.add_row("Status", response.status)
+
+    stale_display = "[red]Yes[/]" if response.is_stale else "[green]No[/]"
+    table.add_row("Stale", stale_display)
+    if response.staleness_reason:
+        table.add_row("Staleness Reason", response.staleness_reason)
+
+    table.add_row("Source Chunks", str(response.source_chunk_count))
+    table.add_row("Updated At", format_datetime(response.updated_at))
+
+    panel = Panel(table, title="Synthesis Updated", border_style="green")
+    output.console.print(panel)