agentpool 2.1.9__py3-none-any.whl

agentpool_config/builtin_tools.py

@@ -0,0 +1,265 @@
+"""Models for PydanticAI builtin tools configuration."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Annotated, Literal
+
+from pydantic import ConfigDict, Field
+from pydantic_ai import (
+    CodeExecutionTool,
+    ImageGenerationTool,
+    MCPServerTool,
+    MemoryTool,
+    WebFetchTool,
+    WebSearchTool,
+)
+from pydantic_ai.builtin_tools import WebSearchUserLocation  # noqa: TC002
+
+from agentpool_config.tools import BaseToolConfig
+
+
+if TYPE_CHECKING:
+    from pydantic_ai.builtin_tools import AbstractBuiltinTool
+
+
+class BaseBuiltinToolConfig(BaseToolConfig):
+    """Base configuration for PydanticAI builtin tools."""
+
+    def get_builtin_tool(self) -> AbstractBuiltinTool:
+        """Convert config to PydanticAI builtin tool instance."""
+        raise NotImplementedError
+
+
+class WebSearchToolConfig(BaseBuiltinToolConfig):
+    """Configuration for PydanticAI web search builtin tool."""
+
+    model_config = ConfigDict(title="Web Search Tool")
+
+    type: Literal["web_search"] = Field("web_search", init=False)
+    """Web search builtin tool."""
+
+    search_context_size: Literal["low", "medium", "high"] = Field(
+        default="medium",
+        examples=["low", "medium", "high"],
+        title="Search context size",
+    )
+    """The search context size parameter controls how much context is retrieved."""
+
+    user_location: WebSearchUserLocation | None = Field(default=None, title="User location")
+    """User location for localizing search results (city, country, region, timezone)."""
+
+    blocked_domains: list[str] | None = Field(
+        default=None,
+        examples=[["spam.com", "ads.example.com"], ["blocked.site"]],
+        title="Blocked domains",
+    )
+    """Domains that will never appear in results."""
+
+    allowed_domains: list[str] | None = Field(
+        default=None,
+        examples=[["wikipedia.org", "github.com"], ["trusted.site"]],
+        title="Allowed domains",
+    )
+    """Only these domains will be included in results."""
+
+    max_uses: int | None = Field(default=None, examples=[5, 10, 20], title="Maximum uses")
+    """Maximum number of times the tool can be used."""
+
+    def get_builtin_tool(self) -> WebSearchTool:
+        """Convert config to WebSearchTool instance."""
+        return WebSearchTool(
+            search_context_size=self.search_context_size,
+            user_location=self.user_location,
+            blocked_domains=self.blocked_domains,
+            allowed_domains=self.allowed_domains,
+            max_uses=self.max_uses,
+        )
+
+
+class CodeExecutionToolConfig(BaseBuiltinToolConfig):
+    """Configuration for PydanticAI code execution builtin tool."""
+
+    model_config = ConfigDict(title="Code Execution Tool")
+
+    type: Literal["code_execution"] = Field("code_execution", init=False)
+    """Code execution builtin tool."""
+
+    def get_builtin_tool(self) -> CodeExecutionTool:
+        """Convert config to CodeExecutionTool instance."""
+        return CodeExecutionTool()
+
+
+class WebFetchToolConfig(BaseBuiltinToolConfig):
+    """Configuration for PydanticAI URL context builtin tool."""
+
+    model_config = ConfigDict(title="Url Context Tool")
+
+    type: Literal["web_fetch"] = Field("web_fetch", init=False)
+    """URL context builtin tool."""
+
+    def get_builtin_tool(self) -> WebFetchTool:
+        """Convert config to WebFetchTool instance."""
+        return WebFetchTool()
+
+
+class ImageGenerationToolConfig(BaseBuiltinToolConfig):
+    """Configuration for PydanticAI image generation builtin tool."""
+
+    model_config = ConfigDict(title="Image Generation Tool")
+
+    type: Literal["image_generation"] = Field("image_generation", init=False)
+    """Image generation builtin tool."""
+
+    background: Literal["transparent", "opaque", "auto"] = Field(
+        default="auto",
+        examples=["transparent", "opaque", "auto"],
+        title="Background type",
+    )
+    """Background type for the generated image."""
+
+    input_fidelity: Literal["high", "low"] | None = Field(
+        default=None,
+        examples=["high", "low"],
+        title="Input fidelity",
+    )
+    """Control how much effort the model will exert to match input image features."""
+
+    moderation: Literal["auto", "low"] = Field(
+        default="auto",
+        examples=["auto", "low"],
+        title="Moderation level",
+    )
+    """Moderation level for the generated image."""
+
+    output_compression: int = Field(
+        default=100,
+        ge=0,
+        le=100,
+        examples=[80, 90, 100],
+        title="Output compression",
+    )
+    """Compression level for the output image."""
+
+    output_format: Literal["png", "webp", "jpeg"] | None = Field(
+        default=None,
+        examples=["png", "webp", "jpeg"],
+        title="Output format",
+    )
+    """The output format of the generated image."""
+
+    partial_images: int = Field(
+        default=0,
+        ge=0,
+        examples=[0, 2, 4],
+        title="Partial images count",
+    )
+    """Number of partial images to generate in streaming mode."""
+
+    quality: Literal["low", "medium", "high", "auto"] = Field(
+        default="auto",
+        examples=["low", "medium", "high", "auto"],
+        title="Image quality",
+    )
+    """The quality of the generated image."""
+
+    size: Literal["1024x1024", "1024x1536", "1536x1024", "auto"] = Field(
+        default="auto",
+        examples=["1024x1024", "1024x1536", "1536x1024", "auto"],
+        title="Image size",
+    )
+    """The size of the generated image."""
+
+    def get_builtin_tool(self) -> ImageGenerationTool:
+        """Convert config to ImageGenerationTool instance."""
+        return ImageGenerationTool(
+            background=self.background,
+            input_fidelity=self.input_fidelity,
+            moderation=self.moderation,
+            output_compression=self.output_compression,
+            output_format=self.output_format,
+            partial_images=self.partial_images,
+            quality=self.quality,
+            size=self.size,
+        )
+
+
+class MemoryToolConfig(BaseBuiltinToolConfig):
+    """Configuration for PydanticAI memory builtin tool."""
+
+    model_config = ConfigDict(title="Memory Tool")
+
+    type: Literal["memory"] = Field("memory", init=False)
+    """Memory builtin tool."""
+
+    def get_builtin_tool(self) -> MemoryTool:
+        """Convert config to MemoryTool instance."""
+        return MemoryTool()
+
+
+class MCPServerToolConfig(BaseBuiltinToolConfig):
+    """Configuration for PydanticAI MCP server builtin tool."""
+
+    model_config = ConfigDict(title="MCP Server Tool")
+
+    type: Literal["mcp_server"] = Field("mcp_server", init=False)
+    """MCP server builtin tool."""
+
+    server_id: str = Field(
+        alias="id",
+        examples=["my_mcp_server", "code_tools", "web_api"],
+        title="Server ID",
+    )
+    """A unique identifier for the MCP server."""
+
+    url: str = Field(
+        examples=["https://api.example.com/mcp", "http://localhost:8080"],
+        title="Server URL",
+    )
+    """The URL of the MCP server to use."""
+
+    authorization_token: str | None = Field(
+        default=None,
+        examples=["Bearer token123", "api_key_abc"],
+        title="Authorization token",
+    )
+    """Authorization header to use when making requests to the MCP server."""
+
+    description: str | None = Field(
+        default=None,
+        examples=["External API tools", "Code execution server"],
+        title="Server description",
+    )
+    """A description of the MCP server."""
+
+    allowed_tools: list[str] | None = Field(
+        default=None,
+        examples=[["search", "fetch"], ["execute", "compile"]],
+        title="Allowed tools",
+    )
+    """A list of tools that the MCP server can use."""
+
+    headers: dict[str, str] | None = Field(default=None, title="HTTP headers")
+    """Optional HTTP headers to send to the MCP server."""
+
+    def get_builtin_tool(self) -> MCPServerTool:
+        """Convert config to MCPServerTool instance."""
+        return MCPServerTool(
+            id=self.server_id,
+            url=self.url,
+            authorization_token=self.authorization_token,
+            description=self.description,
+            allowed_tools=self.allowed_tools,
+            headers=self.headers,
+        )
+
+
+# Union type for builtin tool configs
+BuiltinToolConfig = Annotated[
+    WebSearchToolConfig
+    | CodeExecutionToolConfig
+    | WebFetchToolConfig
+    | ImageGenerationToolConfig
+    | MemoryToolConfig
+    | MCPServerToolConfig,
+    Field(discriminator="type"),
+]

agentpool_config/commands.py

@@ -0,0 +1,237 @@
+"""Command configuration for prompt shortcuts."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+import inspect
+from pathlib import Path
+import re
+from typing import Annotated, Any, Literal
+
+from pydantic import ConfigDict, Field, ImportString
+from schemez import Schema
+
+
+class BaseCommandConfig(Schema):
+    """Base configuration for commands."""
+
+    model_config = ConfigDict(json_schema_extra={"title": "Base Command"})
+
+    type: str = Field(title="Command type")
+    """Type discriminator for command configurations."""
+
+    name: str | None = Field(
+        default=None,
+        examples=["summarize", "code_review", "translate"],
+        title="Command name",
+    )
+    """Command name (optional, can be inferred from key)."""
+
+    description: str | None = Field(
+        default=None,
+        examples=["Summarize the given text", "Review code for issues"],
+        title="Command description",
+    )
+    """Optional description of what this command does."""
+
+    def get_callable(self) -> Callable[..., str]:
+        """Generate a callable function from the command configuration.
+
+        Returns:
+            A function with proper signature that can be introspected by libraries
+            like slashed that examine Python callables.
+        """
+        raise NotImplementedError
+
+
+class StaticCommandConfig(BaseCommandConfig):
+    """Static command with inline content."""
+
+    model_config = ConfigDict(json_schema_extra={"title": "Static Command"})
+
+    type: Literal["static"] = Field("static", init=False)
+    """Static command configuration."""
+
+    content: str = Field(
+        examples=[
+            "Summarize this text: {text}",
+            "Translate {text} to {language}",
+            "Review this code: {code}",
+        ],
+        title="Template content",
+    )
+    """The prompt template content. Supports ${env.VAR} substitution."""
+
+    def get_callable(self) -> Callable[..., str]:
+        """Generate a callable function from the static command content.
+
+        Parses {param} placeholders in content to create function parameters.
+
+        Returns:
+            A function with signature matching the template parameters
+        """
+        # Extract parameter names from {param} placeholders
+        param_names = list(set(re.findall(r"\{(\w+)\}", self.content)))
+        param_names.sort()  # Consistent ordering
+
+        # Create function that does template substitution
+        def command_func(*args: Any, **kwargs: Any) -> str:
+            """Generated command function."""
+            # Build substitution dict from args and kwargs
+            substitutions = {}
+            for i, name in enumerate(param_names):
+                if i < len(args):
+                    substitutions[name] = args[i]
+                elif name in kwargs:
+                    substitutions[name] = kwargs[name]
+                else:
+                    substitutions[name] = ""  # Default empty string
+
+            # Substitute into template
+            return self.content.format(**substitutions)
+
+        # Create proper signature
+        parameters = [
+            inspect.Parameter(
+                name, inspect.Parameter.POSITIONAL_OR_KEYWORD, annotation=str, default=""
+            )
+            for name in param_names
+        ]
+        signature = inspect.Signature(parameters, return_annotation=str)
+        # Set function metadata
+        command_func.__name__ = self.name or "unnamed_command"
+        command_func.__doc__ = self.description or self.content
+        command_func.__signature__ = signature  # type: ignore
+
+        return command_func
+
+
+class CallableCommandConfig(BaseCommandConfig):
+    """Callable command that references a Python function."""
+
+    model_config = ConfigDict(json_schema_extra={"title": "Callable Command"})
+
+    type: Literal["callable"] = Field("callable", init=False)
+    """Callable command configuration."""
+
+    function: ImportString[Callable[..., Any]] = Field(
+        examples=[
+            "mymodule.commands.summarize",
+            "utils.prompts:code_review",
+            "external.tools:translate_text",
+        ],
+        title="Function import path",
+    )
+    """Python function import path (e.g., 'my.package.module.function_name')."""
+
+    def get_callable(self) -> Callable[..., str]:
+        """Return the imported function directly.
+
+        Returns:
+            The imported Python function
+
+        Raises:
+            ImportError: If the function cannot be imported
+            TypeError: If the imported object is not callable
+        """
+        func = self.function
+        if not callable(func):
+            msg = f"Imported object {self.function} is not callable"
+            raise TypeError(msg)
+
+        # Set name if provided and function has __name__
+        if self.name and hasattr(func, "__name__"):
+            func.__name__ = self.name  # ty: ignore
+
+        # Set description as docstring if provided
+        if self.description and not func.__doc__:
+            func.__doc__ = self.description
+        elif self.description:
+            # Prepend description to existing docstring
+            existing_doc = func.__doc__ or ""
+            func.__doc__ = f"{self.description}\n\n{existing_doc}".strip()
+
+        return func
+
+
+class FileCommandConfig(BaseCommandConfig):
+    """File-based command that loads content from external file."""
+
+    model_config = ConfigDict(json_schema_extra={"title": "File-based Command"})
+
+    type: Literal["file"] = Field("file", init=False)
+    """File-based command configuration."""
+
+    path: str = Field(
+        examples=[
+            "prompts/summarize.txt",
+            "/templates/code_review.j2",
+            "commands/translate.md",
+        ],
+        title="Template file path",
+    )
+    """Path to file containing the prompt template."""
+
+    encoding: str = Field(
+        default="utf-8",
+        examples=["utf-8", "ascii", "latin1"],
+        title="File encoding",
+    )
+    """File encoding to use when reading the file."""
+
+    def get_callable(self) -> Callable[..., str]:
+        """Generate a callable function from the file-based command.
+
+        Loads content from file and creates function with parameters
+        based on {param} placeholders in the file content.
+
+        Returns:
+            A function with signature matching the template parameters
+
+        Raises:
+            FileNotFoundError: If the specified file doesn't exist
+            UnicodeDecodeError: If file cannot be decoded with specified encoding
+        """
+        file_path = Path(self.path)
+        content = file_path.read_text(encoding=self.encoding)
+        # Extract parameter names from {param} placeholders
+        param_names = list(set(re.findall(r"\{(\w+)\}", content)))
+        param_names.sort()  # Consistent ordering
+
+        # Create function that does template substitution
+        def command_func(*args: Any, **kwargs: Any) -> str:
+            """Generated command function from file."""
+            # Build substitution dict from args and kwargs
+            substitutions = {}
+            for i, name in enumerate(param_names):
+                if i < len(args):
+                    substitutions[name] = args[i]
+                elif name in kwargs:
+                    substitutions[name] = kwargs[name]
+                else:
+                    substitutions[name] = ""  # Default empty string
+
+            # Substitute into template
+            return content.format(**substitutions)
+
+        # Create proper signature
+        parameters = [
+            inspect.Parameter(
+                name, inspect.Parameter.POSITIONAL_OR_KEYWORD, annotation=str, default=""
+            )
+            for name in param_names
+        ]
+        signature = inspect.Signature(parameters, return_annotation=str)
+
+        # Set function metadata
+        command_func.__name__ = self.name or "unnamed_command"
+        command_func.__doc__ = self.description or f"Command from {self.path}"
+        command_func.__signature__ = signature  # type: ignore
+
+        return command_func
+
+
+CommandConfig = Annotated[
+    StaticCommandConfig | FileCommandConfig | CallableCommandConfig,
+    Field(discriminator="type"),
+]