assistant-runtime-sdk 1.5.0__tar.gz → 1.7.0__tar.gz

{assistant_runtime_sdk-1.5.0 → assistant_runtime_sdk-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assistant_runtime_sdk
-Version: 1.5.0
+Version: 1.7.0
 Summary: Python SDK for FAC Cloud - the Assistant Runtime AI assistant backend
 Keywords: frappe,ai,assistant,llm,mcp,anthropic,openai,streaming
 Author: Paul Clinton

{assistant_runtime_sdk-1.5.0 → assistant_runtime_sdk-1.7.0}/assistant_runtime_sdk/__init__.py

@@ -53,7 +53,7 @@ Standalone Functions:
 
 """
 
-__version__ = "1.5.0"
+__version__ = "1.7.0"
 __author__ = "Paul Clinton"
 __license__ = "AGPL-3.0"
 
@@ -118,6 +118,8 @@ from .types import (
     StreamStartData,
     StreamChunkData,
     StreamCompleteData,
+    RoutingReceiptData,
+    ModelSelectedData,
     ModelFallbackData,
     RateLimitedData,
     ToolCallStartData,
@@ -198,6 +200,8 @@ __all__ = [
     "StreamStartData",
     "StreamChunkData",
     "StreamCompleteData",
+    "RoutingReceiptData",
+    "ModelSelectedData",
     "ModelFallbackData",
     "RateLimitedData",
     "ToolCallStartData",

{assistant_runtime_sdk-1.5.0 → assistant_runtime_sdk-1.7.0}/assistant_runtime_sdk/async_client.py

@@ -792,6 +792,56 @@ class AsyncAssistantRuntimeClient(BaseAssistantRuntimeClient):
         endpoint, payload = self._prepare_set_tool_preference(user_id, tool_name, preference)
         return await self._request_post_json(endpoint, payload)
 
+    # =========================================================================
+    # Routing Preference APIs
+    # =========================================================================
+
+    async def list_routing_preferences(self, user_id: str) -> Optional[Dict[str, Any]]:
+        """Async version of AssistantRuntimeClient.list_routing_preferences."""
+        endpoint, payload = self._prepare_list_routing_preferences(user_id)
+        return await self._request_post_json(endpoint, payload)
+
+    async def create_routing_preference(
+        self,
+        user_id: str,
+        scope: str,
+        match_kind: str,
+        match_value: str,
+        target_tier: str,
+        priority: int = None,
+        source_message_id: str = None,
+        origin: str = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Async version of AssistantRuntimeClient.create_routing_preference."""
+        endpoint, payload = self._prepare_create_routing_preference(
+            user_id, scope, match_kind, match_value, target_tier,
+            priority, source_message_id, origin)
+        return await self._request_post_json(endpoint, payload)
+
+    async def set_routing_preference_status(
+        self, user_id: str, preference_id: str, status: str,
+    ) -> Optional[Dict[str, Any]]:
+        """Async version of AssistantRuntimeClient.set_routing_preference_status."""
+        endpoint, payload = self._prepare_set_routing_preference_status(
+            user_id, preference_id, status)
+        return await self._request_post_json(endpoint, payload)
+
+    async def delete_routing_preference(
+        self, user_id: str, preference_id: str,
+    ) -> Optional[Dict[str, Any]]:
+        """Async version of AssistantRuntimeClient.delete_routing_preference."""
+        endpoint, payload = self._prepare_delete_routing_preference(
+            user_id, preference_id)
+        return await self._request_post_json(endpoint, payload)
+
+    async def forecast_routing_preference(
+        self, user_id: str, match_kind: str, match_value: str, target_tier: str,
+    ) -> Optional[Dict[str, Any]]:
+        """Async version of AssistantRuntimeClient.forecast_routing_preference."""
+        endpoint, payload = self._prepare_forecast_routing_preference(
+            user_id, match_kind, match_value, target_tier)
+        return await self._request_post_json(endpoint, payload)
+
     # =========================================================================
     # Billing & Subscription APIs
     # =========================================================================
@@ -1669,11 +1719,12 @@ class AsyncAssistantRuntimeClient(BaseAssistantRuntimeClient):
                             category: Optional[str] = None,
                             conversation_id: Optional[str] = None,
                             environment: Optional[dict] = None,
-                            attachment_ids: Optional[List[str]] = None) -> Optional[Dict[str, Any]]:
-        """Raise a support ticket. Returns {ticket_id, portal_link}."""
+                            attachment_ids: Optional[List[str]] = None,
+                            conversation_transcript: Optional[str] = None) -> Optional[Dict[str, Any]]:
+        """Raise a support ticket. Returns {ticket_id}."""
         endpoint, payload = self._prepare_create_ticket(
             user_id, subject, description, category, conversation_id, environment,
-            attachment_ids)
+            attachment_ids, conversation_transcript)
         return await self._request_post_json(endpoint, payload)
 
     async def submit_feedback(self, user_id: str, rating: Optional[int] = None,
@@ -1686,6 +1737,18 @@ class AsyncAssistantRuntimeClient(BaseAssistantRuntimeClient):
             user_id, rating, comment, category, conversation_id, environment)
         return await self._request_post_json(endpoint, payload)
 
+    async def download_ticket_attachment(self, user_id: str, ticket_id: str,
+                                         file_url: str) -> tuple:
+        """Download one attachment from a ticket the user owns.
+
+        Returns:
+            (content_bytes, content_type, filename) tuple.
+        """
+        endpoint, params = self._prepare_download_ticket_attachment(
+            user_id, ticket_id, file_url
+        )
+        return await self._request_get_raw(endpoint, params)
+
     async def list_tickets(self, user_id: str, status: Optional[str] = None) -> Optional[Dict[str, Any]]:
         """List the user's support tickets. Returns {tickets: [...]}."""
         endpoint, payload = self._prepare_list_tickets(user_id, status)

{assistant_runtime_sdk-1.5.0 → assistant_runtime_sdk-1.7.0}/assistant_runtime_sdk/base.py

@@ -846,6 +846,63 @@ class BaseAssistantRuntimeClient:
             "preference": preference,
         }
 
+    # =========================================================================
+    # Prepare Methods — Routing Preferences
+    # =========================================================================
+
+    def _prepare_list_routing_preferences(self, user_id: str) -> tuple:
+        return "routing_preferences.list_routing_preferences", {
+            "tenant_id": self.tenant_id,
+            "user_id": user_id,
+        }
+
+    def _prepare_create_routing_preference(
+        self, user_id: str, scope: str, match_kind: str, match_value: str,
+        target_tier: str, priority: int = None, source_message_id: str = None,
+        origin: str = None,
+    ) -> tuple:
+        return "routing_preferences.create_routing_preference", {
+            "tenant_id": self.tenant_id,
+            "user_id": user_id,
+            "scope": scope,
+            "match_kind": match_kind,
+            "match_value": match_value,
+            "target_tier": target_tier,
+            "priority": priority,
+            "source_message_id": source_message_id,
+            "origin": origin,
+        }
+
+    def _prepare_set_routing_preference_status(
+        self, user_id: str, preference_id: str, status: str,
+    ) -> tuple:
+        return "routing_preferences.set_routing_preference_status", {
+            "tenant_id": self.tenant_id,
+            "user_id": user_id,
+            "preference_id": preference_id,
+            "status": status,
+        }
+
+    def _prepare_delete_routing_preference(
+        self, user_id: str, preference_id: str,
+    ) -> tuple:
+        return "routing_preferences.delete_routing_preference", {
+            "tenant_id": self.tenant_id,
+            "user_id": user_id,
+            "preference_id": preference_id,
+        }
+
+    def _prepare_forecast_routing_preference(
+        self, user_id: str, match_kind: str, match_value: str, target_tier: str,
+    ) -> tuple:
+        return "routing_preferences.forecast_routing_preference", {
+            "tenant_id": self.tenant_id,
+            "user_id": user_id,
+            "match_kind": match_kind,
+            "match_value": match_value,
+            "target_tier": target_tier,
+        }
+
     # =========================================================================
     # Prepare Methods — Billing
     # =========================================================================
@@ -1802,7 +1859,8 @@ class BaseAssistantRuntimeClient:
                                category: Optional[str] = None,
                                conversation_id: Optional[str] = None,
                                environment: Optional[dict] = None,
-                               attachment_ids: Optional[List[str]] = None) -> tuple:
+                               attachment_ids: Optional[List[str]] = None,
+                               conversation_transcript: Optional[str] = None) -> tuple:
         """Returns (endpoint, payload)."""
         payload: Dict[str, Any] = {
             "tenant_id": self.tenant_id,
@@ -1818,6 +1876,8 @@ class BaseAssistantRuntimeClient:
             payload["environment"] = environment
         if attachment_ids:
             payload["attachment_ids"] = attachment_ids
+        if conversation_transcript:
+            payload["conversation_transcript"] = conversation_transcript
         return "support.create_ticket", payload
 
     def _prepare_submit_feedback(self, user_id: str, rating: Optional[int] = None,
@@ -1864,6 +1924,16 @@ class BaseAssistantRuntimeClient:
             "ticket_id": ticket_id,
         }
 
+    def _prepare_download_ticket_attachment(self, user_id: str, ticket_id: str,
+                                            file_url: str) -> tuple:
+        """Returns (endpoint, params)."""
+        return "support.download_ticket_attachment", {
+            "tenant_id": self.tenant_id,
+            "user_id": user_id,
+            "ticket_id": ticket_id,
+            "file_url": file_url,
+        }
+
     def _prepare_reply_to_ticket(self, user_id: str, ticket_id: str, message: str,
                                  attachment_ids: Optional[List[str]] = None) -> tuple:
         """Returns (endpoint, payload)."""

{assistant_runtime_sdk-1.5.0 → assistant_runtime_sdk-1.7.0}/assistant_runtime_sdk/client.py

@@ -1119,6 +1119,103 @@ class AssistantRuntimeClient(BaseAssistantRuntimeClient):
         endpoint, payload = self._prepare_set_tool_preference(user_id, tool_name, preference)
         return self._request_post_json(endpoint, payload)
 
+    # =========================================================================
+    # Routing Preference APIs
+    # =========================================================================
+    #
+    # Every one of these is POST, reads included: a rule's match_value is text
+    # the user wrote, and a GET would put it in the query string and from
+    # there into access logs.
+
+    def list_routing_preferences(self, user_id: str) -> Optional[Dict[str, Any]]:
+        """List this member's routing rules and their workspace's.
+
+        Args:
+            user_id: User identifier
+
+        Returns:
+            {"mine": [...], "team": [...], "mode": "off"|"shadow"|"on",
+             "can_manage_team": bool}. A team rule's `match_value` is None
+            unless the caller wrote it or administers the workspace.
+        """
+        endpoint, payload = self._prepare_list_routing_preferences(user_id)
+        return self._request_post_json(endpoint, payload)
+
+    def create_routing_preference(
+        self,
+        user_id: str,
+        scope: str,
+        match_kind: str,
+        match_value: str,
+        target_tier: str,
+        priority: int = None,
+        source_message_id: str = None,
+        origin: str = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Create a routing rule. Workspace scope is admin-capable only.
+
+        Args:
+            user_id: User identifier — the recorded author
+            scope: "Tenant" (workspace) or "User" (personal, not yet open)
+            match_kind: "doctype", "keyword" or "task_type"
+            match_value: what to match on
+            target_tier: "Economy", "Standard" or "Premium"
+            priority: lower runs first; defaults to 100
+            source_message_id: opaque id of the message this came from
+            origin: "panel", "settings" or "admin"
+
+        Returns:
+            {"preference_id": ..., "direction": ..., "status": ...}
+        """
+        endpoint, payload = self._prepare_create_routing_preference(
+            user_id, scope, match_kind, match_value, target_tier,
+            priority, source_message_id, origin)
+        return self._request_post_json(endpoint, payload)
+
+    def set_routing_preference_status(
+        self, user_id: str, preference_id: str, status: str,
+    ) -> Optional[Dict[str, Any]]:
+        """Suspend or re-enable a rule.
+
+        Args:
+            user_id: User identifier
+            preference_id: the rule
+            status: "active" or "suspended"
+
+        Returns:
+            {"preference_id": ..., "status": ...}
+        """
+        endpoint, payload = self._prepare_set_routing_preference_status(
+            user_id, preference_id, status)
+        return self._request_post_json(endpoint, payload)
+
+    def delete_routing_preference(
+        self, user_id: str, preference_id: str,
+    ) -> Optional[Dict[str, Any]]:
+        """Remove a rule outright.
+
+        Returns:
+            {"preference_id": ..., "deleted": True}
+        """
+        endpoint, payload = self._prepare_delete_routing_preference(
+            user_id, preference_id)
+        return self._request_post_json(endpoint, payload)
+
+    def forecast_routing_preference(
+        self, user_id: str, match_kind: str, match_value: str, target_tier: str,
+    ) -> Optional[Dict[str, Any]]:
+        """What a rule would cost, before saving it.
+
+        Returns:
+            {"direction": ..., "cost_multiplier": float|None,
+             "rates_reviewed": bool, "requires_confirmation": bool,
+             "can_manage_team": bool}. A null multiplier means the rates are
+            not configured — it never means parity.
+        """
+        endpoint, payload = self._prepare_forecast_routing_preference(
+            user_id, match_kind, match_value, target_tier)
+        return self._request_post_json(endpoint, payload)
+
     # =========================================================================
     # Billing & Subscription APIs
     # =========================================================================
@@ -2478,11 +2575,12 @@ class AssistantRuntimeClient(BaseAssistantRuntimeClient):
                       category: Optional[str] = None,
                       conversation_id: Optional[str] = None,
                       environment: Optional[dict] = None,
-                      attachment_ids: Optional[List[str]] = None) -> Optional[Dict[str, Any]]:
-        """Raise a support ticket. Returns {ticket_id, portal_link}."""
+                      attachment_ids: Optional[List[str]] = None,
+                      conversation_transcript: Optional[str] = None) -> Optional[Dict[str, Any]]:
+        """Raise a support ticket. Returns {ticket_id}."""
         endpoint, payload = self._prepare_create_ticket(
             user_id, subject, description, category, conversation_id, environment,
-            attachment_ids)
+            attachment_ids, conversation_transcript)
         return self._request_post_json(endpoint, payload)
 
     def submit_feedback(self, user_id: str, rating: Optional[int] = None,
@@ -2495,6 +2593,21 @@ class AssistantRuntimeClient(BaseAssistantRuntimeClient):
             user_id, rating, comment, category, conversation_id, environment)
         return self._request_post_json(endpoint, payload)
 
+    def download_ticket_attachment(self, user_id: str, ticket_id: str,
+                                   file_url: str) -> tuple:
+        """Download one attachment from a ticket the user owns.
+
+        Raw bytes rather than JSON, so a 10 MB screenshot doesn't get
+        base64-inflated through two hops.
+
+        Returns:
+            (content_bytes, content_type, filename) tuple.
+        """
+        endpoint, params = self._prepare_download_ticket_attachment(
+            user_id, ticket_id, file_url
+        )
+        return self._request_get_raw(endpoint, params)
+
     def list_tickets(self, user_id: str, status: Optional[str] = None) -> Optional[Dict[str, Any]]:
         """List the user's support tickets. Returns {tickets: [...]}."""
         endpoint, payload = self._prepare_list_tickets(user_id, status)

{assistant_runtime_sdk-1.5.0 → assistant_runtime_sdk-1.7.0}/assistant_runtime_sdk/streaming.py

@@ -18,10 +18,12 @@ class SSEEventType(str, Enum):
     STREAM_START = "stream_start"
     STREAM_CHUNK = "stream_chunk"
     STREAM_COMPLETE = "stream_complete"
+    STREAM_CANCELLED = "stream_cancelled"
     STREAM_ERROR = "stream_error"
 
     # AI response events
     THINKING = "thinking"
+    THINKING_COMPLETE = "thinking_complete"
 
     # Tool execution events
     TOOL_CALL_START = "tool_call_start"
@@ -32,7 +34,18 @@ class SSEEventType(str, Enum):
     TOOL_CANCELLED = "tool_cancelled"
 
     # Auto-model events
+    MODEL_SELECTED = "model_selected"
+    # Deprecated: AR has never emitted `model_fallback`. Kept because this is a
+    # published API; use MODEL_SELECTED.
     MODEL_FALLBACK = "model_fallback"
+    ROUTING_NOTICE = "routing_notice"
+
+    # Retrieval, planning and workflow events
+    SOURCES = "sources"
+    PLAN_COMPLETE = "plan_complete"
+    TASK_UPDATED = "task_updated"
+    WORKFLOW_CREATED = "workflow_created"
+    CONTEXT_SUMMARIZED = "context_summarized"
 
     # Rate limiting events
     RATE_LIMITED = "rate_limited"

{assistant_runtime_sdk-1.5.0 → assistant_runtime_sdk-1.7.0}/assistant_runtime_sdk/types.py

@@ -77,6 +77,41 @@ class StreamChunkData(TypedDict):
     chunk_index: Optional[int]
 
 
+class RoutingReceiptData(TypedDict):
+    """Why a given model answered a turn (`stream_complete.routing`).
+
+    Closed reason codes, never sentences — the client owns the wording. The
+    server cannot put a price, a credit rate or a review timestamp in here.
+    `preference` / `preference_source` are reserved; they stay null until
+    routing preferences ship.
+    """
+
+    v: int
+    mode: str                          # auto | explicit
+    incomplete: bool                   # true on the live emit, false at completion
+    selected_model: Optional[str]
+    selected_model_name: Optional[str]   # resolved server-side for catalogue-less clients
+    selected_tier: Optional[str]
+    fallback_from: Optional[str]
+    fallback_from_name: Optional[str]
+    classification: Optional[dict]     # complexity, task_type, source, floor_applied
+    floor: Optional[dict]              # tier, reasons[]
+    ceiling: Optional[dict]            # tier, source, reasons[]
+    bound_by: Optional[str]            # floor | ceiling | neither
+    target_tier: Optional[str]
+    band: Optional[str]                # only for an admin-capable viewer
+    band_disclosed: str                # full | capacity_managed
+    shortlist_size: int
+    pick_reason: str
+    notices: List[str]
+    thinking: dict                     # requested, applied, effort, not_applied_reason
+    credits: dict                      # actual
+    cycles: int
+    also_ran: List[str]
+    preference: Optional[dict]
+    preference_source: str
+
+
 class StreamCompleteData(TypedDict):
     """Data from stream_complete event."""
 
@@ -86,16 +121,25 @@ class StreamCompleteData(TypedDict):
     model_id: str
     session_id: str
     message_id: str
+    credits_used: Optional[float]
+    model_breakdown: Optional[dict]
+    routing: Optional[RoutingReceiptData]
 
 
-class ModelFallbackData(TypedDict):
-    """Data from model_fallback event (auto-mode)."""
+class ModelSelectedData(TypedDict):
+    """Data from the `model_selected` event (auto-mode)."""
 
-    original: str
+    original: Optional[str]
     selected: str
     provider: str
     tier: str
     fallback_attempted: bool
+    routing: Optional[RoutingReceiptData]
+
+
+# Deprecated: named for a `model_fallback` event that has never existed on the
+# wire. Kept as an alias because this is a published API.
+ModelFallbackData = ModelSelectedData
 
 
 class RateLimitedData(TypedDict):

{assistant_runtime_sdk-1.5.0 → assistant_runtime_sdk-1.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "assistant_runtime_sdk"
-version = "1.5.0"
+version = "1.7.0"
 description = "Python SDK for FAC Cloud - the Assistant Runtime AI assistant backend"
 readme = "README.md"
 license = {text = "AGPL-3.0"}