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

cli/commands/generate/text/stream_renderer.py

@@ -0,0 +1,129 @@
+"""Streaming text renderer with thinking block support.
+
+Provides a terminal display for streaming text generation,
+with visual differentiation between thinking/reasoning blocks
+and generated content.
+
+Streams both thinking and content in real-time:
+- Thinking blocks are displayed in red with <thinking> tags to stderr
+- Content is streamed directly to stdout
+"""
+
+import sys
+from collections.abc import AsyncGenerator
+
+from rich.console import Console
+
+from alloy_runtime_types.dtos.generation import GenerateTextStreamChunk
+
+# ANSI escape codes
+RED = "\033[31m"
+RESET = "\033[0m"
+
+
+class StreamRenderer:
+    """Renders streaming text generation with thinking block support.
+
+    Features:
+    - Thinking/reasoning blocks displayed in real-time (to stderr, in red)
+    - Content output to stdout in real-time
+    - Both thinking and content stream as they arrive
+    """
+
+    def __init__(self, console: Console):
+        """Initialize stream renderer.
+
+        Args:
+            console: Rich console for output
+        """
+        self.console = console
+        self._thinking_text = ""
+        self._content_text = ""
+        self._session_id: str | None = None
+        self._in_thinking_block = False
+
+    async def render_stream(
+        self,
+        stream: AsyncGenerator[GenerateTextStreamChunk, None],
+        show_thinking: bool = True,
+    ) -> tuple[str, str, str | None]:
+        """Render a streaming generation.
+
+        Streams both thinking and content in real-time as chunks arrive.
+
+        Args:
+            stream: Async generator of stream chunks
+            show_thinking: Whether to display thinking blocks (default True)
+
+        Returns:
+            Tuple of (content_text, thinking_text, session_id) - accumulated outputs
+        """
+        self._thinking_text = ""
+        self._content_text = ""
+        self._session_id = None
+        self._in_thinking_block = False
+
+        async for chunk in stream:
+            self._process_chunk(chunk, show_thinking)
+
+        # Close thinking block if still open at end of stream
+        if self._in_thinking_block:
+            self._close_thinking_block()
+
+        # Final newline for clean output
+        if self._content_text:
+            sys.stdout.write("\n")
+            sys.stdout.flush()
+
+        return self._content_text, self._thinking_text, self._session_id
+
+    def _process_chunk(
+        self, chunk: GenerateTextStreamChunk, show_thinking: bool
+    ) -> None:
+        """Process a stream chunk.
+
+        Args:
+            chunk: Stream chunk to process
+            show_thinking: Whether to display thinking text
+        """
+        if chunk.chunk_type == "thinking":
+            # Thinking chunks - stream in real-time
+            if chunk.reasoning_content:
+                self._thinking_text += chunk.reasoning_content
+                if show_thinking:
+                    # Open thinking block if not already open
+                    if not self._in_thinking_block:
+                        self._open_thinking_block()
+                    # Stream thinking content immediately
+                    sys.stderr.write(f"{RED}{chunk.reasoning_content}{RESET}")
+                    sys.stderr.flush()
+
+        elif chunk.chunk_type == "metadata":
+            # Metadata chunks - capture session_id from final metadata
+            if chunk.metadata and "chat_session_id" in chunk.metadata:
+                self._session_id = chunk.metadata["chat_session_id"]
+
+        else:
+            # Content chunks - close thinking block first if open
+            if self._in_thinking_block:
+                self._close_thinking_block()
+
+            if chunk.content:
+                self._content_text += chunk.content
+                # Stream content immediately
+                sys.stdout.write(chunk.content)
+                sys.stdout.flush()
+
+    def _open_thinking_block(self) -> None:
+        """Print opening thinking tag to stderr."""
+        sys.stderr.write(f"\n{RED}<thinking>{RESET}\n")
+        sys.stderr.flush()
+        self._in_thinking_block = True
+
+    def _close_thinking_block(self) -> None:
+        """Print closing thinking tag to stderr."""
+        if not self._thinking_text.endswith("\n"):
+            sys.stderr.write("\n")
+        sys.stderr.write(f"{RED}</thinking>{RESET}\n\n")
+        sys.stderr.flush()
+        self._in_thinking_block = False

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

@@ -0,0 +1,64 @@
+"""Knowledge collection cluster command implementation."""
+
+import typer
+
+from cli.commands.knowledge.collections.cluster.presenter import (
+    present_cluster_status,
+    present_cluster_triggered,
+)
+from cli.infrastructure.command import async_command, authenticated_client
+
+
+def knowledge_collections_cluster_command(
+    collection: str = typer.Argument(
+        ...,
+        help="Collection name or UUID",
+    ),
+    wait: bool = typer.Option(
+        False,
+        "--wait",
+        help="Wait for clustering to complete before returning",
+    ),
+    timeout: float = typer.Option(
+        300.0,
+        "--timeout",
+        help="Maximum seconds to wait when using --wait (default: 300)",
+    ),
+) -> None:
+    """Trigger clustering for a knowledge collection.
+
+    Queues an asynchronous clustering run. Use --wait to block until complete.
+
+    Examples:
+        ai2 knowledge collections cluster my-collection
+        ai2 kb collections cluster 550e8400-e29b-41d4-a716-446655440000 --wait
+        ai2 kb collections cluster my-collection --wait --timeout 600
+    """
+    _execute_cluster(
+        collection_identifier=collection,
+        wait=wait,
+        timeout=timeout,
+    )
+
+
+@async_command
+async def _execute_cluster(
+    collection_identifier: str,
+    wait: bool,
+    timeout: float,
+) -> None:
+    """Execute cluster operation."""
+    async with authenticated_client() as (_config, client):
+        response = await client.trigger_collection_clustering(collection_identifier)
+
+    present_cluster_triggered(response)
+
+    if wait:
+        async with authenticated_client() as (_config, client):
+            status = await client.wait_for_collection_clustering(
+                collection_identifier,
+                task_id=response.task_id,
+                timeout=timeout,
+            )
+
+        present_cluster_status(status)

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

@@ -0,0 +1,74 @@
+"""Presenter for knowledge collection cluster command 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 (
+    GetCollectionClusteringStatusResponse,
+    TriggerCollectionClusteringResponse,
+)
+
+
+def present_cluster_triggered(response: TriggerCollectionClusteringResponse) -> None:
+    """Present clustering trigger result.
+
+    Args:
+        response: TriggerCollectionClusteringResponse from server
+    """
+    output = OutputService.get()
+
+    output.success(response.message)
+
+    table = Table(show_header=False, box=None, padding=(0, 1))
+    table.add_column("Field", style="dim")
+    table.add_column("Value")
+
+    table.add_row("Collection ID", format_uuid(response.collection_id, short=False))
+    table.add_row("Task ID", response.task_id)
+    table.add_row("Status", response.status)
+
+    panel = Panel(table, title="Clustering Triggered", border_style="green")
+    output.console.print(panel)
+
+
+def present_cluster_status(
+    response: GetCollectionClusteringStatusResponse,
+) -> None:
+    """Present clustering status details.
+
+    Args:
+        response: GetCollectionClusteringStatusResponse from server
+    """
+    output = OutputService.get()
+
+    # Choose border style based on status
+    border_style = {
+        "completed": "green",
+        "failed": "red",
+        "processing": "yellow",
+        "pending": "dim",
+    }.get(response.status, "dim")
+
+    table = Table(show_header=False, box=None, padding=(0, 1))
+    table.add_column("Field", style="dim")
+    table.add_column("Value")
+
+    table.add_row("Collection ID", format_uuid(response.collection_id, short=False))
+    table.add_row("Status", response.status)
+    table.add_row("Cluster Count", str(response.cluster_count))
+    table.add_row("Total Chunks", str(response.total_chunks))
+    table.add_row("Clustered Chunks", str(response.clustered_chunks))
+    table.add_row("Noise Chunks", str(response.noise_chunks))
+    table.add_row("Unclustered Chunks", str(response.unclustered_chunks))
+    table.add_row("Message", format_optional(response.message))
+    table.add_row("Error", format_optional(response.error_message))
+    table.add_row("Last Cluster Run", format_datetime(response.last_cluster_run_at))
+
+    panel = Panel(table, title="Clustering Status", border_style=border_style)
+    output.console.print(panel)

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

@@ -0,0 +1,46 @@
+"""Knowledge collection cluster-status command implementation."""
+
+import typer
+
+from cli.commands.knowledge.collections.cluster.presenter import present_cluster_status
+from cli.infrastructure.command import async_command, authenticated_client
+
+
+def knowledge_collections_cluster_status_command(
+    collection: str = typer.Argument(
+        ...,
+        help="Collection name or UUID",
+    ),
+    task_id: str = typer.Option(
+        ...,
+        "--task-id",
+        help="Celery task ID returned by the cluster trigger command",
+    ),
+) -> None:
+    """Get clustering status for a knowledge collection.
+
+    Requires a task ID from a previous cluster trigger.
+
+    Examples:
+        ai2 knowledge collections cluster-status my-collection --task-id abc-123
+        ai2 kb collections cluster-status 550e8400-... --task-id abc-123
+    """
+    _execute_cluster_status(
+        collection_identifier=collection,
+        task_id=task_id,
+    )
+
+
+@async_command
+async def _execute_cluster_status(
+    collection_identifier: str,
+    task_id: str,
+) -> None:
+    """Execute cluster status operation."""
+    async with authenticated_client() as (_config, client):
+        response = await client.get_collection_clustering_status(
+            collection_identifier,
+            task_id=task_id,
+        )
+
+    present_cluster_status(response)

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

@@ -0,0 +1,10 @@
+"""Presenter for knowledge collection cluster-status command output.
+
+This module re-exports the shared presenter from the cluster command.
+The cluster-status command and the cluster --wait command both display
+the same status format.
+"""
+
+from cli.commands.knowledge.collections.cluster.presenter import present_cluster_status
+
+__all__ = ["present_cluster_status"]

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

@@ -0,0 +1,137 @@
+"""Knowledge collection create command implementation."""
+
+from typing import Optional
+
+import typer
+
+from cli.commands.flag_utils import validate_section_strategy
+from cli.commands.knowledge.collections.create.presenter import (
+    present_collection_create_success,
+)
+from cli.infrastructure.command import async_command, authenticated_client
+from alloy_runtime_types.dtos.knowledge import CreateCollectionRequest
+
+
+def knowledge_collections_create_command(
+    name: str = typer.Option(
+        ...,
+        "-n",
+        "--name",
+        help="Collection name",
+    ),
+    description: Optional[str] = typer.Option(
+        None,
+        "-d",
+        "--description",
+        help="Collection description",
+    ),
+    chunk_size: int = typer.Option(
+        512,
+        "-c",
+        "--chunk-size",
+        min=64,
+        max=8192,
+        help="Target tokens per chunk (64-8192)",
+    ),
+    chunk_overlap: int = typer.Option(
+        50,
+        "-o",
+        "--chunk-overlap",
+        min=0,
+        help="Token overlap between chunks",
+    ),
+    section_strategy: str = typer.Option(
+        "paragraph_based",
+        "-s",
+        "--section-strategy",
+        help="Section extraction strategy: heading_based, paragraph_based, fixed_size, none",
+    ),
+    dedup_threshold: Optional[float] = typer.Option(
+        None,
+        "--dedup-threshold",
+        min=0.50,
+        max=1.00,
+        help="Dedup similarity threshold (0.50-1.00). Default: 0.95",
+    ),
+    disable_dedup: bool = typer.Option(
+        False,
+        "--disable-dedup",
+        help="Disable chunk deduplication entirely",
+    ),
+    rerank_instruction: Optional[str] = typer.Option(
+        None,
+        "-r",
+        "--rerank-instruction",
+        help="Default instruction for Voyage AI reranking (max 500 chars)",
+    ),
+) -> None:
+    """Create a new knowledge collection.
+
+    Examples:
+        ai2 knowledge collections create -n "Product Docs"
+        ai2 knowledge collections create -n "Support" -d "Support articles" -c 1024
+        ai2 kb collections create -n "Wiki" -s heading_based
+        ai2 kb collections create -n "NoDedup" --disable-dedup
+        ai2 kb collections create -n "StrictDedup" --dedup-threshold 0.99
+    """
+    _execute_create_from_flags(
+        name=name,
+        description=description,
+        chunk_size=chunk_size,
+        chunk_overlap=chunk_overlap,
+        section_strategy=section_strategy,
+        dedup_threshold=dedup_threshold,
+        disable_dedup=disable_dedup,
+        rerank_instruction=rerank_instruction,
+    )
+
+
+@async_command
+async def _execute_create(request: CreateCollectionRequest) -> None:
+    """Execute the collection creation with the given request."""
+    async with authenticated_client() as (_config, client):
+        response = await client.create_collection(request)
+
+    present_collection_create_success(response)
+
+
+def _execute_create_from_flags(
+    name: str,
+    description: Optional[str],
+    chunk_size: int,
+    chunk_overlap: int,
+    section_strategy: str,
+    dedup_threshold: Optional[float],
+    disable_dedup: bool,
+    rerank_instruction: Optional[str],
+) -> None:
+    """Build and execute collection creation from command flags."""
+    strategy = validate_section_strategy(section_strategy)
+
+    if chunk_overlap >= chunk_size:
+        raise typer.BadParameter(
+            f"Chunk overlap ({chunk_overlap}) must be less than chunk size ({chunk_size})"
+        )
+
+    if disable_dedup and dedup_threshold is not None:
+        raise typer.BadParameter("Cannot use --disable-dedup with --dedup-threshold")
+
+    final_dedup_threshold: float | None
+    if disable_dedup:
+        final_dedup_threshold = None
+    elif dedup_threshold is not None:
+        final_dedup_threshold = dedup_threshold
+    else:
+        final_dedup_threshold = 0.95
+
+    request = CreateCollectionRequest(
+        name=name,
+        description=description,
+        chunk_size_tokens=chunk_size,
+        chunk_overlap_tokens=chunk_overlap,
+        section_strategy=strategy,
+        dedup_similarity_threshold=final_dedup_threshold,
+        rerank_instruction=rerank_instruction,
+    )
+
+    _execute_create(request)

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

@@ -0,0 +1,38 @@
+"""Presenter for collection creation output."""
+
+from rich.panel import Panel
+from rich.table import Table
+
+from cli.infrastructure.formatting.fields import (
+    format_optional,
+    format_uuid,
+)
+from cli.infrastructure.output import OutputService
+from alloy_runtime_types.dtos.knowledge import CreateCollectionResponse
+
+
+def present_collection_create_success(response: CreateCollectionResponse) -> None:
+    """Present successful collection creation.
+
+    Args:
+        response: Collection creation response from server
+    """
+    output = OutputService.get()
+
+    output.success("Collection created 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)
+
+    panel = Panel(table, title=f"Collection: {response.name}", border_style="green")
+    output.console.print(panel)

cli/commands/knowledge/collections/delete/__init__.py

@@ -0,0 +1 @@
+

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

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

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

@@ -0,0 +1,20 @@
+"""Presenter for knowledge collection delete command output."""
+
+from cli.infrastructure.output import OutputService
+from alloy_runtime_types.dtos.knowledge import DeleteCollectionResponse
+
+
+def present_delete_result(response: DeleteCollectionResponse) -> None:
+    """Present collection deletion result.
+
+    Args:
+        response: DeleteCollectionResponse from server
+    """
+    output = OutputService.get()
+
+    docs_msg = (
+        f" ({response.documents_deleted} documents deleted)"
+        if response.documents_deleted > 0
+        else ""
+    )
+    output.success(f"Collection '{response.name}' deleted successfully{docs_msg}")

cli/commands/knowledge/collections/get/__init__.py

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,30 @@
+"""Knowledge collections get command implementation."""
+
+import typer
+
+from cli.commands.knowledge.collections.get.presenter import present_collection_details
+from cli.infrastructure.command import async_command, authenticated_client
+
+
+def knowledge_collections_get_command(
+    collection: str = typer.Argument(
+        ...,
+        help="Collection name or UUID",
+    ),
+) -> None:
+    """Get collection details.
+
+    Examples:
+        ai2 knowledge collections get my-collection
+        ai2 kb collections get 550e8400-e29b-41d4-a716-446655440000
+    """
+    _execute_get(collection_identifier=collection)
+
+
+@async_command
+async def _execute_get(collection_identifier: str) -> None:
+    """Execute get collection operation."""
+    async with authenticated_client() as (_config, client):
+        response = await client.get_collection(collection_identifier)
+
+    present_collection_details(response)

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

@@ -0,0 +1,44 @@
+"""Presenter for knowledge collection get command 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 GetCollectionResponse
+
+
+def present_collection_details(response: GetCollectionResponse) -> None:
+    """Present collection details with Rich formatting.
+
+    Args:
+        response: GetCollectionResponse from server
+    """
+    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("Name", response.name)
+    table.add_row("Description", format_optional(response.description))
+    table.add_row("Embedding Model", response.embedding_model)
+    table.add_row("Embedding Dimensions", str(response.embedding_dimensions))
+    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("Document Count", str(response.document_count))
+    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"Collection: {response.name}",
+        border_style="green",
+    )
+    output.console.print(panel)

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

@@ -0,0 +1 @@
+