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

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

@@ -0,0 +1,37 @@
+"""Presenter for knowledge document update metadata 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 UpdateDocumentMetadataResponse
+
+
+def present_update_metadata_result(
+    response: UpdateDocumentMetadataResponse,
+) -> None:
+    """Present document metadata update result.
+
+    Args:
+        response: UpdateDocumentMetadataResponse from server
+    """
+    output = OutputService.get()
+
+    output.success(f"Document '{response.title}' metadata 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("Collection ID", format_uuid(response.collection_id, short=False))
+    table.add_row("Title", response.title)
+    if response.metadata:
+        table.add_row("Metadata", json.dumps(response.metadata, indent=2))
+    table.add_row("Updated At", format_datetime(response.updated_at))
+
+    panel = Panel(table, title="Document Updated", border_style="green")
+    output.console.print(panel)

cli/commands/knowledge/recover/command.py

@@ -0,0 +1,46 @@
+"""Knowledge recover command implementation."""
+
+from typing import Optional
+
+import typer
+
+from cli.commands.knowledge.recover.presenter import present_recovery_result
+from cli.infrastructure.command import async_command, authenticated_client
+from alloy_runtime_types.dtos.knowledge import RecoverDocumentsRequest
+
+
+def knowledge_recover_command(
+    max_retries: Optional[int] = typer.Option(
+        None,
+        "-r",
+        "--max-retries",
+        min=1,
+        max=10,
+        help="Override max retry attempts (default: 3)",
+    ),
+) -> None:
+    """Recover stuck documents.
+
+    Finds documents stuck in 'processing' or 'pending' state and either
+    re-queues them for processing or marks them as permanently failed.
+
+    Documents can get stuck when:
+    - Processing is interrupted (container crash, API timeout, etc.)
+    - Celery never picks up the task (message lost, worker unavailable)
+
+    Examples:
+        ai2 knowledge recover
+        ai2 kb recover --max-retries 5
+    """
+    _execute_recover(max_retries=max_retries)
+
+
+@async_command
+async def _execute_recover(max_retries: Optional[int]) -> None:
+    """Execute document recovery operation."""
+    request = RecoverDocumentsRequest(max_retries=max_retries) if max_retries else None
+
+    async with authenticated_client() as (_config, client):
+        response = await client.recover_documents(request)
+
+    present_recovery_result(response)

cli/commands/knowledge/recover/presenter.py

@@ -0,0 +1,79 @@
+"""Presenter for document recovery output."""
+
+from uuid import UUID
+
+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 RecoverDocumentsResponse
+
+
+def present_recovery_result(response: RecoverDocumentsResponse) -> None:
+    """Present document recovery results.
+
+    Args:
+        response: Recovery response from server
+    """
+    output = OutputService.get()
+
+    total_affected = (
+        response.recovered_count + response.failed_count + response.requeued_count
+    )
+
+    if total_affected == 0:
+        output.info("No stuck documents found")
+        return
+
+    output.success("Document recovery completed")
+
+    # Build summary table
+    table = Table(show_header=False, box=None, padding=(0, 1))
+    table.add_column("Metric", style="dim")
+    table.add_column("Value")
+
+    table.add_row("Documents recovered", str(response.recovered_count))
+    table.add_row("Documents re-queued", str(response.requeued_count))
+    table.add_row("Documents permanently failed", str(response.failed_count))
+
+    panel = Panel(table, title="Recovery Summary", border_style="green")
+    output.console.print(panel)
+
+    # Show document IDs if any
+    if response.requeued_document_ids:
+        _present_document_ids(
+            output, "Re-queued for processing", response.requeued_document_ids
+        )
+
+    if response.recovered_document_ids:
+        _present_document_ids(
+            output, "Reset for retry", response.recovered_document_ids
+        )
+
+    if response.failed_document_ids:
+        _present_document_ids(
+            output, "Permanently failed", response.failed_document_ids, style="red"
+        )
+
+
+def _present_document_ids(
+    output: OutputService,
+    title: str,
+    doc_ids: list[UUID],
+    style: str = "cyan",
+    max_display: int = 10,
+) -> None:
+    """Present a list of document IDs."""
+    if not doc_ids:
+        return
+
+    output.console.print(f"\n[{style}]{title}:[/{style}]")
+
+    displayed: list[UUID] = doc_ids[:max_display]
+    for doc_id in displayed:
+        output.console.print(f"  {format_uuid(doc_id, short=False)}")
+
+    remaining = len(doc_ids) - max_display
+    if remaining > 0:
+        output.console.print(f"  [dim]...and {remaining} more[/dim]")

cli/commands/knowledge/search/command.py

@@ -0,0 +1,218 @@
+"""Knowledge search command implementation."""
+
+import json
+from typing import Any, Optional
+from uuid import UUID
+
+import typer
+
+from cli.commands.flag_utils import validate_uuid
+from cli.commands.knowledge.search.presenter import present_search_results
+from cli.infrastructure.command import async_command, authenticated_client
+from alloy_runtime_types.dtos.knowledge import SearchRequest
+
+
+def knowledge_search_command(
+    query: str = typer.Argument(..., help="Search query"),
+    collections: Optional[str] = typer.Option(
+        None,
+        "-C",
+        "--collections",
+        help="Comma-separated collection IDs to search",
+    ),
+    collection_filter: Optional[str] = typer.Option(
+        None,
+        "-F",
+        "--collection-filter",
+        help="Filter by collection name pattern (e.g., 'Product*')",
+    ),
+    tag_filter: Optional[str] = typer.Option(
+        None,
+        "-T",
+        "--tag-filter",
+        help="Filter by document tag pattern (e.g., 'engineering.*', 'docs')",
+    ),
+    top_k: int = typer.Option(
+        5,
+        "-k",
+        "--top-k",
+        min=1,
+        max=20,
+        help="Number of results to return (1-20)",
+    ),
+    hyde_agent: Optional[str] = typer.Option(
+        None,
+        "--hyde-agent",
+        help="Agent ID for HyDE hypothetical document generation",
+    ),
+    hyde_template: Optional[str] = typer.Option(
+        None,
+        "--hyde-template",
+        help="Template ID for HyDE hypothetical document generation",
+    ),
+    decomposition_agent: Optional[str] = typer.Option(
+        None,
+        "--decomposition-agent",
+        help="Agent ID for query decomposition",
+    ),
+    decomposition_template: Optional[str] = typer.Option(
+        None,
+        "--decomposition-template",
+        help="Template ID for query decomposition",
+    ),
+    rerank_instruction: Optional[str] = typer.Option(
+        None,
+        "-r",
+        "--rerank-instruction",
+        help="Custom instruction for reranking (e.g., 'Prioritize recent docs')",
+    ),
+    min_confidence: Optional[float] = typer.Option(
+        None,
+        "--min-confidence",
+        min=0.0,
+        max=1.0,
+        help="Minimum confidence threshold (0.0-1.0)",
+    ),
+    retrieval_k: Optional[int] = typer.Option(
+        None,
+        "--retrieval-k",
+        min=1,
+        max=1000,
+        help="Override initial candidate retrieval count",
+    ),
+    metadata_filter: Optional[str] = typer.Option(
+        None,
+        "--metadata-filter",
+        help='Filter by chunk metadata as JSON (e.g., \'{"author": "John"}\')',
+    ),
+    output: str = typer.Option(
+        "table",
+        "-o",
+        "--output",
+        help="Output format: 'table' or 'json'",
+    ),
+) -> None:
+    """Search the knowledge base.
+
+    Performs semantic search across document collections using hybrid retrieval
+    (vector + full-text search). Opt in to HyDE or query decomposition by
+    providing the corresponding agent and template IDs.
+
+    Examples:
+        ai2 knowledge search "How do I authenticate?"
+        ai2 kb search "API documentation" --collection-filter "Product*"
+        ai2 kb search "complex query" \\
+            --hyde-agent <id> --hyde-template <id> \\
+            --decomposition-agent <id> --decomposition-template <id>
+        ai2 kb search "test query" --output json
+        ai2 kb search "query" --retrieval-k 100
+        ai2 kb search "query" --metadata-filter '{"author": "John"}'
+    """
+    _execute_search_from_flags(
+        query=query,
+        collections=collections,
+        collection_filter=collection_filter,
+        tag_filter=tag_filter,
+        top_k=top_k,
+        hyde_agent=hyde_agent,
+        hyde_template=hyde_template,
+        decomposition_agent=decomposition_agent,
+        decomposition_template=decomposition_template,
+        rerank_instruction=rerank_instruction,
+        min_confidence=min_confidence,
+        retrieval_k=retrieval_k,
+        metadata_filter=metadata_filter,
+        output=output,
+    )
+
+
+def _execute_search_from_flags(
+    query: str,
+    collections: Optional[str],
+    collection_filter: Optional[str],
+    tag_filter: Optional[str],
+    top_k: int,
+    hyde_agent: Optional[str],
+    hyde_template: Optional[str],
+    decomposition_agent: Optional[str],
+    decomposition_template: Optional[str],
+    rerank_instruction: Optional[str],
+    min_confidence: Optional[float],
+    retrieval_k: Optional[int],
+    metadata_filter: Optional[str],
+    output: str,
+) -> None:
+    """Validate flags and build search request."""
+    output_format = output.lower()
+    if output_format not in ("table", "json"):
+        raise typer.BadParameter(
+            f"Invalid output format '{output}'. Valid: table, json"
+        )
+
+    collection_ids: list[UUID] | None = None
+    if collections:
+        parsed_collection_ids: list[UUID] = []
+        for cid in collections.split(","):
+            cid = cid.strip()
+            if cid:
+                parsed_collection_ids.append(validate_uuid(cid, "collection"))
+        collection_ids = parsed_collection_ids
+
+    hyde_agent_id: UUID | None = None
+    hyde_template_id: UUID | None = None
+    decomposition_agent_id: UUID | None = None
+    decomposition_template_id: UUID | None = None
+
+    if hyde_agent:
+        hyde_agent_id = validate_uuid(hyde_agent, "hyde-agent")
+    if hyde_template:
+        hyde_template_id = validate_uuid(hyde_template, "hyde-template")
+    if decomposition_agent:
+        decomposition_agent_id = validate_uuid(
+            decomposition_agent, "decomposition-agent"
+        )
+    if decomposition_template:
+        decomposition_template_id = validate_uuid(
+            decomposition_template, "decomposition-template"
+        )
+
+    parsed_metadata_filter: dict[str, Any] | None = None
+    if metadata_filter:
+        try:
+            parsed_metadata_filter = json.loads(metadata_filter)
+            if not isinstance(parsed_metadata_filter, dict):
+                raise typer.BadParameter(
+                    "--metadata-filter must be a JSON object, not "
+                    f"{type(parsed_metadata_filter).__name__}"
+                )
+        except json.JSONDecodeError as e:
+            raise typer.BadParameter(f"Invalid JSON in --metadata-filter: {e}")
+
+    request = SearchRequest(
+        query=query,
+        collection_ids=collection_ids,
+        collection_filter=collection_filter,
+        top_k=top_k,
+        metadata_filter=parsed_metadata_filter,
+        tag_filter=tag_filter,
+        source_date_from=None,
+        source_date_to=None,
+        rerank_instruction=rerank_instruction,
+        retrieval_k=retrieval_k,
+        min_retrieval_confidence=min_confidence,
+        hyde_agent_id=hyde_agent_id,
+        hyde_template_id=hyde_template_id,
+        decomposition_agent_id=decomposition_agent_id,
+        decomposition_template_id=decomposition_template_id,
+    )
+
+    _execute_search(request, output_format)
+
+
+@async_command
+async def _execute_search(request: SearchRequest, output_format: str) -> None:
+    """Execute knowledge base search."""
+    async with authenticated_client() as (_config, client):
+        response = await client.search_knowledge(request)
+
+    present_search_results(response, output_format)

cli/commands/knowledge/search/presenter.py

@@ -0,0 +1,111 @@
+"""Presenter for knowledge search output."""
+
+import json
+
+from rich.panel import Panel
+from rich.table import Table
+
+from cli.infrastructure.output import OutputService
+from alloy_runtime_types.dtos.knowledge import SearchResponse
+
+
+def present_search_results(response: SearchResponse, output_format: str) -> None:
+    """Present search results in specified format.
+
+    Args:
+        response: Search response from server
+        output_format: Output format ('table' or 'json')
+    """
+    if output_format == "json":
+        _present_json_results(response)
+    else:
+        _present_table_results(response)
+
+
+def _present_table_results(response: SearchResponse) -> None:
+    """Present search results as formatted table."""
+    output = OutputService.get()
+
+    if not response.results:
+        output.info(f"No results found for: {response.query}")
+        return
+
+    # Build summary panel
+    summary_table = Table(show_header=False, box=None, padding=(0, 1))
+    summary_table.add_column("Field", style="dim")
+    summary_table.add_column("Value")
+
+    summary_table.add_row("Query", response.query)
+    summary_table.add_row("Results", str(len(response.results)))
+    summary_table.add_row("Candidates evaluated", str(response.total_candidates))
+    summary_table.add_row("Avg relevance", f"{response.avg_relevance_score:.3f}")
+
+    # Add timing breakdown
+    timing_parts: list[str] = []
+    for key, value in response.timing_ms.items():
+        timing_parts.append(f"{key}={value}ms")
+    if timing_parts:
+        summary_table.add_row("Timing", ", ".join(timing_parts))
+
+    summary_panel = Panel(summary_table, title="Search Summary", border_style="blue")
+    output.console.print(summary_panel)
+
+    # Show transformations if applied
+    if response.transformations_applied:
+        output.console.print(
+            f"\n[dim]Transformations applied:[/dim] "
+            f"[cyan]{', '.join(response.transformations_applied)}[/cyan]"
+        )
+
+    if response.sub_queries_used:
+        output.console.print("[dim]Sub-queries used:[/dim]")
+        for i, sq in enumerate(response.sub_queries_used, 1):
+            output.console.print(f"  [cyan]{i}.[/cyan] {sq}")
+
+    # Build results table
+    output.console.print()
+    results_table = Table(title="Results", show_header=True, header_style="bold")
+    results_table.add_column("#", style="dim", width=3, justify="right")
+    results_table.add_column("Document", style="white", no_wrap=True, max_width=30)
+    results_table.add_column("Score", style="cyan", width=7, justify="right")
+    results_table.add_column("Content", style="dim", overflow="ellipsis")
+
+    low_confidence_results: list[int] = []
+    for i, result in enumerate(response.results, 1):
+        # Truncate content preview
+        content_preview = result.content.replace("\n", " ")[:100]
+        if len(result.content) > 100:
+            content_preview += "..."
+
+        # Mark low confidence results
+        score_display = f"{result.relevance_score:.3f}"
+        if result.low_confidence:
+            score_display = f"[yellow]{score_display}*[/yellow]"
+            low_confidence_results.append(i)
+
+        results_table.add_row(
+            str(i),
+            result.document_title,
+            score_display,
+            content_preview,
+        )
+
+    output.console.print(results_table)
+
+    # Show low confidence warning
+    if low_confidence_results:
+        output.console.print(
+            f"\n[yellow]* Results {', '.join(map(str, low_confidence_results))} "
+            "are below the confidence threshold[/yellow]"
+        )
+
+
+def _present_json_results(response: SearchResponse) -> None:
+    """Present search results as JSON."""
+    output = OutputService.get()
+
+    # Convert response to JSON-serializable dict
+    data = response.model_dump(mode="json")
+
+    # Pretty-print JSON
+    output.console.print_json(json.dumps(data))

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

@@ -0,0 +1,127 @@
+"""Knowledge synthesis create command implementation."""
+
+from typing import Annotated, Optional
+from uuid import UUID
+
+import typer
+
+from cli.commands.flag_utils import validate_uuid
+from cli.commands.knowledge.synthesis.create.presenter import (
+    present_synthesis_create_success,
+)
+from cli.infrastructure.command import async_command, authenticated_client
+from cli.infrastructure.kv_parser import parse_kv_pairs
+from alloy_runtime_types.dtos.knowledge import CreateSynthesisRequest
+
+
+def knowledge_synthesis_create_command(
+    topic: str = typer.Option(
+        ...,
+        "-t",
+        "--topic",
+        help="Topic to research and synthesize",
+    ),
+    collections: str = typer.Option(
+        ...,
+        "-C",
+        "--collections",
+        help="Comma-separated collection UUIDs to include",
+    ),
+    agent: str = typer.Option(
+        ...,
+        "-a",
+        "--agent",
+        help="Synthesizer agent UUID (must have rag_search tool)",
+    ),
+    template: str = typer.Option(
+        ...,
+        "-T",
+        "--template",
+        help="Synthesis template UUID (receives {{ topic }} variable)",
+    ),
+    title: Optional[str] = typer.Option(
+        None,
+        "--title",
+        help="Title for the synthesis (defaults to topic)",
+    ),
+    metadata: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            "-m",
+            "--metadata",
+            help="Metadata (key=value or key:=json). Repeatable.",
+        ),
+    ] = None,
+) -> None:
+    """Create a corpus-level synthesis.
+
+    A synthesis uses an agent with RAG tools to research a topic across
+    specified collections and generate a comprehensive response. The
+    synthesis is processed asynchronously - poll the synthesis status
+    to check for completion.
+
+    Examples:
+        ai2 knowledge synthesis create -t "API authentication methods" \\
+            -C <collection-uuid> -a <agent-uuid> -T <template-uuid>
+
+        ai2 kb synthesis create -t "Product roadmap summary" \\
+            -C <col1>,<col2> -a <agent> -T <template> --title "Q1 Roadmap"
+
+        ai2 kb synthesis create -t "Security best practices" \\
+            -C <collection> -a <agent> -T <template> -m priority=high
+    """
+    _execute_create_from_flags(
+        topic=topic,
+        collections=collections,
+        agent=agent,
+        template=template,
+        title=title,
+        metadata=metadata,
+    )
+
+
+def _execute_create_from_flags(
+    topic: str,
+    collections: str,
+    agent: str,
+    template: str,
+    title: Optional[str],
+    metadata: Optional[list[str]],
+) -> None:
+    """Build and execute synthesis creation from command flags."""
+    # Parse collection IDs
+    collection_ids: list[UUID] = []
+    for cid in collections.split(","):
+        cid = cid.strip()
+        if cid:
+            collection_ids.append(validate_uuid(cid, "collection"))
+
+    if not collection_ids:
+        raise typer.BadParameter("At least one collection UUID is required")
+
+    # Validate agent and template UUIDs
+    agent_id = validate_uuid(agent, "agent")
+    template_id = validate_uuid(template, "template")
+
+    # Parse metadata (httpie style)
+    parsed_metadata = parse_kv_pairs(metadata) if metadata else None
+
+    request = CreateSynthesisRequest(
+        topic=topic,
+        collection_ids=collection_ids,
+        synthesizer_agent_id=agent_id,
+        synthesis_template_id=template_id,
+        title=title,
+        metadata=parsed_metadata,
+    )
+
+    _execute_create(request)
+
+
+@async_command
+async def _execute_create(request: CreateSynthesisRequest) -> None:
+    """Execute the synthesis creation with the given request."""
+    async with authenticated_client() as (_config, client):
+        response = await client.create_synthesis(request)
+
+    present_synthesis_create_success(response)

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

@@ -0,0 +1,33 @@
+"""Presenter for synthesis creation 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 CreateSynthesisResponse
+
+
+def present_synthesis_create_success(response: CreateSynthesisResponse) -> None:
+    """Present successful synthesis creation.
+
+    Args:
+        response: Synthesis creation response from server
+    """
+    output = OutputService.get()
+
+    output.success("Synthesis queued for generation")
+
+    # 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 Created", border_style="green")
+    output.console.print(panel)
+
+    output.info(f"Poll status with: ai2 kb synthesis get {response.synthesis_id}")