assistant-runtime-sdk 1.4.0__tar.gz → 1.6.0__tar.gz

{assistant_runtime_sdk-1.4.0 → assistant_runtime_sdk-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assistant_runtime_sdk
-Version: 1.4.0
+Version: 1.6.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.4.0 → assistant_runtime_sdk-1.6.0}/assistant_runtime_sdk/__init__.py

@@ -53,7 +53,7 @@ Standalone Functions:
 
 """
 
-__version__ = "1.4.0"
+__version__ = "1.6.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.4.0 → assistant_runtime_sdk-1.6.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
     # =========================================================================
@@ -1489,10 +1539,11 @@ class AsyncAssistantRuntimeClient(BaseAssistantRuntimeClient):
         input_data: Dict[str, Any],
         user_id: str,
         trigger_id: str,
+        workflow_docname: Optional[str] = None,
     ) -> Optional[Dict[str, Any]]:
         """Async version of AssistantRuntimeClient.execute_workflow_from_event."""
         endpoint, payload = self._prepare_execute_workflow_from_event(
-            workflow_name, input_data, user_id, trigger_id,
+            workflow_name, input_data, user_id, trigger_id, workflow_docname,
         )
         return await self._request_post_json(endpoint, payload, api_base=self.workflows_api_base)
 
@@ -1668,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,

{assistant_runtime_sdk-1.4.0 → assistant_runtime_sdk-1.6.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
     # =========================================================================
@@ -1617,14 +1674,20 @@ class BaseAssistantRuntimeClient:
         input_data: Dict[str, Any],
         user_id: str,
         trigger_id: str,
+        workflow_docname: Optional[str] = None,
     ) -> tuple:
-        return "workflows.execute_from_event", {
+        payload = {
             "tenant_id": self.tenant_id,
             "workflow_name": workflow_name,
             "input_data": input_data,
             "user_id": user_id,
             "trigger_id": trigger_id,
         }
+        # The docname is the stable binding; workflow_name is a mutable display
+        # label a rename can invalidate. Both travel so an older AR keeps working.
+        if workflow_docname:
+            payload["workflow_docname"] = workflow_docname
+        return "workflows.execute_from_event", payload
 
     def _prepare_cancel_workflow_run(self, run_name: str) -> tuple:
         return "workflows.cancel_run", {
@@ -1796,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,
@@ -1812,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,

{assistant_runtime_sdk-1.4.0 → assistant_runtime_sdk-1.6.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
     # =========================================================================
@@ -2193,21 +2290,24 @@ class AssistantRuntimeClient(BaseAssistantRuntimeClient):
         input_data: Dict[str, Any],
         user_id: str,
         trigger_id: str,
+        workflow_docname: Optional[str] = None,
     ) -> Optional[Dict[str, Any]]:
         """
-        Trigger workflow execution from a FACO-side doc event.
+        Trigger workflow execution from a FAC-side doc event.
 
         Args:
-            workflow_name: AR Workflow.workflow_name (human identifier)
+            workflow_name: AR Workflow.workflow_name (mutable display label)
             input_data: Structured payload {trigger, doc, changed_fields}
             user_id: User on the customer bench who saved the doc
-            trigger_id: FACO AR Workflow Trigger name (for traceability)
+            trigger_id: FAC Workflow Trigger name (for traceability)
+            workflow_docname: AR Workflow docname (WF-#####). Preferred — a
+                rename cannot invalidate it. Falls back to workflow_name.
 
         Returns:
             {"status": "queued", "run_name": str, "run_id": str, ...}
         """
         endpoint, payload = self._prepare_execute_workflow_from_event(
-            workflow_name, input_data, user_id, trigger_id,
+            workflow_name, input_data, user_id, trigger_id, workflow_docname,
         )
         return self._request_post_json(endpoint, payload, api_base=self.workflows_api_base)
 
@@ -2475,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,

{assistant_runtime_sdk-1.4.0 → assistant_runtime_sdk-1.6.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.4.0 → assistant_runtime_sdk-1.6.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.4.0 → assistant_runtime_sdk-1.6.0}/pyproject.toml

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