applied-cli 0.1.0__py3-none-any.whl

applied_cli/commands/insights.py

@@ -0,0 +1,614 @@
+import json
+import time
+from typing import Any, Optional
+
+import typer
+
+from applied_cli.commands._parsers import (
+    parse_csv_list,
+    parse_optional_bool,
+    validate_uuid,
+    validate_uuid_list,
+)
+from applied_cli.error_reporting import render_api_error
+from applied_cli.http import (
+    APIError,
+    get_insights_report,
+    get_insights_status,
+    insights_followup,
+    insights_generate,
+    list_insights_reports,
+)
+from applied_cli.runtime import resolve_runtime
+
+app = typer.Typer(help="Generate and inspect analytics insights reports.")
+
+
+def _emit(payload: Any, output_json: bool) -> None:
+    if output_json:
+        typer.echo(json.dumps(payload, indent=2, default=str))
+        return
+    if isinstance(payload, list):
+        if not payload:
+            typer.echo("No results.")
+            return
+        for row in payload:
+            if not isinstance(row, dict):
+                typer.echo(str(row))
+                continue
+            items: list[str] = []
+            report_id = row.get("reportId") or row.get("id")
+            if report_id:
+                items.append(f"report_id={report_id}")
+            title = row.get("title")
+            if title:
+                items.append(f"title={title}")
+            status = row.get("status")
+            if status:
+                items.append(f"status={status}")
+            findings = row.get("findingsCount")
+            if findings is not None:
+                items.append(f"findings={findings}")
+            conversations = row.get("conversationsAnalyzed")
+            if conversations is not None:
+                items.append(f"conversations={conversations}")
+            typer.echo(" | ".join(items) if items else str(row))
+        return
+    if isinstance(payload, dict):
+        items = []
+        report_id = payload.get("reportId")
+        if report_id:
+            items.append(f"report_id={report_id}")
+        status = payload.get("status")
+        if status:
+            items.append(f"status={status}")
+        title = payload.get("title")
+        if title:
+            items.append(f"title={title}")
+        findings = payload.get("findingsCount")
+        if findings is not None:
+            items.append(f"findings={findings}")
+        conversations = payload.get("conversationsAnalyzed")
+        if conversations is not None:
+            items.append(f"conversations={conversations}")
+        if items:
+            typer.echo("result=success | " + " | ".join(items))
+            return
+    typer.echo(str(payload))
+
+
+def _build_filters(
+    *,
+    agent_ids: list[str],
+    topic_ids: list[str],
+    intent_ids: list[str],
+    resolutions: list[str],
+    conversation_types: list[str],
+    user_ids: list[str],
+    tags: list[str],
+    directions: list[str],
+    flags: list[str],
+    score_gte: Optional[int],
+    score_lte: Optional[int],
+    is_test: Optional[bool],
+) -> dict[str, Any]:
+    filters: dict[str, Any] = {}
+    if agent_ids:
+        filters["agent__in"] = ",".join(agent_ids)
+    if topic_ids:
+        filters["label__in"] = ",".join(topic_ids)
+    if intent_ids:
+        filters["sublabel__in"] = ",".join(intent_ids)
+    if resolutions:
+        filters["resolution__in"] = ",".join(resolutions)
+    if conversation_types:
+        filters["type__in"] = ",".join(conversation_types)
+    if user_ids:
+        filters["user__in"] = ",".join(user_ids)
+    if tags:
+        filters["tags__in"] = ",".join(tags)
+    if directions:
+        filters["direction__in"] = ",".join(directions)
+    if flags:
+        filters["flags__in"] = ",".join(flags)
+    if score_gte is not None:
+        filters["score__gte"] = score_gte
+    if score_lte is not None:
+        filters["score__lte"] = score_lte
+    if is_test is not None:
+        filters["is_test"] = is_test
+    return filters
+
+
+def _wait_for_report_completion(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    report_id: str,
+    poll_seconds: float,
+    max_wait_seconds: float,
+) -> dict[str, Any]:
+    deadline = time.monotonic() + max_wait_seconds
+    last_status: dict[str, Any] = {}
+    while time.monotonic() < deadline:
+        try:
+            last_status = get_insights_status(
+                base_url=base_url,
+                shop_id=shop_id,
+                api_token=api_token,
+                report_id=report_id,
+            )
+        except APIError as exc:
+            typer.echo(render_api_error(exc, action="poll insights status"), err=True)
+            raise typer.Exit(code=1) from exc
+
+        status_value = str(last_status.get("status") or "").lower()
+        if status_value in {"completed", "failed"}:
+            return last_status
+        time.sleep(poll_seconds)
+
+    return {
+        "reportId": report_id,
+        "status": "generating",
+        "message": "Timed out waiting for completion. Re-run `applied-cli insights status --report-id <uuid>`.",
+        "last_status": last_status,
+    }
+
+
+def _wait_and_emit_report(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    report_id: str,
+    poll_seconds: float,
+    max_wait_seconds: float,
+    output_json: bool,
+) -> None:
+    status_payload = _wait_for_report_completion(
+        base_url=base_url,
+        shop_id=shop_id,
+        api_token=api_token,
+        report_id=report_id,
+        poll_seconds=poll_seconds,
+        max_wait_seconds=max_wait_seconds,
+    )
+    status_value = str(status_payload.get("status") or "").lower()
+    if status_value == "completed":
+        try:
+            report = get_insights_report(
+                base_url=base_url,
+                shop_id=shop_id,
+                api_token=api_token,
+                report_id=report_id,
+            )
+        except APIError as exc:
+            typer.echo(render_api_error(exc, action="fetch insights report"), err=True)
+            raise typer.Exit(code=1) from exc
+        _emit(report, output_json)
+        return
+
+    _emit(status_payload, output_json)
+    raise typer.Exit(code=1)
+
+
+@app.command(
+    "run",
+    help=(
+        "Generate an insights report. Example: applied-cli insights run "
+        "--query 'top issues in last 30 days' --agent-ids <uuid> --wait"
+    ),
+)
+def run_cmd(
+    query: Optional[str] = typer.Option(
+        None,
+        "--query",
+        "--instruction",
+        help="Optional natural-language analysis question.",
+    ),
+    date_range: str = typer.Option(
+        "relative:-14d,",
+        "--date-range",
+        help="Date range, e.g. relative:-30d, or ISO start,end.",
+    ),
+    data_source: str = typer.Option(
+        "conversations",
+        "--data-source",
+        help="Data source: conversations or tickets.",
+    ),
+    agent_ids_raw: Optional[str] = typer.Option(
+        None,
+        "--agent-ids",
+        help="Comma-separated agent UUIDs.",
+    ),
+    topic_ids_raw: Optional[str] = typer.Option(
+        None,
+        "--topic-ids",
+        help="Comma-separated topic UUIDs.",
+    ),
+    intent_ids_raw: Optional[str] = typer.Option(
+        None,
+        "--intent-ids",
+        help="Comma-separated intent UUIDs.",
+    ),
+    resolutions_raw: Optional[str] = typer.Option(
+        None,
+        "--resolutions",
+        help="Comma-separated values like escalated,human,soft,hard.",
+    ),
+    conversation_types_raw: Optional[str] = typer.Option(
+        None,
+        "--types",
+        help="Comma-separated conversation types: web_chat,email,sms,phone_call,web_call,comments,form.",
+    ),
+    user_ids_raw: Optional[str] = typer.Option(
+        None,
+        "--user-ids",
+        help="Comma-separated assignee/user UUIDs.",
+    ),
+    tags_raw: Optional[str] = typer.Option(
+        None,
+        "--tags",
+        help="Comma-separated tags.",
+    ),
+    directions_raw: Optional[str] = typer.Option(
+        None,
+        "--directions",
+        help="Comma-separated directions (e.g. inbound,outbound).",
+    ),
+    flags_raw: Optional[str] = typer.Option(
+        None,
+        "--flags",
+        help="Comma-separated conversation flags.",
+    ),
+    score_gte: Optional[int] = typer.Option(
+        None,
+        "--score-gte",
+        help="Minimum CSAT score.",
+    ),
+    score_lte: Optional[int] = typer.Option(
+        None,
+        "--score-lte",
+        help="Maximum CSAT score.",
+    ),
+    is_test_raw: Optional[str] = typer.Option(
+        None,
+        "--is-test",
+        help="Filter test conversations: true/false.",
+    ),
+    conversation_ids_raw: Optional[str] = typer.Option(
+        None,
+        "--conversation-ids",
+        help="Optional comma-separated conversation UUIDs to scope report.",
+    ),
+    wait: bool = typer.Option(
+        False,
+        "--wait/--no-wait",
+        help="Poll until completed/failed.",
+    ),
+    poll_seconds: float = typer.Option(
+        5.0,
+        "--poll-seconds",
+        help="Polling interval when --wait is set.",
+    ),
+    max_wait_seconds: float = typer.Option(
+        600.0,
+        "--max-wait-seconds",
+        help="Max wait duration for --wait.",
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    if data_source not in {"conversations", "tickets"}:
+        raise typer.BadParameter("data-source must be one of: conversations, tickets.")
+    if poll_seconds <= 0:
+        raise typer.BadParameter("poll-seconds must be > 0.")
+    if max_wait_seconds <= 0:
+        raise typer.BadParameter("max-wait-seconds must be > 0.")
+    if score_gte is not None and score_lte is not None and score_gte > score_lte:
+        raise typer.BadParameter("score-gte cannot be greater than score-lte.")
+
+    agent_ids = parse_csv_list(agent_ids_raw)
+    topic_ids = parse_csv_list(topic_ids_raw)
+    intent_ids = parse_csv_list(intent_ids_raw)
+    user_ids = parse_csv_list(user_ids_raw)
+    conversation_ids = parse_csv_list(conversation_ids_raw)
+    resolutions = parse_csv_list(resolutions_raw)
+    conversation_types = parse_csv_list(conversation_types_raw)
+    tags = parse_csv_list(tags_raw)
+    directions = parse_csv_list(directions_raw)
+    flags = parse_csv_list(flags_raw)
+    is_test = parse_optional_bool(is_test_raw, field_name="is-test")
+
+    validate_uuid_list(
+        [*agent_ids, *topic_ids, *intent_ids, *user_ids, *conversation_ids],
+        field_name="uuid",
+    )
+
+    filters = _build_filters(
+        agent_ids=agent_ids,
+        topic_ids=topic_ids,
+        intent_ids=intent_ids,
+        resolutions=resolutions,
+        conversation_types=conversation_types,
+        user_ids=user_ids,
+        tags=tags,
+        directions=directions,
+        flags=flags,
+        score_gte=score_gte,
+        score_lte=score_lte,
+        is_test=is_test,
+    )
+
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        generated = insights_generate(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            instruction=query,
+            date_range=date_range,
+            filters=filters if filters else None,
+            conversation_ids=conversation_ids if conversation_ids else None,
+            data_source=data_source,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="run insights report"), err=True)
+        raise typer.Exit(code=1) from exc
+
+    report_id = str(generated.get("reportId") or "")
+    if not wait or not report_id:
+        _emit(generated, output_json)
+        return
+
+    _wait_and_emit_report(
+        base_url=resolved_base_url,
+        shop_id=resolved_shop_id,
+        api_token=resolved_token,
+        report_id=report_id,
+        poll_seconds=poll_seconds,
+        max_wait_seconds=max_wait_seconds,
+        output_json=output_json,
+    )
+
+
+@app.command(
+    "followup",
+    help=(
+        "Run a follow-up insights report on a parent report thread. Example: "
+        "applied-cli insights followup --report-id <uuid> --query "
+        "'break down refund complaints by intent' --wait"
+    ),
+)
+def followup_cmd(
+    report_id: str = typer.Option(
+        ...,
+        "--report-id",
+        "--parent-report-id",
+        "--id",
+        help="Parent insights report UUID.",
+    ),
+    query: str = typer.Option(
+        ...,
+        "--query",
+        "--instruction",
+        help="Follow-up analysis question.",
+    ),
+    date_range: Optional[str] = typer.Option(
+        None,
+        "--date-range",
+        help="Optional override date range, e.g. relative:-30d, or ISO start,end.",
+    ),
+    conversation_ids_raw: Optional[str] = typer.Option(
+        None,
+        "--conversation-ids",
+        help="Optional comma-separated conversation UUIDs to scope follow-up.",
+    ),
+    wait: bool = typer.Option(
+        False,
+        "--wait/--no-wait",
+        help="Poll until completed/failed.",
+    ),
+    poll_seconds: float = typer.Option(
+        5.0,
+        "--poll-seconds",
+        help="Polling interval when --wait is set.",
+    ),
+    max_wait_seconds: float = typer.Option(
+        600.0,
+        "--max-wait-seconds",
+        help="Max wait duration for --wait.",
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    if not query.strip():
+        raise typer.BadParameter("query cannot be empty.")
+    if poll_seconds <= 0:
+        raise typer.BadParameter("poll-seconds must be > 0.")
+    if max_wait_seconds <= 0:
+        raise typer.BadParameter("max-wait-seconds must be > 0.")
+    validate_uuid(report_id, field_name="report-id")
+
+    conversation_ids = parse_csv_list(conversation_ids_raw)
+    validate_uuid_list(conversation_ids, field_name="conversation-id")
+
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        generated = insights_followup(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            instruction=query,
+            parent_report_id=report_id,
+            date_range=date_range,
+            conversation_ids=conversation_ids if conversation_ids else None,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="run insights follow-up"), err=True)
+        raise typer.Exit(code=1) from exc
+
+    followup_report_id = str(generated.get("reportId") or "")
+    if not wait or not followup_report_id:
+        _emit(generated, output_json)
+        return
+
+    _wait_and_emit_report(
+        base_url=resolved_base_url,
+        shop_id=resolved_shop_id,
+        api_token=resolved_token,
+        report_id=followup_report_id,
+        poll_seconds=poll_seconds,
+        max_wait_seconds=max_wait_seconds,
+        output_json=output_json,
+    )
+
+
+@app.command(
+    "status",
+    help=(
+        "Check report generation status. Example: applied-cli insights status "
+        "--report-id <uuid>"
+    ),
+)
+def status_cmd(
+    report_id: str = typer.Option(
+        ...,
+        "--report-id",
+        "--id",
+        help="Insights report UUID.",
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    validate_uuid(report_id, field_name="report-id")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        status_data = get_insights_status(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            report_id=report_id,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="get insights status"), err=True)
+        raise typer.Exit(code=1) from exc
+    _emit(status_data, output_json)
+
+
+@app.command(
+    "reports",
+    help=(
+        "List report history. Example: applied-cli insights reports --status completed"
+    ),
+)
+def reports_cmd(
+    status: Optional[str] = typer.Option(
+        None,
+        "--status",
+        help="Optional status filter: generating, completed, failed.",
+    ),
+    configuration_id: Optional[str] = typer.Option(
+        None,
+        "--configuration-id",
+        help="Optional configuration UUID filter.",
+    ),
+    parent_report_id: Optional[str] = typer.Option(
+        None,
+        "--parent-report-id",
+        help="Optional parent report UUID filter.",
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    if status and status not in {"generating", "completed", "failed"}:
+        raise typer.BadParameter("status must be one of: generating, completed, failed.")
+    if configuration_id:
+        validate_uuid(configuration_id, field_name="configuration-id")
+    if parent_report_id:
+        validate_uuid(parent_report_id, field_name="parent-report-id")
+
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        rows = list_insights_reports(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            status=status,
+            configuration_id=configuration_id,
+            parent_report_id=parent_report_id,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="list insights reports"), err=True)
+        raise typer.Exit(code=1) from exc
+    _emit(rows, output_json)
+
+
+@app.command(
+    "describe",
+    help=(
+        "Describe a report including generated findings. Example: applied-cli insights "
+        "describe --report-id <uuid>"
+    ),
+)
+@app.command(
+    "show",
+    help=(
+        "Show a report including generated findings. Example: applied-cli insights show "
+        "--report-id <uuid>"
+    ),
+)
+def show_cmd(
+    report_id: str = typer.Option(
+        ...,
+        "--report-id",
+        "--id",
+        help="Insights report UUID.",
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    base_url: Optional[str] = typer.Option(None, help="Applied base URL."),
+    shop_id: Optional[str] = typer.Option(None, help="Target shop UUID."),
+    api_token: Optional[str] = typer.Option(None, help="Applied API token."),
+) -> None:
+    validate_uuid(report_id, field_name="report-id")
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        payload = get_insights_report(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            report_id=report_id,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="show insights report"), err=True)
+        raise typer.Exit(code=1) from exc
+    _emit(payload, output_json)