applied-cli 0.5.37__tar.gz → 0.5.39__tar.gz

{applied_cli-0.5.37 → applied_cli-0.5.39}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: applied-cli
-Version: 0.5.37
+Version: 0.5.39
 Summary: CLI and shared client library for Applied Labs AI support agents
 Author: Applied Labs
 License-Expression: MIT

{applied_cli-0.5.37 → applied_cli-0.5.39}/applied_cli/cli.py

@@ -178,40 +178,97 @@ def taxonomy(
 
 
 @app.command()
-def taxonomy_counts(
-    start: str = typer.Option(
-        None,
-        "--start",
-        help="Inclusive start timestamp/date, e.g. 2026-03-01 or 2026-03-01T00:00:00Z",
+def analytics(
+    group_by: str = typer.Option(
+        ...,
+        "--group-by",
+        "-g",
+        help=(
+            "Comma-separated dimensions: label_name, sublabel_name, agent_name, "
+            "resolution, sentiment, type, user_id, label_id, sublabel_id, agent_id"
+        ),
     ),
-    end: str = typer.Option(
-        None,
-        "--end",
-        help="Inclusive end timestamp/date, e.g. 2026-03-18 or 2026-03-18T23:59:59Z",
+    metrics: str = typer.Option(
+        "count",
+        "--metrics",
+        "-m",
+        help="Comma-separated metrics: count, avg_score, avg_ttr, resolution_rate",
     ),
-    date_field: str = typer.Option(
-        "created_at",
-        "--date-field",
-        help="Conversation date field to filter on: created_at or last_message_at",
+    filter: list[str] = typer.Option(
+        [],
+        "--filter",
+        help='Filter as "field=value". Repeatable.',
     ),
-    include_zero: bool = typer.Option(
-        True,
-        "--include-zero/--exclude-zero",
-        help="Include zero-count topics and intents",
+    start: str = typer.Option(None, "--start", help="Start date, e.g. 2025-01-01"),
+    end: str = typer.Option(None, "--end", help="End date, e.g. 2025-01-31"),
+    limit: int = typer.Option(1000, "--limit", "-l", help="Max rows to return"),
+    format: str = typer.Option(
+        "csv", "--format", "-f", help="Output format: csv or json"
+    ),
+) -> None:
+    """Run a server-side analytics query grouped by dimensions."""
+    client = get_client()
+    result = asyncio.run(
+        tools.analytics_query(
+            client,
+            group_by=[g.strip() for g in group_by.split(",") if g.strip()],
+            metrics=[m.strip() for m in metrics.split(",") if m.strip()],
+            filters=list(filter) or None,
+            start=start,
+            end=end,
+            limit=limit if limit != 1000 else None,
+            output_format=format,
+        )
+    )
+    typer.echo(result)
+
+
+@app.command()
+def metrics(
+    metric_name: str = typer.Option(
+        ...,
+        "--metric-name",
+        "-n",
+        help="Metric name, e.g. customer.cancel, customer.save",
+    ),
+    group_by: str = typer.Option(
+        "",
+        "--group-by",
+        "-g",
+        help="Property key to group by, e.g. reason",
+    ),
+    period: str = typer.Option(
+        "",
+        "--period",
+        "-p",
+        help="Trending period: day, week, month",
+    ),
+    filter: list[str] = typer.Option(
+        [],
+        "--filter",
+        help='Property filter as "key=value". Repeatable.',
+    ),
+    start: str = typer.Option(None, "--start", help="Start date, e.g. 2025-01-01"),
+    end: str = typer.Option(None, "--end", help="End date, e.g. 2025-01-31"),
+    object_type: str = typer.Option(
+        "conversation", "--object-type", help="Object type"
     ),
     format: str = typer.Option(
         "csv", "--format", "-f", help="Output format: csv or json"
     ),
 ) -> None:
-    """Aggregate conversation counts by topic and intent."""
+    """Query metric events with property grouping and trending."""
     client = get_client()
     result = asyncio.run(
-        tools.taxonomy_counts(
+        tools.analytics_metrics(
             client,
+            metric_name=metric_name,
+            group_by=group_by or None,
+            period=period or None,
+            filters=list(filter) or None,
             start=start,
             end=end,
-            date_field=date_field,
-            include_zero=include_zero,
+            object_type=object_type,
             output_format=format,
         )
     )

{applied_cli-0.5.37 → applied_cli-0.5.39}/applied_cli/client.py

@@ -231,6 +231,60 @@ class AppliedClient:
         data = await self._request("GET", "/v1/property-choices/", params=params)
         return self._normalize_response(data)
 
+    # -------------------------------------------------------------------------
+    # Analytics
+    # -------------------------------------------------------------------------
+
+    async def analytics_query(
+        self,
+        group_by: list[str],
+        metrics: list[str] | None = None,
+        filters: list[str] | None = None,
+        start: str | None = None,
+        end: str | None = None,
+        limit: int | None = None,
+    ) -> dict:
+        """Run a GROUP BY query against conversation_latest_state."""
+        params: dict[str, Any] = {"group_by": ",".join(group_by)}
+        if metrics:
+            params["metrics"] = ",".join(metrics)
+        if filters:
+            params["filter"] = filters
+        if start:
+            params["start_date"] = start
+        if end:
+            params["end_date"] = end
+        if limit:
+            params["limit"] = limit
+        return await self._request("GET", "/v2/analytics/query/", params=params)
+
+    async def analytics_metrics(
+        self,
+        metric_name: str,
+        group_by: str | None = None,
+        period: str | None = None,
+        filters: list[str] | None = None,
+        start: str | None = None,
+        end: str | None = None,
+        object_type: str = "conversation",
+    ) -> dict:
+        """Query metric_events_hour with optional property grouping and trending."""
+        params: dict[str, Any] = {
+            "metric_name": metric_name,
+            "object_type": object_type,
+        }
+        if group_by:
+            params["group_by"] = group_by
+        if period:
+            params["period"] = period
+        if filters:
+            params["filter"] = filters
+        if start:
+            params["start_date"] = start
+        if end:
+            params["end_date"] = end
+        return await self._request("GET", "/v2/analytics/metrics/", params=params)
+
     # -------------------------------------------------------------------------
     # Conversations
     # -------------------------------------------------------------------------

{applied_cli-0.5.37 → applied_cli-0.5.39}/applied_cli/tools.py

@@ -4,8 +4,6 @@ These functions wrap the client methods with formatting logic,
 suitable for both MCP tools and CLI commands.
 """
 
-import csv
-import io
 import json
 
 from applied_cli.client import AppliedAPIError, AppliedClient
@@ -82,143 +80,78 @@ async def taxonomy_list(
     return to_json(items)
 
 
-def _taxonomy_counts_csv(
-    summary: dict,
-    topics: list[dict],
-    intents: list[dict],
+async def analytics_query(
+    client: AppliedClient,
+    group_by: list[str],
+    metrics: list[str] | None = None,
+    filters: list[str] | None = None,
+    start: str | None = None,
+    end: str | None = None,
+    limit: int | None = None,
+    output_format: str = "csv",
 ) -> str:
-    sections: list[str] = []
-
-    summary_output = io.StringIO()
-    summary_writer = csv.writer(summary_output)
-    summary_writer.writerow(["field", "value"])
-    for key in ["start", "end", "date_field", "total_conversations"]:
-        summary_writer.writerow([key, summary.get(key, "")])
-    sections.append("# summary")
-    sections.append(summary_output.getvalue().strip())
-
-    sections.append("# topics")
-    sections.append(to_csv(topics, ["id", "name", "conversation_count"]).strip())
-
-    sections.append("# intents")
-    sections.append(
-        to_csv(
-            intents,
-            ["id", "name", "topic_id", "topic_name", "conversation_count"],
-        ).strip()
-    )
+    """Run a server-side ClickHouse GROUP BY query on conversation data.
 
-    return "\n\n".join(sections) + "\n"
+    Dimensions: label_id, label_name, sublabel_id, sublabel_name,
+                agent_id, agent_name, resolution, sentiment, score, type, user_id
+    Metrics: count, avg_score, avg_ttr, resolution_rate
+    Filters: agent_id, label_id, sublabel_id, type, resolution, sentiment, score, user_id
+    """
+    data = await client.analytics_query(
+        group_by=group_by,
+        metrics=metrics,
+        filters=filters,
+        start=start,
+        end=end,
+        limit=limit,
+    )
+    rows = data.get("rows", [])
+    if not rows:
+        return "No data found for the given query."
+    if output_format == "json":
+        return to_json(data)
+    columns = data.get("dimensions", group_by) + data.get(
+        "metrics", metrics or ["count"]
+    )
+    return to_csv(rows, columns)
 
 
-async def taxonomy_counts(
+async def analytics_metrics(
     client: AppliedClient,
+    metric_name: str,
+    group_by: str | None = None,
+    period: str | None = None,
+    filters: list[str] | None = None,
     start: str | None = None,
     end: str | None = None,
-    date_field: str = "created_at",
-    include_zero: bool = True,
+    object_type: str = "conversation",
     output_format: str = "csv",
 ) -> str:
-    """
-    Aggregate conversation counts by topic and intent.
-
-    Args:
-        client: Authenticated AppliedClient
-        start: Inclusive start timestamp/date string
-        end: Inclusive end timestamp/date string
-        date_field: Conversation date field to filter on: 'created_at' or 'last_message_at'
-        include_zero: Include zero-count taxonomy rows
-        output_format: 'csv' or 'json'
+    """Query metric events with optional property grouping and trending.
 
-    Returns:
-        Topic and intent counts with optional time-range summary.
+    Use for custom business metrics: cancel reasons, save rates, etc.
     """
-    if date_field not in {"created_at", "last_message_at"}:
-        raise ValueError("date_field must be 'created_at' or 'last_message_at'")
-
-    topics = await client.list_taxonomy("topics")
-    intents = await client.list_taxonomy("intents")
-
-    topic_counts = {str(topic.get("id")): 0 for topic in topics}
-    intent_counts = {str(intent.get("id")): 0 for intent in intents}
-
-    filters: dict[str, dict[str, str]] = {}
-    if start or end:
-        filters[date_field] = {}
-        if start:
-            filters[date_field]["gte"] = start
-        if end:
-            filters[date_field]["lte"] = end
-
-    conversations = await client.query_conversations(
-        filters=filters or None,
-        limit=100,
-        fetch_all=True,
+    data = await client.analytics_metrics(
+        metric_name=metric_name,
+        group_by=group_by,
+        period=period,
+        filters=filters,
+        start=start,
+        end=end,
+        object_type=object_type,
     )
-
-    for conversation in conversations:
-        topic_id = (
-            conversation.get("label_id")
-            or (conversation.get("label") or {}).get("id")
-            or (conversation.get("label") or {}).get("uuid")
-        )
-        intent_id = (
-            conversation.get("sublabel_id")
-            or (conversation.get("sublabel") or {}).get("id")
-            or (conversation.get("sublabel") or {}).get("uuid")
-        )
-
-        if topic_id is not None:
-            topic_key = str(topic_id)
-            if topic_key in topic_counts:
-                topic_counts[topic_key] += 1
-        if intent_id is not None:
-            intent_key = str(intent_id)
-            if intent_key in intent_counts:
-                intent_counts[intent_key] += 1
-
-    topic_rows = [
-        {
-            "id": str(topic.get("id")),
-            "name": topic.get("name", ""),
-            "conversation_count": topic_counts.get(str(topic.get("id")), 0),
-        }
-        for topic in topics
-    ]
-    intent_rows = [
-        {
-            "id": str(intent.get("id")),
-            "name": intent.get("name", ""),
-            "topic_id": str(intent.get("parent_choice_id") or ""),
-            "topic_name": intent.get("parent_choice_name", ""),
-            "conversation_count": intent_counts.get(str(intent.get("id")), 0),
-        }
-        for intent in intents
-    ]
-
-    if not include_zero:
-        topic_rows = [row for row in topic_rows if row["conversation_count"] > 0]
-        intent_rows = [row for row in intent_rows if row["conversation_count"] > 0]
-
-    topic_rows.sort(key=lambda row: (-row["conversation_count"], row["name"]))
-    intent_rows.sort(key=lambda row: (-row["conversation_count"], row["name"]))
-
-    summary = {
-        "start": start or "",
-        "end": end or "",
-        "date_field": date_field,
-        "total_conversations": len(conversations),
-    }
-
-    payload = {
-        "summary": summary,
-        "topics": topic_rows,
-        "intents": intent_rows,
-    }
-
+    rows = data.get("rows", [])
+    if not rows:
+        return "No data found for the given query."
     if output_format == "json":
-        return to_json(payload)
-    return _taxonomy_counts_csv(summary, topic_rows, intent_rows)
+        return to_json(data)
+    columns: list[str] = []
+    if group_by:
+        columns.append("prop_group")
+    if period:
+        columns.append("period")
+    columns.extend(["event_count", "object_count"])
+    return to_csv(rows, columns)
 
 
 async def conversation_query(

{applied_cli-0.5.37 → applied_cli-0.5.39}/applied_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: applied-cli
-Version: 0.5.37
+Version: 0.5.39
 Summary: CLI and shared client library for Applied Labs AI support agents
 Author: Applied Labs
 License-Expression: MIT

{applied_cli-0.5.37 → applied_cli-0.5.39}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "applied-cli"
-version = "0.5.37"
+version = "0.5.39"
 description = "CLI and shared client library for Applied Labs AI support agents"
 readme = "README.md"
 requires-python = ">=3.11"