agentrun-sdk 0.1.2__py3-none-any.whl

agentrun_sdk/tools/watcher.py

@@ -0,0 +1,136 @@
+"""Tool watcher for hot reloading tools during development.
+
+This module provides functionality to watch tool directories for changes and automatically reload tools when they are
+modified.
+"""
+
+import logging
+from pathlib import Path
+from typing import Any, Dict, Set
+
+from watchdog.events import FileSystemEventHandler
+from watchdog.observers import Observer
+
+from .registry import ToolRegistry
+
+logger = logging.getLogger(__name__)
+
+
+class ToolWatcher:
+    """Watches tool directories for changes and reloads tools when they are modified."""
+
+    # This class uses class variables for the observer and handlers because watchdog allows only one Observer instance
+    # per directory. Using class variables ensures that all ToolWatcher instances share a single Observer, with the
+    # MasterChangeHandler routing file system events to the appropriate individual handlers for each registry. This
+    # design pattern avoids conflicts when multiple tool registries are watching the same directories.
+
+    _shared_observer = None
+    _watched_dirs: Set[str] = set()
+    _observer_started = False
+    _registry_handlers: Dict[str, Dict[int, "ToolWatcher.ToolChangeHandler"]] = {}
+
+    def __init__(self, tool_registry: ToolRegistry) -> None:
+        """Initialize a tool watcher for the given tool registry.
+
+        Args:
+            tool_registry: The tool registry to report changes.
+        """
+        self.tool_registry = tool_registry
+        self.start()
+
+    class ToolChangeHandler(FileSystemEventHandler):
+        """Handler for tool file changes."""
+
+        def __init__(self, tool_registry: ToolRegistry) -> None:
+            """Initialize a tool change handler.
+
+            Args:
+                tool_registry: The tool registry to update when tools change.
+            """
+            self.tool_registry = tool_registry
+
+        def on_modified(self, event: Any) -> None:
+            """Reload tool if file modification detected.
+
+            Args:
+                event: The file system event that triggered this handler.
+            """
+            if event.src_path.endswith(".py"):
+                tool_path = Path(event.src_path)
+                tool_name = tool_path.stem
+
+                if tool_name not in ["__init__"]:
+                    logger.debug("tool_name=<%s> | tool change detected", tool_name)
+                    try:
+                        self.tool_registry.reload_tool(tool_name)
+                    except Exception as e:
+                        logger.error("tool_name=<%s>, exception=<%s> | failed to reload tool", tool_name, str(e))
+
+    class MasterChangeHandler(FileSystemEventHandler):
+        """Master handler that delegates to all registered handlers."""
+
+        def __init__(self, dir_path: str) -> None:
+            """Initialize a master change handler for a specific directory.
+
+            Args:
+                dir_path: The directory path to watch.
+            """
+            self.dir_path = dir_path
+
+        def on_modified(self, event: Any) -> None:
+            """Delegate file modification events to all registered handlers.
+
+            Args:
+                event: The file system event that triggered this handler.
+            """
+            if event.src_path.endswith(".py"):
+                tool_path = Path(event.src_path)
+                tool_name = tool_path.stem
+
+                if tool_name not in ["__init__"]:
+                    # Delegate to all registered handlers for this directory
+                    for handler in ToolWatcher._registry_handlers.get(self.dir_path, {}).values():
+                        try:
+                            handler.on_modified(event)
+                        except Exception as e:
+                            logger.error("exception=<%s> | handler error", str(e))
+
+    def start(self) -> None:
+        """Start watching all tools directories for changes."""
+        # Initialize shared observer if not already done
+        if ToolWatcher._shared_observer is None:
+            ToolWatcher._shared_observer = Observer()
+
+        # Create handler for this instance
+        self.tool_change_handler = self.ToolChangeHandler(self.tool_registry)
+        registry_id = id(self.tool_registry)
+
+        # Get tools directories to watch
+        tools_dirs = self.tool_registry.get_tools_dirs()
+
+        for tools_dir in tools_dirs:
+            dir_str = str(tools_dir)
+
+            # Initialize the registry handlers dict for this directory if needed
+            if dir_str not in ToolWatcher._registry_handlers:
+                ToolWatcher._registry_handlers[dir_str] = {}
+
+            # Store this handler with its registry id
+            ToolWatcher._registry_handlers[dir_str][registry_id] = self.tool_change_handler
+
+            # Schedule or update the master handler for this directory
+            if dir_str not in ToolWatcher._watched_dirs:
+                # First time seeing this directory, create a master handler
+                master_handler = self.MasterChangeHandler(dir_str)
+                ToolWatcher._shared_observer.schedule(master_handler, dir_str, recursive=False)
+                ToolWatcher._watched_dirs.add(dir_str)
+                logger.debug("tools_dir=<%s> | started watching tools directory", tools_dir)
+            else:
+                # Directory already being watched, just log it
+                logger.debug("tools_dir=<%s> | directory already being watched", tools_dir)
+
+        # Start the observer if not already started
+        if not ToolWatcher._observer_started:
+            ToolWatcher._shared_observer.start()
+            ToolWatcher._observer_started = True
+            logger.debug("tool directory watching initialized")

agentrun_sdk/types/__init__.py

@@ -0,0 +1,5 @@
+"""SDK type definitions."""
+
+from .collections import PaginatedList
+
+__all__ = ["PaginatedList"]

agentrun_sdk/types/collections.py

@@ -0,0 +1,23 @@
+"""Generic collection types for the Strands SDK."""
+
+from typing import Generic, List, Optional, TypeVar
+
+T = TypeVar("T")
+
+
+class PaginatedList(list, Generic[T]):
+    """A generic list-like object that includes a pagination token.
+
+    This maintains backwards compatibility by inheriting from list,
+    so existing code that expects List[T] will continue to work.
+    """
+
+    def __init__(self, data: List[T], token: Optional[str] = None):
+        """Initialize a PaginatedList with data and an optional pagination token.
+
+        Args:
+            data: The list of items to store.
+            token: Optional pagination token for retrieving additional items.
+        """
+        super().__init__(data)
+        self.pagination_token = token

agentrun_sdk/types/content.py

@@ -0,0 +1,188 @@
+"""Content-related type definitions for the SDK.
+
+This module defines the types used to represent messages, content blocks, and other content-related structures in the
+SDK. These types are modeled after the Bedrock API.
+
+- Bedrock docs: https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Types_Amazon_Bedrock_Runtime.html
+"""
+
+from typing import Dict, List, Literal, Optional
+
+from typing_extensions import TypedDict
+
+from .media import DocumentContent, ImageContent, VideoContent
+from .tools import ToolResult, ToolUse
+
+
+class GuardContentText(TypedDict):
+    """Text content to be evaluated by guardrails.
+
+    Attributes:
+        qualifiers: The qualifiers describing the text block.
+        text: The input text details to be evaluated by the guardrail.
+    """
+
+    qualifiers: List[Literal["grounding_source", "query", "guard_content"]]
+    text: str
+
+
+class GuardContent(TypedDict):
+    """Content block to be evaluated by guardrails.
+
+    Attributes:
+        text: Text within content block to be evaluated by the guardrail.
+    """
+
+    text: GuardContentText
+
+
+class ReasoningTextBlock(TypedDict, total=False):
+    """Contains the reasoning that the model used to return the output.
+
+    Attributes:
+        signature: A token that verifies that the reasoning text was generated by the model.
+        text: The reasoning that the model used to return the output.
+    """
+
+    signature: Optional[str]
+    text: str
+
+
+class ReasoningContentBlock(TypedDict, total=False):
+    """Contains content regarding the reasoning that is carried out by the model.
+
+    Attributes:
+        reasoningText: The reasoning that the model used to return the output.
+        redactedContent: The content in the reasoning that was encrypted by the model provider for safety reasons.
+    """
+
+    reasoningText: ReasoningTextBlock
+    redactedContent: bytes
+
+
+class CachePoint(TypedDict):
+    """A cache point configuration for optimizing conversation history.
+
+    Attributes:
+        type: The type of cache point, typically "default".
+    """
+
+    type: str
+
+
+class ContentBlock(TypedDict, total=False):
+    """A block of content for a message that you pass to, or receive from, a model.
+
+    Attributes:
+        cachePoint: A cache point configuration to optimize conversation history.
+        document: A document to include in the message.
+        guardContent: Contains the content to assess with the guardrail.
+        image: Image to include in the message.
+        reasoningContent: Contains content regarding the reasoning that is carried out by the model.
+        text: Text to include in the message.
+        toolResult: The result for a tool request that a model makes.
+        toolUse: Information about a tool use request from a model.
+        video: Video to include in the message.
+    """
+
+    cachePoint: CachePoint
+    document: DocumentContent
+    guardContent: GuardContent
+    image: ImageContent
+    reasoningContent: ReasoningContentBlock
+    text: str
+    toolResult: ToolResult
+    toolUse: ToolUse
+    video: VideoContent
+
+
+class SystemContentBlock(TypedDict, total=False):
+    """Contains configurations for instructions to provide the model for how to handle input.
+
+    Attributes:
+        guardContent: A content block to assess with the guardrail.
+        text: A system prompt for the model.
+    """
+
+    guardContent: GuardContent
+    text: str
+
+
+class DeltaContent(TypedDict, total=False):
+    """A block of content in a streaming response.
+
+    Attributes:
+        text: The content text.
+        toolUse: Information about a tool that the model is requesting to use.
+    """
+
+    text: str
+    toolUse: Dict[Literal["input"], str]
+
+
+class ContentBlockStartToolUse(TypedDict):
+    """The start of a tool use block.
+
+    Attributes:
+        name: The name of the tool that the model is requesting to use.
+        toolUseId: The ID for the tool request.
+    """
+
+    name: str
+    toolUseId: str
+
+
+class ContentBlockStart(TypedDict, total=False):
+    """Content block start information.
+
+    Attributes:
+        toolUse: Information about a tool that the model is requesting to use.
+    """
+
+    toolUse: Optional[ContentBlockStartToolUse]
+
+
+class ContentBlockDelta(TypedDict):
+    """The content block delta event.
+
+    Attributes:
+        contentBlockIndex: The block index for a content block delta event.
+        delta: The delta for a content block delta event.
+    """
+
+    contentBlockIndex: int
+    delta: DeltaContent
+
+
+class ContentBlockStop(TypedDict):
+    """A content block stop event.
+
+    Attributes:
+        contentBlockIndex: The index for a content block.
+    """
+
+    contentBlockIndex: int
+
+
+Role = Literal["user", "assistant"]
+"""Role of a message sender.
+
+- "user": Messages from the user to the assistant
+- "assistant": Messages from the assistant to the user
+"""
+
+
+class Message(TypedDict):
+    """A message in a conversation with the agent.
+
+    Attributes:
+        content: The message content.
+        role: The role of the message sender.
+    """
+
+    content: List[ContentBlock]
+    role: Role
+
+
+Messages = List[Message]
+"""A list of messages representing a conversation."""

agentrun_sdk/types/event_loop.py

@@ -0,0 +1,48 @@
+"""Event loop-related type definitions for the SDK."""
+
+from typing import Literal
+
+from typing_extensions import TypedDict
+
+
+class Usage(TypedDict):
+    """Token usage information for model interactions.
+
+    Attributes:
+        inputTokens: Number of tokens sent in the request to the model..
+        outputTokens: Number of tokens that the model generated for the request.
+        totalTokens: Total number of tokens (input + output).
+    """
+
+    inputTokens: int
+    outputTokens: int
+    totalTokens: int
+
+
+class Metrics(TypedDict):
+    """Performance metrics for model interactions.
+
+    Attributes:
+        latencyMs (int): Latency of the model request in milliseconds.
+    """
+
+    latencyMs: int
+
+
+StopReason = Literal[
+    "content_filtered",
+    "end_turn",
+    "guardrail_intervened",
+    "max_tokens",
+    "stop_sequence",
+    "tool_use",
+]
+"""Reason for the model ending its response generation.
+
+- "content_filtered": Content was filtered due to policy violation
+- "end_turn": Normal completion of the response
+- "guardrail_intervened": Guardrail system intervened
+- "max_tokens": Maximum token limit reached
+- "stop_sequence": Stop sequence encountered
+- "tool_use": Model requested to use a tool
+"""

agentrun_sdk/types/exceptions.py

@@ -0,0 +1,81 @@
+"""Exception-related type definitions for the SDK."""
+
+from typing import Any
+
+from .content import Message
+
+
+class EventLoopException(Exception):
+    """Exception raised by the event loop."""
+
+    def __init__(self, original_exception: Exception, request_state: Any = None) -> None:
+        """Initialize exception.
+
+        Args:
+            original_exception: The original exception that was raised.
+            request_state: The state of the request at the time of the exception.
+        """
+        self.original_exception = original_exception
+        self.request_state = request_state if request_state is not None else {}
+        super().__init__(str(original_exception))
+
+
+class MaxTokensReachedException(Exception):
+    """Exception raised when the model reaches its maximum token generation limit.
+
+    This exception is raised when the model stops generating tokens because it has reached the maximum number of
+    tokens allowed for output generation. This can occur when the model's max_tokens parameter is set too low for
+    the complexity of the response, or when the model naturally reaches its configured output limit during generation.
+    """
+
+    def __init__(self, message: str, incomplete_message: Message):
+        """Initialize the exception with an error message and the incomplete message object.
+
+        Args:
+            message: The error message describing the token limit issue
+            incomplete_message: The valid Message object with incomplete content due to token limits
+        """
+        self.incomplete_message = incomplete_message
+        super().__init__(message)
+
+
+class ContextWindowOverflowException(Exception):
+    """Exception raised when the context window is exceeded.
+
+    This exception is raised when the input to a model exceeds the maximum context window size that the model can
+    handle. This typically occurs when the combined length of the conversation history, system prompt, and current
+    message is too large for the model to process.
+    """
+
+    pass
+
+
+class MCPClientInitializationError(Exception):
+    """Raised when the MCP server fails to initialize properly."""
+
+    pass
+
+
+class ModelThrottledException(Exception):
+    """Exception raised when the model is throttled.
+
+    This exception is raised when the model is throttled by the service. This typically occurs when the service is
+    throttling the requests from the client.
+    """
+
+    def __init__(self, message: str) -> None:
+        """Initialize exception.
+
+        Args:
+            message: The message from the service that describes the throttling.
+        """
+        self.message = message
+        super().__init__(message)
+
+    pass
+
+
+class SessionException(Exception):
+    """Exception raised when session operations fail."""
+
+    pass