applied-cli 0.6.12__tar.gz → 0.7.0__tar.gz

{applied_cli-0.6.12 → applied_cli-0.7.0}/PKG-INFO

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

{applied_cli-0.6.12 → applied_cli-0.7.0}/applied_cli/__init__.py

@@ -6,7 +6,7 @@ from applied_cli.client import AppliedClient
 from applied_cli.formatters import to_csv, to_json
 from applied_cli.toolkit import ToolResult, ToolSpec
 
-__version__ = "0.6.12"
+__version__ = "0.7.0"
 
 __all__ = [
     "AppliedClient",

{applied_cli-0.6.12 → applied_cli-0.7.0}/applied_cli/v2/catalog.py

@@ -17,6 +17,7 @@ from applied_cli.v2.articles import article_specs
 from applied_cli.v2.connectors import connector_specs
 from applied_cli.v2.content import content_specs
 from applied_cli.v2.conversations import conversation_specs
+from applied_cli.v2.dashboards import dashboard_specs
 from applied_cli.v2.domains import LEGACY_TOOL_RENAMES
 from applied_cli.v2.evals import evals_specs
 from applied_cli.v2.flows import flow_specs
@@ -228,6 +229,7 @@ def get_tool_catalog(include_debug: bool = False) -> ToolCatalog:
         *connector_specs(),
         *content_specs(),
         *conversation_specs(),
+        *dashboard_specs(),
         *evals_specs(),
         *flow_specs(),
         *knowledge_specs(),

applied_cli-0.7.0/applied_cli/v2/dashboards.py

@@ -0,0 +1,330 @@
+"""Native structured v2 tools for analytics dashboards and save-metric config.
+
+These tools let an agent stand up a shop's Save Agent analytics end to end:
+list the built-in dashboard templates, instantiate one (e.g. ``save_agent``),
+and read/update the save-metric vocabulary (cancellation reasons and save
+tactics) that the post-conversation metric extractor classifies against.
+
+All endpoints are shop-scoped and merchant-authenticated. Save-metric
+extraction itself is enrolled per shop via the ``save_metric_extraction``
+feature flag (platform admin) — ``save_metrics_config_get`` reports whether
+the current shop is enrolled.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from applied_cli.client import AppliedAPIError, AppliedClient
+from applied_cli.toolkit import ToolError, ToolResult, ToolSpec
+
+
+class StrictInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+# ── inputs ──────────────────────────────────────────────────────────────────
+
+
+class DashboardsListInput(StrictInput):
+    pass
+
+
+class DashboardTemplatesListInput(StrictInput):
+    pass
+
+
+class DashboardsCreateInput(StrictInput):
+    template_key: str | None = Field(
+        default=None,
+        description=(
+            "Key of a built-in dashboard template to instantiate (see "
+            "dashboards_templates_list; e.g. 'save_agent'). Omit to create an "
+            "empty dashboard."
+        ),
+    )
+    name: str | None = Field(
+        default=None,
+        description="Dashboard name. Defaults to the template's name.",
+    )
+    description: str | None = Field(
+        default=None,
+        description="Dashboard description. Defaults to the template's.",
+    )
+    is_public: bool = Field(
+        default=True,
+        description=(
+            "Whether the dashboard is visible to the whole workspace (true) "
+            "or private to the creator (false)."
+        ),
+    )
+
+
+class SaveMetricsConfigGetInput(StrictInput):
+    pass
+
+
+class SaveMetricsConfigUpdateInput(StrictInput):
+    cancellation_reasons: list[str] | None = Field(
+        default=None,
+        description=(
+            "Canonical cancellation_reason values the extractor classifies "
+            "against. Replaces the current list; pass [] to clear the override "
+            "and fall back to values observed in the shop's metric events. "
+            "Omit to leave unchanged."
+        ),
+    )
+    save_tactics: list[str] | None = Field(
+        default=None,
+        description=(
+            "Canonical save_tactic values the extractor classifies against. "
+            "Replaces the current list; pass [] to clear the override and fall "
+            "back to observed values. Omit to leave unchanged."
+        ),
+    )
+
+
+# ── helpers ─────────────────────────────────────────────────────────────────
+
+
+def _api_error_result(exc: AppliedAPIError) -> ToolResult[Any]:
+    return ToolResult(
+        ok=False,
+        error=ToolError(
+            code=f"api.{exc.status_code}",
+            message=str(exc),
+            status_code=exc.status_code,
+            retryable=exc.status_code in {408, 429, 500, 502, 503, 504},
+            recovery_hint=exc.suggestion,
+        ),
+    )
+
+
+def _rows(data: Any) -> list[dict[str, Any]]:
+    if isinstance(data, list):
+        return [row for row in data if isinstance(row, dict)]
+    if isinstance(data, dict):
+        for key in ("results", "items", "data"):
+            value = data.get(key)
+            if isinstance(value, list):
+                return [row for row in value if isinstance(row, dict)]
+    return []
+
+
+def _project_dashboard(item: dict[str, Any]) -> dict[str, Any]:
+    revision = item.get("latest_revision") or item.get("revision") or {}
+    if not isinstance(revision, dict):
+        revision = {}
+    return {
+        "id": item.get("id"),
+        "name": item.get("name") or revision.get("name"),
+        "description": item.get("description") or revision.get("description"),
+        "is_public": item.get("is_public"),
+        "created_at": item.get("created_at"),
+    }
+
+
+# ── handlers ────────────────────────────────────────────────────────────────
+
+
+async def dashboards_list_handler(
+    client: AppliedClient,
+    params: DashboardsListInput,
+) -> ToolResult[Any]:
+    try:
+        data = await client.request("GET", "/v1/dashboards/")
+    except AppliedAPIError as exc:
+        return _api_error_result(exc)
+
+    items = [_project_dashboard(row) for row in _rows(data)]
+    suffix = "" if len(items) == 1 else "s"
+    return ToolResult(
+        data={"count": len(items), "dashboards": items},
+        summary=f"Found {len(items)} dashboard{suffix}.",
+        next_actions=[
+            "Use dashboards_create with a template_key to add a templated dashboard.",
+        ],
+    )
+
+
+async def dashboards_templates_list_handler(
+    client: AppliedClient,
+    params: DashboardTemplatesListInput,
+) -> ToolResult[Any]:
+    try:
+        data = await client.request("GET", "/v1/dashboards/templates/")
+    except AppliedAPIError as exc:
+        return _api_error_result(exc)
+
+    templates = data.get("templates", []) if isinstance(data, dict) else []
+    suffix = "" if len(templates) == 1 else "s"
+    return ToolResult(
+        data={"count": len(templates), "templates": templates},
+        summary=f"Found {len(templates)} dashboard template{suffix}.",
+        next_actions=[
+            "Use dashboards_create with template_key to instantiate a template "
+            "(e.g. 'save_agent' for the Save Agent dashboard).",
+        ],
+    )
+
+
+async def dashboards_create_handler(
+    client: AppliedClient,
+    params: DashboardsCreateInput,
+) -> ToolResult[Any]:
+    body: dict[str, Any] = {"is_public": params.is_public}
+    if params.template_key:
+        body["template_key"] = params.template_key
+    if params.name:
+        body["name"] = params.name
+    if params.description:
+        body["description"] = params.description
+
+    try:
+        data = await client.request("POST", "/v1/dashboards/", body=body)
+    except AppliedAPIError as exc:
+        return _api_error_result(exc)
+
+    dashboard = _project_dashboard(data if isinstance(data, dict) else {})
+    label = params.template_key or "empty"
+    return ToolResult(
+        data={"dashboard": dashboard, "raw": data},
+        summary=f"Created dashboard {dashboard.get('id')} from template '{label}'.",
+        next_actions=[
+            "Use save_metrics_config_get to check the save-metric vocabulary "
+            "and enrollment if this is a Save Agent dashboard.",
+        ],
+    )
+
+
+async def save_metrics_config_get_handler(
+    client: AppliedClient,
+    params: SaveMetricsConfigGetInput,
+) -> ToolResult[Any]:
+    try:
+        data = await client.request("GET", "/v1/save-metrics/config/")
+    except AppliedAPIError as exc:
+        return _api_error_result(exc)
+
+    enrolled = bool(data.get("enrolled")) if isinstance(data, dict) else False
+    return ToolResult(
+        data=data,
+        summary=(
+            "Save-metric extraction is "
+            + ("enrolled" if enrolled else "NOT enrolled")
+            + " for this shop."
+        ),
+        next_actions=[
+            "Use save_metrics_config_update to set cancellation_reasons or save_tactics.",
+            "Enrollment needs the save_metric_extraction feature flag (platform "
+            "admin) plus a dashboard charting the save metrics.",
+        ],
+    )
+
+
+async def save_metrics_config_update_handler(
+    client: AppliedClient,
+    params: SaveMetricsConfigUpdateInput,
+) -> ToolResult[Any]:
+    body: dict[str, Any] = {}
+    if params.cancellation_reasons is not None:
+        body["cancellation_reasons"] = params.cancellation_reasons
+    if params.save_tactics is not None:
+        body["save_tactics"] = params.save_tactics
+    if not body:
+        return ToolResult(
+            ok=False,
+            error=ToolError(
+                code="input.invalid",
+                message="Provide cancellation_reasons and/or save_tactics.",
+                retryable=False,
+                recovery_hint=(
+                    "Pass the full replacement list for at least one of "
+                    "cancellation_reasons or save_tactics."
+                ),
+            ),
+        )
+
+    try:
+        data = await client.request("PUT", "/v1/save-metrics/config/", body=body)
+    except AppliedAPIError as exc:
+        return _api_error_result(exc)
+
+    return ToolResult(
+        data=data,
+        summary=f"Updated save-metric vocabulary ({', '.join(sorted(body))}).",
+        next_actions=[
+            "Use save_metrics_config_get to verify the effective taxonomy.",
+        ],
+    )
+
+
+def dashboard_specs() -> list[ToolSpec]:
+    return [
+        ToolSpec(
+            name="dashboards_list",
+            namespace="dashboards",
+            description="List the shop's analytics dashboards.",
+            input_model=DashboardsListInput,
+            output_model=None,
+            handler=dashboards_list_handler,
+            read_write_mode="read",
+            tags=["native"],
+        ),
+        ToolSpec(
+            name="dashboards_templates_list",
+            namespace="dashboards",
+            description=(
+                "List built-in dashboard templates (e.g. save_agent) usable "
+                "with dashboards_create."
+            ),
+            input_model=DashboardTemplatesListInput,
+            output_model=None,
+            handler=dashboards_templates_list_handler,
+            read_write_mode="read",
+            tags=["native"],
+        ),
+        ToolSpec(
+            name="dashboards_create",
+            namespace="dashboards",
+            description=(
+                "Create an analytics dashboard, optionally from a built-in "
+                "template such as 'save_agent'."
+            ),
+            input_model=DashboardsCreateInput,
+            output_model=None,
+            handler=dashboards_create_handler,
+            read_write_mode="write",
+            tags=["native"],
+        ),
+        ToolSpec(
+            name="save_metrics_config_get",
+            namespace="save_metrics",
+            description=(
+                "Read the shop's save-metric vocabulary (cancellation reasons "
+                "and save tactics), the observed values, and whether the shop "
+                "is enrolled in post-conversation save-metric extraction."
+            ),
+            input_model=SaveMetricsConfigGetInput,
+            output_model=None,
+            handler=save_metrics_config_get_handler,
+            read_write_mode="read",
+            tags=["native"],
+        ),
+        ToolSpec(
+            name="save_metrics_config_update",
+            namespace="save_metrics",
+            description=(
+                "Update the shop's canonical save tactics and/or cancellation "
+                "reasons used by save-metric extraction and the Save Agent "
+                "dashboard group-bys."
+            ),
+            input_model=SaveMetricsConfigUpdateInput,
+            output_model=None,
+            handler=save_metrics_config_update_handler,
+            read_write_mode="write",
+            tags=["native"],
+        ),
+    ]

{applied_cli-0.6.12 → applied_cli-0.7.0}/applied_cli.egg-info/PKG-INFO

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

{applied_cli-0.6.12 → applied_cli-0.7.0}/applied_cli.egg-info/SOURCES.txt

@@ -27,6 +27,7 @@ applied_cli/v2/catalog.py
 applied_cli/v2/connectors.py
 applied_cli/v2/content.py
 applied_cli/v2/conversations.py
+applied_cli/v2/dashboards.py
 applied_cli/v2/domains.py
 applied_cli/v2/evals.py
 applied_cli/v2/flows.py
@@ -63,6 +64,7 @@ tests/test_v2_catalog_and_mcp.py
 tests/test_v2_connectors.py
 tests/test_v2_content.py
 tests/test_v2_conversations.py
+tests/test_v2_dashboards.py
 tests/test_v2_evals.py
 tests/test_v2_flows.py
 tests/test_v2_knowledge.py

{applied_cli-0.6.12 → applied_cli-0.7.0}/pyproject.toml

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

applied_cli-0.7.0/tests/test_v2_dashboards.py

@@ -0,0 +1,142 @@
+import pytest
+
+from applied_cli.v2.catalog import get_tool_catalog
+
+
+class FakeDashboardsClient:
+    def __init__(self):
+        self.access_mode = "full_access"
+        self.requests = []
+        self.responses = {}
+
+    async def request(self, method, path, params=None, body=None, shop_id=None):
+        self.requests.append(
+            {"method": method, "path": path, "params": params, "body": body}
+        )
+        return self.responses.get((method, path), {})
+
+
+def test_catalog_exposes_dashboard_and_save_metrics_tools():
+    catalog = get_tool_catalog()
+    expected = {
+        "dashboards_list": "read",
+        "dashboards_templates_list": "read",
+        "dashboards_create": "write",
+        "save_metrics_config_get": "read",
+        "save_metrics_config_update": "write",
+    }
+    for name, mode in expected.items():
+        spec = catalog[name]
+        assert spec.handler.__module__ == "applied_cli.v2.dashboards"
+        assert spec.read_write_mode == mode
+        assert "native" in spec.tags
+
+
+@pytest.mark.asyncio
+async def test_dashboards_templates_list_returns_templates():
+    client = FakeDashboardsClient()
+    client.responses[("GET", "/v1/dashboards/templates/")] = {
+        "templates": [
+            {
+                "key": "save_agent",
+                "name": "Save Agent Dashboard",
+                "description": "Track save performance.",
+                "chart_count": 10,
+            }
+        ]
+    }
+    spec = get_tool_catalog()["dashboards_templates_list"]
+
+    result = await spec.run(client, {})
+
+    assert result.ok is True
+    assert result.data["count"] == 1
+    assert result.data["templates"][0]["key"] == "save_agent"
+
+
+@pytest.mark.asyncio
+async def test_dashboards_create_posts_template_key():
+    client = FakeDashboardsClient()
+    client.responses[("POST", "/v1/dashboards/")] = {
+        "id": "dash-1",
+        "name": "Save Agent Dashboard",
+        "is_public": True,
+    }
+    spec = get_tool_catalog()["dashboards_create"]
+
+    result = await spec.run(client, {"template_key": "save_agent"})
+
+    assert result.ok is True
+    assert result.data["dashboard"]["id"] == "dash-1"
+    assert client.requests[-1]["body"] == {
+        "is_public": True,
+        "template_key": "save_agent",
+    }
+
+
+@pytest.mark.asyncio
+async def test_dashboards_list_projects_rows():
+    client = FakeDashboardsClient()
+    client.responses[("GET", "/v1/dashboards/")] = {
+        "results": [
+            {"id": "dash-1", "name": "Save Agent Dashboard", "is_public": True},
+            {"id": "dash-2", "name": "Support Trends", "is_public": False},
+        ]
+    }
+    spec = get_tool_catalog()["dashboards_list"]
+
+    result = await spec.run(client, {})
+
+    assert result.ok is True
+    assert result.data["count"] == 2
+    assert result.data["dashboards"][0]["id"] == "dash-1"
+
+
+@pytest.mark.asyncio
+async def test_save_metrics_config_get_reports_enrollment():
+    client = FakeDashboardsClient()
+    client.responses[("GET", "/v1/save-metrics/config/")] = {
+        "configured": {"save_tactics": ["Offer a discount"]},
+        "observed": {"cancellation_reasons": ["Price"], "save_tactics": []},
+        "effective": {
+            "cancellation_reasons": ["Price"],
+            "save_tactics": ["Offer a discount"],
+        },
+        "enrolled": True,
+        "flag_name": "save_metric_extraction",
+    }
+    spec = get_tool_catalog()["save_metrics_config_get"]
+
+    result = await spec.run(client, {})
+
+    assert result.ok is True
+    assert "enrolled" in result.summary
+    assert result.data["effective"]["save_tactics"] == ["Offer a discount"]
+
+
+@pytest.mark.asyncio
+async def test_save_metrics_config_update_puts_only_provided_lists():
+    client = FakeDashboardsClient()
+    client.responses[("PUT", "/v1/save-metrics/config/")] = {
+        "configured": {"save_tactics": ["Recipe Swap"]},
+        "effective": {"cancellation_reasons": [], "save_tactics": ["Recipe Swap"]},
+        "enrolled": False,
+    }
+    spec = get_tool_catalog()["save_metrics_config_update"]
+
+    result = await spec.run(client, {"save_tactics": ["Recipe Swap"]})
+
+    assert result.ok is True
+    assert client.requests[-1]["body"] == {"save_tactics": ["Recipe Swap"]}
+
+
+@pytest.mark.asyncio
+async def test_save_metrics_config_update_requires_a_field():
+    client = FakeDashboardsClient()
+    spec = get_tool_catalog()["save_metrics_config_update"]
+
+    result = await spec.run(client, {})
+
+    assert result.ok is False
+    assert result.error.code == "input.invalid"
+    assert client.requests == []