assistant-runtime-sdk 1.0.0__py3-none-any.whl

assistant_runtime_sdk/exceptions.py

@@ -0,0 +1,146 @@
+# Assistant Runtime SDK - Exceptions
+# Copyright (C) 2025 Paul Clinton
+# AGPL-3.0 License
+
+"""
+Custom exceptions for the Assistant Runtime SDK.
+
+All exceptions inherit from ARError for easy catching.
+"""
+
+from typing import Optional, List
+
+
+class ARError(Exception):
+    """Base exception for all Assistant Runtime SDK errors."""
+
+    def __init__(self, message: str, error_code: Optional[str] = None):
+        super().__init__(message)
+        self.message = message
+        self.error_code = error_code
+
+    def __str__(self) -> str:
+        if self.error_code:
+            return f"[{self.error_code}] {self.message}"
+        return self.message
+
+
+class ARAuthenticationError(ARError):
+    """
+    HMAC signature validation failed.
+
+    This typically indicates:
+    - Invalid tenant_secret
+    - Clock skew between client and server
+    - Tampered request parameters
+    """
+
+    def __init__(self, message: str = "Authentication failed"):
+        super().__init__(message, error_code="AUTH_FAILED")
+
+
+class ARRateLimitError(ARError):
+    """
+    Rate limit exceeded.
+
+    Contains retry_after indicating seconds until retry is possible.
+    May include models_checked if using auto-model selection.
+    """
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        retry_after: Optional[float] = None,
+        models_checked: Optional[List[str]] = None,
+    ):
+        super().__init__(message, error_code="RATE_LIMITED")
+        self.retry_after = retry_after
+        self.models_checked = models_checked or []
+
+    def __str__(self) -> str:
+        base = super().__str__()
+        if self.retry_after:
+            return f"{base} (retry after {self.retry_after:.1f}s)"
+        return base
+
+
+class ARStreamError(ARError):
+    """
+    SSE streaming error.
+
+    Raised when:
+    - Connection drops during streaming
+    - Malformed SSE data received
+    - Server sends error event
+    """
+
+    def __init__(self, message: str = "Streaming error", error_code: Optional[str] = None):
+        super().__init__(message, error_code=error_code or "STREAM_ERROR")
+
+
+class ARConfigurationError(ARError):
+    """
+    Invalid configuration.
+
+    Raised when:
+    - Missing required parameters (tenant_id, tenant_secret)
+    - Invalid AR URL format
+    - Missing user_id where required
+    """
+
+    def __init__(self, message: str = "Configuration error"):
+        super().__init__(message, error_code="CONFIG_ERROR")
+
+
+class ARAPIError(ARError):
+    """
+    API request failed.
+
+    Contains HTTP status code and response details.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        response_data: Optional[dict] = None,
+    ):
+        error_code = f"HTTP_{status_code}" if status_code else "API_ERROR"
+        super().__init__(message, error_code=error_code)
+        self.status_code = status_code
+        self.response_data = response_data or {}
+
+
+class ARTimeoutError(ARError):
+    """
+    Request timed out.
+
+    Raised when connection or read timeout is exceeded.
+    """
+
+    def __init__(self, message: str = "Request timed out"):
+        super().__init__(message, error_code="TIMEOUT")
+
+
+class ARConnectionError(ARError):
+    """
+    Connection failed.
+
+    Raised when unable to connect to Assistant Runtime server.
+    """
+
+    def __init__(self, message: str = "Connection failed"):
+        super().__init__(message, error_code="CONNECTION_ERROR")
+
+
+class ARBillingUnavailableError(ARError):
+    """
+    Billing features are not available on this server.
+
+    Raised when:
+    - The payments app is not installed on the target server
+    - check_billing_available() returned False and a billing method was called
+    """
+
+    def __init__(self, message: str = "Billing is not available"):
+        super().__init__(message, error_code="BILLING_UNAVAILABLE")

assistant_runtime_sdk/skills.py

@@ -0,0 +1,328 @@
+# Assistant Runtime SDK - Skill Provider
+# Copyright (C) 2025 Paul Clinton
+# AGPL-3.0 License
+
+"""
+Skill Provider - Bridges MCP resources to Strands Agent.
+
+When MCP server has resources enabled, tools have minimal descriptions
+with hints like "See fac://tools/create_document for usage guide."
+
+This module provides the get_skill tool that allows LLMs to fetch
+the full documentation on-demand, reducing context token usage by ~90%.
+
+Usage:
+    from assistant_runtime_sdk import AssistantRuntimeClient
+    from assistant_runtime_sdk.skills import SkillProvider
+
+    client = AssistantRuntimeClient(tenant_id, tenant_secret)
+    skills = SkillProvider(client, user_id="user@example.com")
+
+    # Add to Strands agent tools
+    from strands import Agent
+    agent = Agent(
+        tools=[*mcp_tools, skills.get_skill_tool()]
+    )
+"""
+
+from typing import Dict, Optional, TYPE_CHECKING, Callable
+
+if TYPE_CHECKING:
+    from .client import AssistantRuntimeClient
+    from .async_client import AsyncAssistantRuntimeClient
+
+
+class SkillProvider:
+    """
+    Provides the get_skill tool for Strands agents.
+
+    The get_skill tool allows LLMs to fetch detailed documentation for any tool
+    before using it. This enables a pattern where tools have minimal descriptions
+    (saving context tokens) and the LLM can request full documentation on-demand.
+
+    Attributes:
+        _client: Assistant Runtime client instance for API calls
+        _user_id: User identifier for API authentication
+        _cache: Optional in-memory cache for skill documentation
+
+    Example:
+        >>> from assistant_runtime_sdk import AssistantRuntimeClient
+        >>> from assistant_runtime_sdk.skills import SkillProvider
+        >>>
+        >>> client = AssistantRuntimeClient(tenant_id, tenant_secret)
+        >>> skills = SkillProvider(client, user_id="user@example.com")
+        >>>
+        >>> # Get the tool function to add to agent
+        >>> skill_tool = skills.get_skill_tool()
+        >>>
+        >>> # Or use directly
+        >>> docs = skills.fetch_skill("create_document")
+        >>> print(docs)
+    """
+
+    def __init__(
+        self,
+        client: "AssistantRuntimeClient",
+        user_id: str,
+        cache_enabled: bool = True,
+    ):
+        """
+        Initialize the SkillProvider.
+
+        Args:
+            client: Assistant Runtime client instance (sync or async)
+            user_id: User identifier for API authentication
+            cache_enabled: Whether to cache skill documentation (default: True)
+        """
+        self._client = client
+        self._user_id = user_id
+        self._cache: Optional[Dict[str, str]] = {} if cache_enabled else None
+
+    def get_skill_tool(self) -> Callable[[str], str]:
+        """
+        Returns the get_skill tool function decorated for Strands.
+
+        The returned function can be passed directly to the Strands Agent's
+        tools parameter. It will be available to the LLM as a callable tool.
+
+        Returns:
+            A Strands-compatible tool function
+
+        Example:
+            >>> skills = SkillProvider(client, user_id)
+            >>> agent = Agent(tools=[skills.get_skill_tool()])
+        """
+        try:
+            from strands import tool
+        except ImportError:
+            raise ImportError(
+                "strands-agents is required for get_skill_tool(). "
+                "Install it with: pip install strands-agents"
+            )
+
+        @tool
+        def get_skill(tool_name: str) -> str:
+            """Get detailed documentation for a tool before using it.
+
+            Call this when you see a tool with a minimal description that says
+            "See fac://tools/... for usage guide" to get the full documentation.
+
+            Args:
+                tool_name: The name of the tool (e.g., "create_document", "list_documents")
+
+            Returns:
+                Detailed markdown documentation including:
+                - Full description of what the tool does
+                - All parameters with types and descriptions
+                - Usage examples
+                - Important notes and warnings
+            """
+            return self.fetch_skill(tool_name)
+
+        return get_skill
+
+    def fetch_skill(self, tool_name: str) -> str:
+        """
+        Fetch skill documentation for a tool (sync).
+
+        This is the core method that retrieves documentation from the
+        resources API. Results are cached if caching is enabled.
+
+        Args:
+            tool_name: Name of the tool to get documentation for
+
+        Returns:
+            Markdown documentation string, or error message if not found
+        """
+        # Check cache first
+        if self._cache is not None and tool_name in self._cache:
+            return self._cache[tool_name]
+
+        # Build URI - the MCP server uses fac://tools/{tool_name} format
+        uri = f"fac://tools/{tool_name}"
+
+        try:
+            result = self._client.read_resource(self._user_id, uri)
+
+            if result and result.get("content"):
+                content = result["content"]
+
+                # Cache the result
+                if self._cache is not None:
+                    self._cache[tool_name] = content
+
+                return content
+
+            # Check for error response
+            if result and result.get("error"):
+                return f"Error fetching documentation for '{tool_name}': {result.get('error')}"
+
+        except Exception as e:
+            return f"Could not retrieve documentation for '{tool_name}': {str(e)}"
+
+        return (
+            f"No documentation available for tool '{tool_name}'. "
+            "The tool may not have detailed docs, or the resources feature may be disabled on the MCP server."
+        )
+
+    def clear_cache(self) -> None:
+        """Clear the skill documentation cache."""
+        if self._cache is not None:
+            self._cache.clear()
+
+    def preload_skills(self, tool_names: list[str]) -> None:
+        """
+        Preload documentation for a list of tools.
+
+        Useful for warming up the cache with commonly used tools
+        before starting a conversation.
+
+        Args:
+            tool_names: List of tool names to preload
+        """
+        for name in tool_names:
+            self.fetch_skill(name)
+
+    def get_cached_skills(self) -> list[str]:
+        """
+        Get list of tool names currently in cache.
+
+        Returns:
+            List of cached tool names, or empty list if caching disabled
+        """
+        if self._cache is not None:
+            return list(self._cache.keys())
+        return []
+
+
+class AsyncSkillProvider:
+    """
+    Async version of SkillProvider for use with AsyncAssistantRuntimeClient.
+
+    Provides the same functionality as SkillProvider but with async methods
+    for use in async contexts.
+
+    Example:
+        >>> async with AsyncAssistantRuntimeClient(tenant_id, tenant_secret) as client:
+        ...     skills = AsyncSkillProvider(client, user_id="user@example.com")
+        ...     skill_tool = skills.get_skill_tool()
+        ...     # Add to async agent
+    """
+
+    def __init__(
+        self,
+        client: "AsyncAssistantRuntimeClient",
+        user_id: str,
+        cache_enabled: bool = True,
+    ):
+        """
+        Initialize the AsyncSkillProvider.
+
+        Args:
+            client: AsyncAssistantRuntimeClient instance
+            user_id: User identifier for API authentication
+            cache_enabled: Whether to cache skill documentation (default: True)
+        """
+        self._client = client
+        self._user_id = user_id
+        self._cache: Optional[Dict[str, str]] = {} if cache_enabled else None
+
+    def get_skill_tool(self) -> Callable[[str], str]:
+        """
+        Returns the async get_skill tool function decorated for Strands.
+
+        Returns:
+            A Strands-compatible async tool function
+        """
+        try:
+            from strands import tool
+        except ImportError:
+            raise ImportError(
+                "strands-agents is required for get_skill_tool(). "
+                "Install it with: pip install strands-agents"
+            )
+
+        @tool
+        async def get_skill(tool_name: str) -> str:
+            """Get detailed documentation for a tool before using it.
+
+            Call this when you see a tool with a minimal description that says
+            "See fac://tools/... for usage guide" to get the full documentation.
+
+            Args:
+                tool_name: The name of the tool (e.g., "create_document", "list_documents")
+
+            Returns:
+                Detailed markdown documentation including:
+                - Full description of what the tool does
+                - All parameters with types and descriptions
+                - Usage examples
+                - Important notes and warnings
+            """
+            return await self.fetch_skill(tool_name)
+
+        return get_skill
+
+    async def fetch_skill(self, tool_name: str) -> str:
+        """
+        Fetch skill documentation for a tool (async).
+
+        Args:
+            tool_name: Name of the tool to get documentation for
+
+        Returns:
+            Markdown documentation string, or error message if not found
+        """
+        # Check cache first
+        if self._cache is not None and tool_name in self._cache:
+            return self._cache[tool_name]
+
+        uri = f"fac://tools/{tool_name}"
+
+        try:
+            result = await self._client.read_resource(self._user_id, uri)
+
+            if result and result.get("content"):
+                content = result["content"]
+
+                if self._cache is not None:
+                    self._cache[tool_name] = content
+
+                return content
+
+            if result and result.get("error"):
+                return f"Error fetching documentation for '{tool_name}': {result.get('error')}"
+
+        except Exception as e:
+            return f"Could not retrieve documentation for '{tool_name}': {str(e)}"
+
+        return (
+            f"No documentation available for tool '{tool_name}'. "
+            "The tool may not have detailed docs, or the resources feature may be disabled."
+        )
+
+    def clear_cache(self) -> None:
+        """Clear the skill documentation cache."""
+        if self._cache is not None:
+            self._cache.clear()
+
+    async def preload_skills(self, tool_names: list[str]) -> None:
+        """
+        Preload documentation for a list of tools (async).
+
+        Args:
+            tool_names: List of tool names to preload
+        """
+        for name in tool_names:
+            await self.fetch_skill(name)
+
+    def get_cached_skills(self) -> list[str]:
+        """
+        Get list of tool names currently in cache.
+
+        Returns:
+            List of cached tool names, or empty list if caching disabled
+        """
+        if self._cache is not None:
+            return list(self._cache.keys())
+        return []

assistant_runtime_sdk/streaming.py

@@ -0,0 +1,223 @@
+# Assistant Runtime SDK - Streaming Utilities
+# Copyright (C) 2025 Paul Clinton
+# AGPL-3.0 License
+
+"""
+Server-Sent Events (SSE) parsing utilities for Assistant Runtime streaming responses.
+"""
+
+import json
+from enum import Enum
+from typing import Optional, Dict, Any, Iterator, Tuple
+
+
+class SSEEventType(str, Enum):
+    """SSE event types used by Assistant Runtime streaming API."""
+
+    # Core streaming events
+    STREAM_START = "stream_start"
+    STREAM_CHUNK = "stream_chunk"
+    STREAM_COMPLETE = "stream_complete"
+    STREAM_ERROR = "stream_error"
+
+    # AI response events
+    THINKING = "thinking"
+
+    # Tool execution events
+    TOOL_CALL_START = "tool_call_start"
+    TOOL_CALL_RESULT = "tool_call_result"
+
+    # Human-in-the-loop events
+    APPROVAL_REQUIRED = "approval_required"
+    TOOL_CANCELLED = "tool_cancelled"
+
+    # Auto-model events
+    MODEL_FALLBACK = "model_fallback"
+
+    # Rate limiting events
+    RATE_LIMITED = "rate_limited"
+
+    # Unknown event (fallback)
+    UNKNOWN = "unknown"
+
+    @classmethod
+    def from_string(cls, value: str) -> "SSEEventType":
+        """Convert string to SSEEventType, returning UNKNOWN if not found."""
+        try:
+            return cls(value)
+        except ValueError:
+            return cls.UNKNOWN
+
+
+def parse_sse_line(line: str) -> Optional[Dict[str, Any]]:
+    """
+    Parse a single SSE line.
+
+    Args:
+        line: Raw SSE line (e.g., "event: stream_chunk" or "data: {...}")
+
+    Returns:
+        Parsed event dict with 'type' and 'value', or None for empty/comment lines
+
+    Example:
+        >>> parse_sse_line("event: stream_chunk")
+        {'type': 'event_name', 'value': 'stream_chunk'}
+        >>> parse_sse_line("data: {\"content\": \"Hello\"}")
+        {'type': 'data', 'value': {'content': 'Hello'}}
+        >>> parse_sse_line(": heartbeat")
+        {'type': 'heartbeat', 'value': 'heartbeat'}
+    """
+    line = line.strip()
+
+    # Skip empty lines
+    if not line:
+        return None
+
+    # Surface heartbeat comments so callers can use them as keepalive signals
+    if line.startswith(":"):
+        return {"type": "heartbeat", "value": line[1:].strip()}
+
+    if line.startswith("event:"):
+        return {"type": "event_name", "value": line[6:].strip()}
+    elif line.startswith("data:"):
+        data_str = line[5:].strip()
+        if data_str:
+            try:
+                return {"type": "data", "value": json.loads(data_str)}
+            except json.JSONDecodeError:
+                # Return raw string if not valid JSON
+                return {"type": "data", "value": data_str}
+    elif line.startswith("id:"):
+        return {"type": "id", "value": line[3:].strip()}
+    elif line.startswith("retry:"):
+        try:
+            return {"type": "retry", "value": int(line[6:].strip())}
+        except ValueError:
+            return None
+
+    return None
+
+
+def parse_sse_stream(lines: Iterator[str]) -> Iterator[Dict[str, Any]]:
+    """
+    Parse an SSE stream from an iterator of lines.
+
+    Yields complete events as dicts with 'event' and 'data' keys.
+
+    Args:
+        lines: Iterator of SSE lines (from response.iter_lines() or similar)
+
+    Yields:
+        Event dicts: {'event': 'stream_chunk', 'data': {...}}
+
+    Example:
+        >>> for event in parse_sse_stream(response.iter_lines()):
+        ...     print(event['event'], event['data'])
+    """
+    current_event: Optional[str] = None
+
+    for line in lines:
+        if line is None:
+            continue
+
+        # Handle both str and bytes
+        if isinstance(line, bytes):
+            line = line.decode("utf-8")
+
+        parsed = parse_sse_line(line)
+        if not parsed:
+            continue
+
+        if parsed["type"] == "heartbeat":
+            yield {"event": "heartbeat", "data": {}}
+        elif parsed["type"] == "event_name":
+            current_event = parsed["value"]
+        elif parsed["type"] == "data":
+            yield {"event": current_event or "message", "data": parsed["value"]}
+            current_event = None
+
+
+def format_sse_event(event_type: str, data: Any, event_id: Optional[str] = None) -> str:
+    """
+    Format data as an SSE event string.
+
+    Useful for servers that need to send SSE responses.
+
+    Args:
+        event_type: Event type name
+        data: Event data (will be JSON serialized)
+        event_id: Optional event ID
+
+    Returns:
+        Formatted SSE event string
+
+    Example:
+        >>> print(format_sse_event("stream_chunk", {"content": "Hello"}))
+        event: stream_chunk
+        data: {"content": "Hello"}
+
+    """
+    lines = []
+
+    if event_id:
+        lines.append(f"id: {event_id}")
+
+    lines.append(f"event: {event_type}")
+
+    if isinstance(data, str):
+        lines.append(f"data: {data}")
+    else:
+        lines.append(f"data: {json.dumps(data)}")
+
+    lines.append("")  # Empty line to end event
+    return "\n".join(lines) + "\n"
+
+
+def is_terminal_event(event_type: str) -> bool:
+    """
+    Check if an event type indicates the stream has ended.
+
+    Args:
+        event_type: The event type string
+
+    Returns:
+        True if this is a terminal event (stream_complete, stream_error, rate_limited)
+
+    Example:
+        >>> is_terminal_event("stream_chunk")
+        False
+        >>> is_terminal_event("stream_complete")
+        True
+    """
+    terminal_events = {
+        SSEEventType.STREAM_COMPLETE.value,
+        SSEEventType.STREAM_ERROR.value,
+        SSEEventType.RATE_LIMITED.value,
+    }
+    return event_type in terminal_events
+
+
+def extract_stream_metrics(complete_event: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Extract metrics from a stream_complete event.
+
+    Args:
+        complete_event: The data from a stream_complete event
+
+    Returns:
+        Dict with normalized metrics (tokens_used, model_id, duration_ms, etc.)
+
+    Example:
+        >>> metrics = extract_stream_metrics(event['data'])
+        >>> print(f"Used {metrics.get('tokens_used', 0)} tokens")
+    """
+    data = complete_event.get("data", complete_event) if isinstance(complete_event, dict) else {}
+
+    return {
+        "tokens_used": data.get("tokens_used", 0),
+        "tokens_actual": data.get("tokens_actual", 0),
+        "model_id": data.get("model_id"),
+        "message_id": data.get("message_id"),
+        "session_id": data.get("session_id"),
+        "full_response": data.get("full_response", ""),
+    }