applied-cli 0.5.73__tar.gz → 0.5.74__tar.gz

{applied_cli-0.5.73 → applied_cli-0.5.74}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: applied-cli
-Version: 0.5.73
+Version: 0.5.74
 Summary: CLI and shared client library for Applied Labs AI support agents
 Author: Applied Labs
 License-Expression: MIT
@@ -67,8 +67,18 @@ applied knowledge-unprotect <id>
 # Taxonomy
 applied taxonomy --type topics
 applied taxonomy-counts --start 2026-03-01 --end 2026-03-18 --format csv
+
+# Analytics
+applied analytics-report --view overview_aggregate_metrics --model conversation --start 2026-04-01 --end 2026-04-30 --format json
+applied analytics --group-by topic --metrics count --start 2026-04-01 --end 2026-04-30 --format json
+applied analytics --group-by intent --metrics count --start 2026-04-01 --end 2026-04-30 --format json
+applied metrics --metric-name conversation.resolve --start 2026-04-01 --end 2026-04-30 --period day --format json
 ```
 
+`analytics-report` returns the selected report payload, not necessarily a `{ "rows": [...] }`
+object. `analytics` returns grouped rows and currently supports `--metrics count`.
+Raw analytics SQL is not available through the public CLI surface.
+
 ## Library Usage
 
 ```python
@@ -99,6 +109,9 @@ conversations = await tools.conversation_query(
 | `knowledge_list` | List knowledge base items |
 | `taxonomy_list` | List topics, intents, and flags |
 | `taxonomy_counts` | Aggregate conversation counts by topic and intent |
+| `analytics_report` | Read standard dashboard/report analytics views |
+| `analytics_query` | Aggregate supported conversation dimensions with count |
+| `metrics_query` | Roll up named metric events |
 
 ## Examples
 

{applied_cli-0.5.73 → applied_cli-0.5.74}/README.md

@@ -42,8 +42,18 @@ applied knowledge-unprotect <id>
 # Taxonomy
 applied taxonomy --type topics
 applied taxonomy-counts --start 2026-03-01 --end 2026-03-18 --format csv
+
+# Analytics
+applied analytics-report --view overview_aggregate_metrics --model conversation --start 2026-04-01 --end 2026-04-30 --format json
+applied analytics --group-by topic --metrics count --start 2026-04-01 --end 2026-04-30 --format json
+applied analytics --group-by intent --metrics count --start 2026-04-01 --end 2026-04-30 --format json
+applied metrics --metric-name conversation.resolve --start 2026-04-01 --end 2026-04-30 --period day --format json
 ```
 
+`analytics-report` returns the selected report payload, not necessarily a `{ "rows": [...] }`
+object. `analytics` returns grouped rows and currently supports `--metrics count`.
+Raw analytics SQL is not available through the public CLI surface.
+
 ## Library Usage
 
 ```python
@@ -74,6 +84,9 @@ conversations = await tools.conversation_query(
 | `knowledge_list` | List knowledge base items |
 | `taxonomy_list` | List topics, intents, and flags |
 | `taxonomy_counts` | Aggregate conversation counts by topic and intent |
+| `analytics_report` | Read standard dashboard/report analytics views |
+| `analytics_query` | Aggregate supported conversation dimensions with count |
+| `metrics_query` | Roll up named metric events |
 
 ## Examples
 

{applied_cli-0.5.73 → applied_cli-0.5.74}/applied_cli/__init__.py

@@ -4,6 +4,6 @@ from applied_cli import tools
 from applied_cli.client import AppliedClient
 from applied_cli.formatters import to_csv, to_json
 
-__version__ = "0.5.72"
+__version__ = "0.5.74"
 
 __all__ = ["AppliedClient", "tools", "to_csv", "to_json", "__version__"]

{applied_cli-0.5.73 → applied_cli-0.5.74}/applied_cli/client.py

@@ -2,11 +2,94 @@
 
 import asyncio
 import json
+import os
 import uuid
 from typing import Any
 
 import httpx
 
+ACCESS_MODE_ENV_VAR = "APPLIED_ASSISTANT_ACCESS_MODE"
+ASSISTANT_CONVERSATION_ENV_VAR = "APPLIED_ASSISTANT_CONVERSATION_ID"
+FULL_ACCESS_MODE = "full_access"
+DEFAULT_ACCESS_MODE = "default"
+READ_ONLY_ACCESS_MODE = "read_only"
+MUTATING_METHODS = {"POST", "PATCH", "DELETE", "PUT"}
+OBJECT_COLLECTION_LABELS = {
+    "agents": "Agent",
+    "c": "Conversation",
+    "conversations": "Conversation",
+    "content": "Content",
+    "flows": "Flow",
+    "nodes": "Flow node",
+    "edges": "Flow edge",
+    "products": "Product",
+    "responses": "Response",
+    "tickets": "Ticket",
+    "tools": "Tool",
+}
+
+
+def _normalize_access_mode(access_mode: str | None) -> str:
+    if access_mode is None or not access_mode.strip():
+        return FULL_ACCESS_MODE
+
+    normalized = access_mode.strip().lower().replace("-", "_")
+    if normalized in {FULL_ACCESS_MODE, DEFAULT_ACCESS_MODE, READ_ONLY_ACCESS_MODE}:
+        return normalized
+    return DEFAULT_ACCESS_MODE
+
+
+def _json_safe(value: Any) -> Any:
+    try:
+        return json.loads(json.dumps(value, default=str, ensure_ascii=True))
+    except (TypeError, ValueError):
+        return str(value)
+
+
+def _infer_change_action(method: str) -> str:
+    method = method.upper()
+    if method == "POST":
+        return "add"
+    if method == "DELETE":
+        return "remove"
+    return "update"
+
+
+def _infer_object_reference(path: str, body: Any) -> tuple[str, str, str]:
+    parts = [part for part in path.split("?", 1)[0].strip("/").split("/") if part]
+    if parts and parts[0].startswith("v") and len(parts) > 1:
+        parts = parts[1:]
+
+    object_type = "DB object"
+    object_id = ""
+    for index, part in enumerate(parts):
+        collection = part.replace("-", "_")
+        if collection not in OBJECT_COLLECTION_LABELS:
+            continue
+        object_type = OBJECT_COLLECTION_LABELS[collection]
+        if index + 1 < len(parts):
+            candidate = parts[index + 1]
+            if candidate.replace("-", "_") not in OBJECT_COLLECTION_LABELS:
+                object_id = candidate
+
+    object_name = ""
+    if isinstance(body, dict):
+        for key in ("name", "title", "label", "display_name", "displayName"):
+            value = body.get(key)
+            if isinstance(value, str) and value.strip():
+                object_name = value.strip()
+                break
+
+    return object_type, object_id, object_name
+
+
+def _candidate_after(before: Any, body: Any, after: Any) -> Any:
+    if after is not None:
+        return after
+    if isinstance(before, dict) and isinstance(body, dict):
+        return {**before, **body}
+    return body or {}
+
 
 class AppliedAPIError(Exception):
     """API error with details and recovery suggestions."""
@@ -355,7 +438,10 @@ def _decode_dashboard_group(group: Any, expected_count: int) -> list[Any]:
 
 def _sort_analytics_rows(rows: list[dict[str, Any]], group_by: list[str]) -> None:
     def sort_key(row: dict[str, Any]) -> tuple[str, ...]:
-        return tuple("" if row.get(dimension) is None else str(row.get(dimension)) for dimension in group_by)
+        return tuple(
+            "" if row.get(dimension) is None else str(row.get(dimension))
+            for dimension in group_by
+        )
 
     rows.sort(key=sort_key)
 
@@ -369,11 +455,163 @@ class AppliedClient:
         shop_id: str | None = None,
         base_url: str = "https://api.appliedlabs.ai",
         timeout: float = 30.0,
+        access_mode: str | None = None,
     ):
         self.token = token
         self.shop_id = shop_id
         self.base_url = base_url.rstrip("/")
         self.timeout = timeout
+        self.access_mode = _normalize_access_mode(
+            access_mode
+            if access_mode is not None
+            else os.environ.get(ACCESS_MODE_ENV_VAR)
+        )
+        self.assistant_conversation_id = os.environ.get(
+            ASSISTANT_CONVERSATION_ENV_VAR,
+            "",
+        ).strip()
+
+    async def _record_access_mode_change(
+        self,
+        *,
+        method: str,
+        path: str,
+        body: Any = None,
+        before: Any = None,
+        after: Any = None,
+        shop_id: str | None = None,
+        status: str,
+    ) -> None:
+        if not self.assistant_conversation_id or not self.token:
+            return
+
+        safe_body = _json_safe(body or {})
+        safe_before = _json_safe(before if before is not None else {})
+        safe_after = _json_safe(_candidate_after(before, body, after))
+        object_type, object_id, object_name = _infer_object_reference(
+            path,
+            safe_body if safe_body else safe_after,
+        )
+        resolved_shop_id = shop_id or self.shop_id
+        payload = {
+            "access_mode": self.access_mode,
+            "status": status,
+            "object_type": object_type,
+            "object_id": object_id,
+            "object_name": object_name,
+            "action": _infer_change_action(method),
+            "before": safe_before,
+            "after": safe_after,
+            "diff": {"request_body": safe_body},
+            "request_method": method.upper(),
+            "request_path": path,
+            "request_body": safe_body,
+        }
+        headers = {
+            "Authorization": f"Bearer {self.token}",
+            "Content-Type": "application/json",
+        }
+        if resolved_shop_id:
+            headers["X-Shop-Id"] = resolved_shop_id
+
+        timeout = (
+            min(self.timeout, 10.0) if isinstance(self.timeout, int | float) else 10.0
+        )
+        diffs_url = (
+            f"{self.base_url}/v1/threads/{self.assistant_conversation_id}/diffs/"
+        )
+        try:
+            async with httpx.AsyncClient(timeout=timeout) as client:
+                await client.post(
+                    diffs_url,
+                    headers=headers,
+                    json=payload,
+                )
+        except Exception:
+            # Do not let proposal logging mask the access-mode decision.
+            return
+
+    async def _fetch_current_object(
+        self,
+        *,
+        method: str,
+        path: str,
+        shop_id: str | None = None,
+    ) -> Any:
+        if method.upper() not in {"PATCH", "PUT", "DELETE"}:
+            return {}
+
+        headers = {"Authorization": f"Bearer {self.token}"}
+        resolved_shop_id = shop_id or self.shop_id
+        if resolved_shop_id:
+            headers["X-Shop-Id"] = resolved_shop_id
+
+        timeout = (
+            min(self.timeout, 10.0) if isinstance(self.timeout, int | float) else 10.0
+        )
+        try:
+            async with httpx.AsyncClient(timeout=timeout) as client:
+                response = await client.get(f"{self.base_url}{path}", headers=headers)
+                if response.status_code >= 400:
+                    return {}
+                return response.json()
+        except Exception:
+            return {}
+
+    async def _enforce_access_mode(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        shop_id: str | None = None,
+    ) -> None:
+        method = method.upper()
+        if method not in MUTATING_METHODS or self.access_mode == FULL_ACCESS_MODE:
+            return
+
+        requires_approval = self.access_mode == DEFAULT_ACCESS_MODE
+        before = await self._fetch_current_object(
+            method=method,
+            path=path,
+            shop_id=shop_id,
+        )
+        await self._record_access_mode_change(
+            method=method,
+            path=path,
+            body=body,
+            before=before,
+            shop_id=shop_id,
+            status="proposed" if requires_approval else "blocked",
+        )
+        error_code = (
+            "requires_approval" if requires_approval else "read_only_access_mode"
+        )
+        message = (
+            f"{method} {path} was not sent because Applied Assistant access mode "
+            f"is {self.access_mode}."
+        )
+        detail = {
+            "error": error_code,
+            "requires_approval": requires_approval,
+            "access_mode": self.access_mode,
+            "method": method,
+            "path": path,
+            "message": message,
+        }
+        suggestion = (
+            "Request approval or run with APPLIED_ASSISTANT_ACCESS_MODE=full_access "
+            "before retrying this mutation."
+            if requires_approval
+            else "This environment is read-only. Re-run in full_access mode only when "
+            "mutations are intended."
+        )
+        raise AppliedAPIError(
+            message=f"{method} {path} blocked by access mode",
+            status_code=403,
+            detail=json.dumps(detail, separators=(",", ":"), ensure_ascii=True),
+            suggestion=suggestion,
+        )
 
     async def _request(
         self,
@@ -384,6 +622,13 @@ class AppliedClient:
         shop_id: str | None = None,
     ) -> Any:
         """Make an authenticated API request."""
+        method = method.upper()
+        await self._enforce_access_mode(
+            method,
+            path,
+            body=body,
+            shop_id=shop_id,
+        )
         headers = {
             "Authorization": f"Bearer {self.token}",
             "Content-Type": "application/json",
@@ -392,6 +637,13 @@ class AppliedClient:
         if resolved_shop_id:
             headers["X-Shop-Id"] = resolved_shop_id
         url = f"{self.base_url}{path}"
+        before = None
+        if method in MUTATING_METHODS and self.access_mode == FULL_ACCESS_MODE:
+            before = await self._fetch_current_object(
+                method=method,
+                path=path,
+                shop_id=resolved_shop_id,
+            )
 
         async with httpx.AsyncClient(timeout=self.timeout) as client:
             if method == "GET":
@@ -441,9 +693,19 @@ class AppliedClient:
                     suggestion=suggestion,
                 )
 
-            if resp.status_code == 204:
-                return None
-            return resp.json()
+            result = None if resp.status_code == 204 else resp.json()
+
+            if method in MUTATING_METHODS and self.access_mode == FULL_ACCESS_MODE:
+                await self._record_access_mode_change(
+                    method=method,
+                    path=path,
+                    body=body,
+                    before=before,
+                    after=result,
+                    shop_id=shop_id,
+                    status="applied",
+                )
+            return result
 
     async def _upload_request(
         self,
@@ -453,12 +715,21 @@ class AppliedClient:
         data: dict[str, Any] | None = None,
     ) -> Any:
         """Make an authenticated multipart file upload request."""
+        method = method.upper()
+        await self._enforce_access_mode(method, path, body=data, shop_id=self.shop_id)
         headers = {
             "Authorization": f"Bearer {self.token}",
         }
         if self.shop_id:
             headers["X-Shop-Id"] = self.shop_id
         url = f"{self.base_url}{path}"
+        before = None
+        if method in MUTATING_METHODS and self.access_mode == FULL_ACCESS_MODE:
+            before = await self._fetch_current_object(
+                method=method,
+                path=path,
+                shop_id=self.shop_id,
+            )
 
         async with httpx.AsyncClient(timeout=self.timeout) as client:
             resp = await client.request(
@@ -485,9 +756,19 @@ class AppliedClient:
                     detail=detail,
                 )
 
-            if resp.status_code == 204:
-                return None
-            return resp.json()
+            result = None if resp.status_code == 204 else resp.json()
+
+            if method in MUTATING_METHODS and self.access_mode == FULL_ACCESS_MODE:
+                await self._record_access_mode_change(
+                    method=method,
+                    path=path,
+                    body=data,
+                    before=before,
+                    after=result,
+                    shop_id=self.shop_id,
+                    status="applied",
+                )
+            return result
 
     def _require_shop_id(self, shop_id: str | None = None) -> str:
         resolved_shop_id = shop_id or self.shop_id
@@ -564,9 +845,7 @@ class AppliedClient:
         **kwargs: Any,
     ) -> dict:
         """Update an agent's properties."""
-        return await self._request(
-            "PATCH", f"/v1/agents/{agent_id}/", body=kwargs
-        )
+        return await self._request("PATCH", f"/v1/agents/{agent_id}/", body=kwargs)
 
     async def update_agent_picture(
         self,
@@ -1886,6 +2165,18 @@ class AppliedClient:
         Returns:
             Dict with conversation_id, response, and status
         """
+        path = f"/v1/agents/{agent_id}/complete/"
+        await self._enforce_access_mode(
+            "POST",
+            path,
+            body={
+                "conversation_id": conversation_id or "",
+                "message": message,
+                "metadata": metadata or {},
+                "flow_id": flow_id or "",
+            },
+        )
+
         conversation = await self.ensure_test_conversation(
             agent_id=agent_id,
             conversation_id=conversation_id,
@@ -1922,7 +2213,7 @@ class AppliedClient:
         if runtime_metadata:
             body["metadata"] = runtime_metadata
 
-        url = f"{self.base_url}/v1/agents/{agent_id}/complete/"
+        url = f"{self.base_url}{path}"
 
         response_text = ""
 
@@ -1944,11 +2235,20 @@ class AppliedClient:
                 except json.JSONDecodeError:
                     pass
 
-        return {
+        result = {
             "conversation_id": result_conversation_id,
             "response": response_text,
             "status": "success" if response_text else "empty",
         }
+        if self.access_mode == FULL_ACCESS_MODE:
+            await self._record_access_mode_change(
+                method="POST",
+                path=path,
+                body=body,
+                after=result,
+                status="applied",
+            )
+        return result
 
     # -------------------------------------------------------------------------
     # Benchmarks

{applied_cli-0.5.73 → applied_cli-0.5.74}/applied_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: applied-cli
-Version: 0.5.73
+Version: 0.5.74
 Summary: CLI and shared client library for Applied Labs AI support agents
 Author: Applied Labs
 License-Expression: MIT
@@ -67,8 +67,18 @@ applied knowledge-unprotect <id>
 # Taxonomy
 applied taxonomy --type topics
 applied taxonomy-counts --start 2026-03-01 --end 2026-03-18 --format csv
+
+# Analytics
+applied analytics-report --view overview_aggregate_metrics --model conversation --start 2026-04-01 --end 2026-04-30 --format json
+applied analytics --group-by topic --metrics count --start 2026-04-01 --end 2026-04-30 --format json
+applied analytics --group-by intent --metrics count --start 2026-04-01 --end 2026-04-30 --format json
+applied metrics --metric-name conversation.resolve --start 2026-04-01 --end 2026-04-30 --period day --format json
 ```
 
+`analytics-report` returns the selected report payload, not necessarily a `{ "rows": [...] }`
+object. `analytics` returns grouped rows and currently supports `--metrics count`.
+Raw analytics SQL is not available through the public CLI surface.
+
 ## Library Usage
 
 ```python
@@ -99,6 +109,9 @@ conversations = await tools.conversation_query(
 | `knowledge_list` | List knowledge base items |
 | `taxonomy_list` | List topics, intents, and flags |
 | `taxonomy_counts` | Aggregate conversation counts by topic and intent |
+| `analytics_report` | Read standard dashboard/report analytics views |
+| `analytics_query` | Aggregate supported conversation dimensions with count |
+| `metrics_query` | Roll up named metric events |
 
 ## Examples
 

{applied_cli-0.5.73 → applied_cli-0.5.74}/pyproject.toml

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