applied-cli 0.1.0__py3-none-any.whl

applied_cli/commands/intents.py

@@ -0,0 +1,447 @@
+import json
+from typing import Any, Optional
+
+import typer
+
+from applied_cli.error_reporting import render_api_error
+from applied_cli.http import APIError, get_conversation, list_conversations, list_property_choices
+from applied_cli.runtime import resolve_runtime
+
+app = typer.Typer(
+    help="Manage shop taxonomy: topics and intents for conversation classification."
+)
+
+_CHANNEL_TO_CONVERSATION_TYPE = {
+    "chat": "web_chat",
+    "email": "email",
+    "sms": "sms",
+}
+
+
+def _parse_channels(raw: str) -> list[str]:
+    channels = [item.strip().lower() for item in raw.split(",") if item.strip()]
+    if not channels:
+        raise typer.BadParameter("channels must include at least one value.")
+    invalid = [item for item in channels if item not in _CHANNEL_TO_CONVERSATION_TYPE]
+    if invalid:
+        raise typer.BadParameter(
+            f"Unsupported channel(s): {', '.join(invalid)}. Expected: chat,email,sms."
+        )
+    return channels
+
+
+def _collect_intents(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    include_flags: bool,
+) -> list[dict[str, Any]]:
+    choices = list_property_choices(
+        base_url=base_url,
+        shop_id=shop_id,
+        api_token=api_token,
+        ordering="name",
+    )
+    by_id = {str(row.get("id")): row for row in choices if row.get("id")}
+    intents: list[dict[str, Any]] = []
+    for row in choices:
+        parent = row.get("parent_choice")
+        if not isinstance(parent, str):
+            continue
+        is_flag = bool(row.get("is_flag"))
+        if is_flag and not include_flags:
+            continue
+        parent_row = by_id.get(parent, {})
+        topic = str(parent_row.get("name") or "(none)")
+        intents.append(
+            {
+                "topic": topic,
+                "intent": str(row.get("name") or "(none)"),
+                "intent_id": str(row.get("id")),
+                "topic_id": parent,
+                "is_flag": is_flag,
+            }
+        )
+    if intents:
+        intents.sort(key=lambda item: (item["topic"].lower(), item["intent"].lower()))
+        return intents
+
+    # Fallback for shops where taxonomy endpoints are restricted:
+    # infer intent ids from audit conversation feed, then resolve names via conversation detail.
+    sample_by_intent: dict[str, str] = {}
+    offset = 0
+    limit = 200
+    while True:
+        rows = list_conversations(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+            response_type="audit",
+            limit=limit,
+            offset=offset,
+            ordering="-created_at",
+        )
+        if not rows:
+            break
+        for row in rows:
+            sublabel_id = row.get("sublabel_id")
+            conversation_id = row.get("id")
+            if (
+                isinstance(sublabel_id, str)
+                and sublabel_id
+                and isinstance(conversation_id, str)
+                and conversation_id
+                and sublabel_id not in sample_by_intent
+            ):
+                sample_by_intent[sublabel_id] = conversation_id
+        if len(rows) < limit:
+            break
+        offset += limit
+
+    for intent_id, conversation_id in sample_by_intent.items():
+        detail = get_conversation(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+            conversation_id=conversation_id,
+        )
+        label = detail.get("label")
+        sublabel = detail.get("sublabel")
+        topic_name = (
+            str(label.get("name"))
+            if isinstance(label, dict) and isinstance(label.get("name"), str)
+            else "(none)"
+        )
+        intent_name = (
+            str(sublabel.get("name"))
+            if isinstance(sublabel, dict) and isinstance(sublabel.get("name"), str)
+            else "(none)"
+        )
+        topic_id = (
+            str(label.get("id"))
+            if isinstance(label, dict) and label.get("id")
+            else ""
+        )
+        intents.append(
+            {
+                "topic": topic_name,
+                "intent": intent_name,
+                "intent_id": intent_id,
+                "topic_id": topic_id,
+                "is_flag": False,
+            }
+        )
+    intents.sort(key=lambda item: (item["topic"].lower(), item["intent"].lower()))
+    return intents
+
+
+def _collect_test_counts(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    channels: list[str],
+    agent_id: Optional[str],
+) -> dict[str, dict[str, int]]:
+    out: dict[str, dict[str, int]] = {channel: {} for channel in channels}
+    for channel in channels:
+        conversation_type = _CHANNEL_TO_CONVERSATION_TYPE[channel]
+        offset = 0
+        limit = 200
+        while True:
+            rows = list_conversations(
+                base_url=base_url,
+                shop_id=shop_id,
+                api_token=api_token,
+                agent_id=agent_id,
+                conversation_type=conversation_type,
+                response_type="audit",
+                is_test=True,
+                limit=limit,
+                offset=offset,
+                ordering="-created_at",
+            )
+            if not rows:
+                break
+            for row in rows:
+                sublabel_id = row.get("sublabel_id")
+                if isinstance(sublabel_id, str) and sublabel_id:
+                    out[channel][sublabel_id] = out[channel].get(sublabel_id, 0) + 1
+            if len(rows) < limit:
+                break
+            offset += limit
+    return out
+
+
+@app.command(
+    "list",
+    help=(
+        "List topic/intents available in shop taxonomy. Example: applied-cli taxonomy list "
+        "--include-flags"
+    ),
+)
+def list_cmd(
+    include_flags: bool = typer.Option(
+        False, "--include-flags", help="Include flag-like intents (is_flag=true)."
+    ),
+    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:
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        intents = _collect_intents(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            include_flags=include_flags,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="list intents"), err=True)
+        raise typer.Exit(code=1) from exc
+
+    payload = {
+        "shop_id": resolved_shop_id,
+        "intent_count": len(intents),
+        "intents": intents,
+    }
+    if output_json:
+        typer.echo(json.dumps(payload, indent=2, default=str))
+        return
+    if not intents:
+        typer.echo("No intents found.")
+        return
+    for row in intents:
+        typer.echo(
+            f"topic={row['topic']} | intent={row['intent']} | intent_id={row['intent_id']} | is_flag={row['is_flag']}"
+        )
+
+
+def _build_intent_coverage_payload(
+    *,
+    base_url: str,
+    shop_id: str,
+    api_token: str,
+    channels: list[str],
+    min_tests_per_channel: int,
+    include_flags: bool,
+    agent_id: Optional[str],
+) -> dict[str, Any]:
+    intents = _collect_intents(
+        base_url=base_url,
+        shop_id=shop_id,
+        api_token=api_token,
+        include_flags=include_flags,
+    )
+    counts = _collect_test_counts(
+        base_url=base_url,
+        shop_id=shop_id,
+        api_token=api_token,
+        channels=channels,
+        agent_id=agent_id,
+    )
+
+    rows: list[dict[str, Any]] = []
+    for item in intents:
+        channel_counts = {channel: counts[channel].get(item["intent_id"], 0) for channel in channels}
+        missing_channels = [
+            channel
+            for channel, value in channel_counts.items()
+            if value < min_tests_per_channel
+        ]
+        rows.append(
+            {
+                **item,
+                "test_counts": channel_counts,
+                "missing_channels": missing_channels,
+                "covered_all_channels": not missing_channels,
+            }
+        )
+
+    missing_rows = [row for row in rows if not row["covered_all_channels"]]
+    return {
+        "shop_id": shop_id,
+        "agent_id": agent_id,
+        "channels": channels,
+        "min_tests_per_channel": min_tests_per_channel,
+        "summary": {
+            "intent_count": len(rows),
+            "fully_covered_count": len(rows) - len(missing_rows),
+            "gaps_count": len(missing_rows),
+        },
+        "rows": rows,
+        "gaps": missing_rows,
+    }
+
+
+@app.command(
+    "coverage",
+    help=(
+        "Show per-intent test coverage matrix by channel. Example: applied-cli taxonomy coverage "
+        "--channels chat,email --min-tests-per-channel 1 --only-gaps"
+    ),
+)
+def coverage_cmd(
+    channels: str = typer.Option(
+        "chat,email",
+        "--channels",
+        help="Comma-separated channels: chat,email,sms",
+    ),
+    min_tests_per_channel: int = typer.Option(
+        1,
+        "--min-tests-per-channel",
+        help="Minimum required test conversations per intent per channel.",
+    ),
+    include_flags: bool = typer.Option(
+        False, "--include-flags", help="Include flag-like intents (is_flag=true)."
+    ),
+    only_gaps: bool = typer.Option(
+        False, "--only-gaps", help="Show only intents missing required channel coverage."
+    ),
+    agent_id: Optional[str] = typer.Option(
+        None,
+        "--agent-id",
+        "--agent",
+        "--id",
+        help="Optional agent UUID to scope test conversations.",
+    ),
+    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 min_tests_per_channel < 1:
+        raise typer.BadParameter("min-tests-per-channel must be >= 1.")
+    selected_channels = _parse_channels(channels)
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        payload = _build_intent_coverage_payload(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            channels=selected_channels,
+            min_tests_per_channel=min_tests_per_channel,
+            include_flags=include_flags,
+            agent_id=agent_id,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="calculate intent coverage"), err=True)
+        raise typer.Exit(code=1) from exc
+
+    rows = payload["gaps"] if only_gaps else payload["rows"]
+    if output_json:
+        output = dict(payload)
+        output["rows"] = rows
+        typer.echo(json.dumps(output, indent=2, default=str))
+        return
+
+    summary = payload["summary"]
+    typer.echo(
+        "summary="
+        + ", ".join(
+            [
+                f"intents={summary['intent_count']}",
+                f"fully_covered={summary['fully_covered_count']}",
+                f"gaps={summary['gaps_count']}",
+                f"min_tests_per_channel={payload['min_tests_per_channel']}",
+                f"channels={','.join(payload['channels'])}",
+            ]
+        )
+    )
+    if not rows:
+        typer.echo("No results.")
+        return
+    for row in rows:
+        counts_view = ", ".join(
+            [f"{channel}:{row['test_counts'].get(channel, 0)}" for channel in payload["channels"]]
+        )
+        missing_view = ",".join(row["missing_channels"]) if row["missing_channels"] else "none"
+        typer.echo(
+            f"topic={row['topic']} | intent={row['intent']} | intent_id={row['intent_id']} | tests=({counts_view}) | missing={missing_view}"
+        )
+
+
+@app.command(
+    "gate",
+    help=(
+        "Fail with exit code 1 if intent coverage has gaps. Example: applied-cli taxonomy gate "
+        "--channels chat,email --min-tests-per-channel 1"
+    ),
+)
+def gate_cmd(
+    channels: str = typer.Option(
+        "chat,email",
+        "--channels",
+        help="Comma-separated channels: chat,email,sms",
+    ),
+    min_tests_per_channel: int = typer.Option(
+        1,
+        "--min-tests-per-channel",
+        help="Minimum required test conversations per intent per channel.",
+    ),
+    include_flags: bool = typer.Option(
+        False, "--include-flags", help="Include flag-like intents (is_flag=true)."
+    ),
+    agent_id: Optional[str] = typer.Option(
+        None,
+        "--agent-id",
+        "--agent",
+        "--id",
+        help="Optional agent UUID to scope test conversations.",
+    ),
+    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 min_tests_per_channel < 1:
+        raise typer.BadParameter("min-tests-per-channel must be >= 1.")
+    selected_channels = _parse_channels(channels)
+    try:
+        resolved_base_url, resolved_shop_id, resolved_token = resolve_runtime(
+            base_url=base_url,
+            shop_id=shop_id,
+            api_token=api_token,
+        )
+        payload = _build_intent_coverage_payload(
+            base_url=resolved_base_url,
+            shop_id=resolved_shop_id,
+            api_token=resolved_token,
+            channels=selected_channels,
+            min_tests_per_channel=min_tests_per_channel,
+            include_flags=include_flags,
+            agent_id=agent_id,
+        )
+    except APIError as exc:
+        typer.echo(render_api_error(exc, action="evaluate intent coverage gate"), err=True)
+        raise typer.Exit(code=1) from exc
+
+    gaps = payload["gaps"]
+    if not gaps:
+        typer.echo(
+            "result=success | gate=pass | "
+            f"intents={payload['summary']['intent_count']} | channels={','.join(payload['channels'])}"
+        )
+        return
+    typer.echo(
+        "result=failed | gate=fail | "
+        f"gaps={payload['summary']['gaps_count']} | channels={','.join(payload['channels'])}",
+        err=True,
+    )
+    for row in gaps[:20]:
+        typer.echo(
+            f"- topic={row['topic']} | intent={row['intent']} | missing={','.join(row['missing_channels'])}",
+            err=True,
+        )
+    if len(gaps) > 20:
+        typer.echo(f"- ... and {len(gaps) - 20} more gaps", err=True)
+    raise typer.Exit(code=1)