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

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

@@ -0,0 +1,222 @@
+"""Knowledge document ingest command implementation."""
+
+from pathlib import Path
+from typing import Annotated, Optional
+from uuid import UUID
+
+import typer
+
+from cli.commands.flag_utils import (
+    require_one_of,
+    validate_document_type,
+    validate_source_type,
+)
+from cli.commands.knowledge.documents.ingest.presenter import present_ingest_success
+from cli.infrastructure.command import async_command, authenticated_client
+from cli.infrastructure.file_content import FileContentError, resolve_content
+from cli.infrastructure.kv_parser import parse_kv_pairs
+from alloy_runtime_types.dtos.knowledge import IngestDocumentRequest
+
+
+def knowledge_documents_ingest_command(
+    collection: UUID = typer.Option(
+        ...,
+        "-C",
+        "--collection",
+        help="Target collection UUID",
+    ),
+    title: str = typer.Option(
+        ...,
+        "-t",
+        "--title",
+        help="Document title",
+    ),
+    file: Optional[Path] = typer.Option(
+        None,
+        "-f",
+        "--file",
+        help="Path to document file",
+        exists=True,
+        readable=True,
+    ),
+    content: Optional[str] = typer.Option(
+        None,
+        "-c",
+        "--content",
+        help="Document content (or @file, or @- for stdin)",
+    ),
+    question_agent: Optional[UUID] = typer.Option(
+        None,
+        "-Q",
+        "--question-agent",
+        help="Agent UUID for question generation (required unless --skip-question-gen)",
+    ),
+    question_template: Optional[UUID] = typer.Option(
+        None,
+        "-T",
+        "--question-template",
+        help="Template UUID for question generation (required unless --skip-question-gen)",
+    ),
+    source_type: str = typer.Option(
+        "upload",
+        "-s",
+        "--source-type",
+        help="Source type: upload, paste, api_import, url_scrape",
+    ),
+    metadata: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            "-m",
+            "--metadata",
+            help="Metadata (key=value or key:=json). Repeatable.",
+        ),
+    ] = None,
+    tag: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            "--tag",
+            help="Hierarchical tag path (e.g., 'engineering.backend'). Repeatable.",
+        ),
+    ] = None,
+    document_type: str = typer.Option(
+        "document",
+        "-D",
+        "--document-type",
+        help="Document type for preprocessing: transcript, sales_call, markdown, document",
+    ),
+    external_id: Optional[str] = typer.Option(
+        None,
+        "-e",
+        "--external-id",
+        help="Caller-provided ID for idempotency and correlation (unique per org)",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Only preprocess - don't persist. Useful for testing preprocessing.",
+    ),
+    skip_question_gen: bool = typer.Option(
+        False,
+        "--skip-question-gen",
+        help="Skip question generation during ingestion. Makes -Q and -T optional.",
+    ),
+) -> None:
+    """Ingest a document into a knowledge collection.
+
+    Document content can be provided via:
+    - --file: Read from a file path
+    - --content: Direct text, @file reference, or @- for stdin
+
+    Document types control preprocessing:
+    - transcript: Podcasts/videos/meetings with timestamps and natural speech
+    - sales_call: Sales/customer calls with speaker labels
+    - markdown: Markdown-formatted content
+    - document: General text documents (default)
+
+    Examples:
+        ai2 knowledge documents ingest -C <uuid> -t "API Docs" -f ./api.md -Q <agent> -T <template>
+        ai2 kb documents ingest -C <uuid> -t "Notes" -c "My content" -Q <agent> -T <template>
+        cat doc.txt | ai2 kb documents ingest -C <uuid> -t "Doc" -c @- -Q <agent> -T <template>
+        ai2 kb documents ingest -C <uuid> -t "Doc" -c @notes.md -Q <agent> -T <template> -m author=John
+        ai2 kb documents ingest -C <uuid> -t "Meeting" -f meeting.vtt -D transcript -Q <agent> -T <template>
+        ai2 kb documents ingest -C <uuid> -t "Test" -f doc.md --dry-run -Q <agent> -T <template>
+    """
+    require_one_of(("--file", file), ("--content", content))
+
+    _execute_ingest_from_flags(
+        collection=collection,
+        title=title,
+        file=file,
+        content=content,
+        question_agent=question_agent,
+        question_template=question_template,
+        source_type=source_type,
+        metadata=metadata,
+        tag=tag,
+        document_type=document_type,
+        external_id=external_id,
+        dry_run=dry_run,
+        skip_question_gen=skip_question_gen,
+    )
+
+
+def _execute_ingest_from_flags(
+    collection: UUID,
+    title: str,
+    file: Optional[Path],
+    content: Optional[str],
+    question_agent: Optional[UUID],
+    question_template: Optional[UUID],
+    source_type: str,
+    metadata: Optional[list[str]],
+    tag: Optional[list[str]],
+    document_type: str,
+    external_id: Optional[str],
+    dry_run: bool,
+    skip_question_gen: bool,
+) -> None:
+    """Build and execute document ingestion from command flags."""
+    # Validate source type
+    validated_source_type = validate_source_type(source_type)
+
+    # Validate document type
+    validated_document_type = validate_document_type(document_type)
+
+    # Resolve content from file or inline
+    if file:
+        if not file.is_file():
+            raise typer.BadParameter(f"Not a file: {file}")
+        try:
+            document_content = file.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            raise typer.BadParameter(
+                f"File is not valid UTF-8 text: {file}. Only text files are supported."
+            )
+    else:
+        try:
+            document_content = resolve_content(content) or ""
+        except FileContentError as e:
+            raise typer.BadParameter(str(e))
+
+    if not document_content.strip():
+        raise typer.BadParameter("Document content cannot be empty")
+
+    # Validate question generation requirements
+    if not skip_question_gen:
+        if question_agent is None:
+            raise typer.BadParameter(
+                "--question-agent (-Q) is required unless --skip-question-gen is set"
+            )
+        if question_template is None:
+            raise typer.BadParameter(
+                "--question-template (-T) is required unless --skip-question-gen is set"
+            )
+
+    # Parse metadata (httpie style)
+    parsed_metadata = parse_kv_pairs(metadata) if metadata else None
+
+    request = IngestDocumentRequest(
+        collection_id=collection,
+        title=title,
+        content=document_content,
+        question_gen_agent_id=question_agent,
+        question_gen_template_id=question_template,
+        source_type=validated_source_type,
+        document_type=validated_document_type,  # type: ignore[arg-type]
+        metadata=parsed_metadata,
+        tags=tag,
+        external_id=external_id,
+        dry_run=dry_run,
+        skip_question_generation=skip_question_gen,
+    )
+
+    _execute_ingest(request)
+
+
+@async_command
+async def _execute_ingest(request: IngestDocumentRequest) -> None:
+    """Execute the document ingestion with the given request."""
+    async with authenticated_client() as (_config, client):
+        response = await client.ingest_document(request)
+
+    present_ingest_success(response)

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

@@ -0,0 +1,41 @@
+"""Presenter for document ingest 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 IngestDocumentResponse
+
+
+def present_ingest_success(response: IngestDocumentResponse) -> None:
+    """Present successful document ingestion (queued for processing).
+
+    Args:
+        response: Document ingestion response from server
+    """
+    output = OutputService.get()
+
+    if response.document_id is None:
+        output.info("Dry run complete - document not persisted")
+    else:
+        output.info("Document queued for processing")
+
+    table = Table(show_header=False, box=None, padding=(0, 1))
+    table.add_column("Field", style="dim")
+    table.add_column("Value")
+
+    if response.document_id is not None:
+        table.add_row("Document ID", format_uuid(response.document_id, short=False))
+    table.add_row("Title", response.title)
+    table.add_row("Status", f"[yellow]{response.status}[/yellow]")
+
+    if response.document_id is not None:
+        table.add_row("", "")
+        table.add_row(
+            "[dim]Next Step[/dim]",
+            "[dim]Poll with: ai2 knowledge documents get <id>[/dim]",
+        )
+
+    panel = Panel(table, title=f"Document: {response.title}", border_style="blue")
+    output.console.print(panel)

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

@@ -0,0 +1,69 @@
+"""Knowledge documents list command implementation."""
+
+import typer
+
+from cli.commands.knowledge.documents.list.presenter import present_documents_list
+from cli.infrastructure.command import async_command, authenticated_client
+
+
+def knowledge_documents_list_command(
+    collection: str | None = typer.Option(
+        None,
+        "-C",
+        "--collection",
+        help="Filter by collection ID or name",
+    ),
+    status: str | None = typer.Option(
+        None,
+        "-s",
+        "--status",
+        help="Filter by status: pending|processing|completed|failed",
+    ),
+    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 documents in the knowledge base.
+
+    Examples:
+        ai2 knowledge documents list
+        ai2 kb documents list -C my-collection
+        ai2 kb documents list -s completed -l 20
+        ai2 kb documents list --status failed
+    """
+    _execute_list(
+        collection_id=collection,
+        processing_status=status,
+        limit=limit,
+        offset=offset,
+    )
+
+
+@async_command
+async def _execute_list(
+    collection_id: str | None,
+    processing_status: str | None,
+    limit: int,
+    offset: int,
+) -> None:
+    """Execute list documents operation."""
+    async with authenticated_client() as (_config, client):
+        response = await client.list_documents(
+            limit=limit,
+            offset=offset,
+            collection_id=collection_id,
+            processing_status=processing_status,
+        )
+
+    present_documents_list(response)

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

@@ -0,0 +1,86 @@
+"""Presenter for knowledge documents list command output."""
+
+from alloy_runtime_types.dtos.knowledge import ListDocumentsResponse
+
+from cli.infrastructure.output import OutputService
+from cli.infrastructure.renderers.list_renderer import ColumnConfig
+
+
+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_documents_list(response: ListDocumentsResponse) -> None:
+    """Present list of documents with Rich table formatting.
+
+    Args:
+        response: List documents response from server
+    """
+    output = OutputService.get()
+
+    if not response.documents:
+        output.info("No documents found")
+        return
+
+    columns = [
+        ColumnConfig(
+            source_field="id",
+            header_label="ID",
+            compact_line=1,
+            compact_style="cyan",
+        ),
+        ColumnConfig(
+            source_field="processing_status",
+            header_label="Status",
+            formatter=_format_status,
+            compact_line=1,
+        ),
+        ColumnConfig(
+            source_field="chunks_count",
+            header_label="Chunks",
+            align="right",
+            compact_line=1,
+            compact_style="blue",
+        ),
+        ColumnConfig(
+            source_field="questions_generated",
+            header_label="Questions",
+            align="right",
+            compact_line=1,
+            compact_style="magenta",
+        ),
+        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="title",
+            header_label="Title",
+            formatter=lambda x: x[:60] + "..." if x and len(x) > 60 else (x or "-"),
+            compact_line=2,
+            compact_style="white bold",
+        ),
+        ColumnConfig(
+            source_field="collection_id",
+            header_label="Collection",
+            formatter=lambda x: str(x)[:8] + "..." if x else "-",
+            compact_line=2,
+            compact_style="dim",
+        ),
+    ]
+
+    output.table(
+        items=response.documents,  # type: ignore[arg-type]
+        title=f"Documents ({response.total})",
+        columns=columns,
+    )

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

@@ -0,0 +1,102 @@
+"""Knowledge documents reingest command implementation."""
+
+from typing import Optional
+from uuid import UUID
+
+import typer
+
+from cli.commands.flag_utils import validate_uuid
+from cli.commands.knowledge.documents.reingest.presenter import (
+    present_reingest_result,
+)
+from cli.infrastructure.command import async_command, authenticated_client
+from alloy_runtime_types.dtos.knowledge import ReingestDocumentRequest
+
+
+def knowledge_documents_reingest_command(
+    document_id: str = typer.Argument(
+        ...,
+        help="Document UUID",
+    ),
+    question_gen_agent: Optional[str] = typer.Option(
+        None,
+        "--question-gen-agent",
+        help="Agent UUID for question generation",
+    ),
+    question_gen_template: Optional[str] = typer.Option(
+        None,
+        "--question-gen-template",
+        help="Template UUID for question generation",
+    ),
+    document_type: Optional[str] = typer.Option(
+        None,
+        "--document-type",
+        help="Document type for preprocessing: transcript, markdown, document",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Preview changes without committing",
+    ),
+) -> None:
+    """Reingest a document with new processing parameters.
+
+    Re-processes an existing document, optionally with updated question
+    generation agents, templates, or document type. The document's
+    original content is preserved; only derived data is regenerated.
+
+    Use --dry-run to preview preprocessing changes without committing.
+
+    Examples:
+        ai2 knowledge documents reingest <uuid>
+        ai2 kb documents reingest <uuid> --document-type transcript
+        ai2 kb documents reingest <uuid> --question-gen-agent <agent-uuid> --dry-run
+    """
+    _execute_reingest(
+        document_id=document_id,
+        question_gen_agent=question_gen_agent,
+        question_gen_template=question_gen_template,
+        document_type=document_type,
+        dry_run=dry_run,
+    )
+
+
+@async_command
+async def _execute_reingest(
+    document_id: str,
+    question_gen_agent: Optional[str],
+    question_gen_template: Optional[str],
+    document_type: Optional[str],
+    dry_run: bool,
+) -> None:
+    """Execute document reingest operation."""
+
+    agent_id: UUID | None = None
+    if question_gen_agent is not None:
+        agent_id = validate_uuid(question_gen_agent, "question-gen-agent")
+
+    template_id: UUID | None = None
+    if question_gen_template is not None:
+        template_id = validate_uuid(question_gen_template, "question-gen-template")
+
+    valid_types = ("transcript", "markdown", "document")
+    if document_type is not None and document_type not in valid_types:
+        raise typer.BadParameter(
+            f"Invalid document type '{document_type}'. "
+            f"Must be one of: {', '.join(valid_types)}"
+        )
+
+    request = ReingestDocumentRequest(
+        question_gen_agent_id=agent_id,
+        question_gen_template_id=template_id,
+        document_type=document_type,  # type: ignore[arg-type]
+        dry_run=dry_run,
+    )
+
+    async with authenticated_client() as (_config, client):
+        response = await client.reingest_document(
+            document_id=document_id,
+            request=request,
+        )
+
+    present_reingest_result(response)

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

@@ -0,0 +1,70 @@
+"""Presenter for knowledge document reingest command 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 ReingestDocumentResponse
+
+
+def _format_reingest_status(status: str) -> str:
+    """Format reingest status with color."""
+    status_colors = {
+        "pending": "[yellow]pending[/]",
+        "dry_run_complete": "[blue]dry_run_complete[/]",
+    }
+    return status_colors.get(status, status)
+
+
+def present_reingest_result(response: ReingestDocumentResponse) -> None:
+    """Present document reingest result.
+
+    Args:
+        response: ReingestDocumentResponse from server
+    """
+    output = OutputService.get()
+
+    if response.dry_run:
+        output.info("Dry run — no changes committed")
+    else:
+        output.success("Document queued for reingestion")
+
+    table = Table(show_header=False, box=None, padding=(0, 1))
+    table.add_column("Field", style="dim")
+    table.add_column("Value")
+
+    table.add_row("Document ID", format_uuid(response.document_id, short=False))
+    table.add_row("Status", _format_reingest_status(response.status))
+    table.add_row("Message", response.message)
+    table.add_row("Document Type", response.document_type)
+
+    if response.question_gen_agent_id:
+        table.add_row(
+            "Question Gen Agent",
+            format_uuid(response.question_gen_agent_id, short=False),
+        )
+    if response.question_gen_template_id:
+        table.add_row(
+            "Question Gen Template",
+            format_uuid(response.question_gen_template_id, short=False),
+        )
+
+    if response.dry_run and response.diff_stats:
+        table.add_row("Diff Stats", str(response.diff_stats))
+
+    if response.rejected:
+        table.add_row("Rejected", f"[red]{response.rejection_reason}[/]")
+
+    border_style = "blue" if response.dry_run else "green"
+    title = "Reingest Dry Run" if response.dry_run else "Document Reingested"
+    panel = Panel(table, title=title, border_style=border_style)
+    output.console.print(panel)
+
+    if response.dry_run and response.diff_unified:
+        diff_panel = Panel(
+            response.diff_unified,
+            title="Preprocessing Diff",
+            border_style="cyan",
+        )
+        output.console.print(diff_panel)

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

@@ -0,0 +1,85 @@
+"""Knowledge documents update metadata command implementation."""
+
+import json
+from typing import Any, cast
+
+import typer
+
+from cli.commands.knowledge.documents.update.presenter import (
+    present_update_metadata_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 UpdateDocumentMetadataRequest
+
+
+def knowledge_documents_update_command(
+    document_id: str = typer.Argument(
+        ...,
+        help="Document UUID",
+    ),
+    metadata: str = typer.Option(
+        ...,
+        "--metadata",
+        help="Metadata JSON object (or @file.json)",
+    ),
+    metadata_mode: str = typer.Option(
+        "merge",
+        "--metadata-mode",
+        help="Metadata update mode: 'merge' (default) or 'replace'",
+    ),
+) -> None:
+    """Update a document's metadata.
+
+    The --metadata flag accepts a JSON string or @file reference.
+    Use --metadata-mode to control whether keys are merged with
+    existing metadata (default) or replace it entirely.
+
+    Examples:
+        ai2 knowledge documents update <uuid> --metadata '{"key": "value"}'
+        ai2 kb documents update <uuid> --metadata @meta.json --metadata-mode replace
+    """
+    _execute_update(
+        document_id=document_id,
+        metadata_raw=metadata,
+        metadata_mode=metadata_mode,
+    )
+
+
+@async_command
+async def _execute_update(
+    document_id: str,
+    metadata_raw: str,
+    metadata_mode: str,
+) -> None:
+    """Execute 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'."
+        )
+
+    resolved = resolve_content_or_raise(metadata_raw)
+    if resolved is None:
+        raise typer.BadParameter("--metadata is required")
+
+    try:
+        parsed = json.loads(resolved)
+    except json.JSONDecodeError as e:
+        raise typer.BadParameter(f"Invalid JSON for --metadata: {e}")
+    if not isinstance(parsed, dict):
+        raise typer.BadParameter("--metadata must be a JSON object")
+    metadata_dict = cast(dict[str, Any], parsed)
+
+    request = UpdateDocumentMetadataRequest(
+        metadata=metadata_dict,
+        metadata_mode=metadata_mode,  # type: ignore[arg-type]
+    )
+
+    async with authenticated_client() as (_config, client):
+        response = await client.update_document_metadata(
+            document_id=document_id,
+            request=request,
+        )
+
+    present_update_metadata_result(response)