selectools 0.2.0__py3-none-any.whl

toolcalling/providers/stubs.py

@@ -0,0 +1,245 @@
+"""
+Provider implementations for Anthropic, Gemini, and a local fallback.
+
+These adapters validate configuration and can be mocked or monkeypatched by
+callers. They surface clear errors when SDKs or API keys are missing.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Iterable, List
+
+from ..env import load_default_env
+from ..types import Message, Role
+from .base import Provider, ProviderError
+
+
+class AnthropicProvider(Provider):
+    """Anthropic Messages API adapter."""
+
+    name = "anthropic"
+    supports_streaming = True
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        default_model: str = "claude-3-5-sonnet-20240620",
+        base_url: str | None = None,
+    ):
+        load_default_env()
+        self.api_key = api_key or os.getenv("ANTHROPIC_API_KEY")
+        if not self.api_key:
+            raise ProviderError("ANTHROPIC_API_KEY is not set. Set it in env or pass api_key.")
+
+        try:
+            from anthropic import Anthropic
+        except ImportError as exc:  # noqa: BLE001
+            raise ProviderError("anthropic package not installed. Install with `pip install anthropic`.") from exc
+
+        self._client = Anthropic(api_key=self.api_key, base_url=base_url)
+        self.default_model = default_model
+
+    def complete(
+        self,
+        *,
+        model: str,
+        system_prompt: str,
+        messages: List[Message],
+        temperature: float = 0.0,
+        max_tokens: int = 1000,
+        timeout: float | None = None,
+    ) -> str:
+        payload = self._format_messages(messages)
+        request_args = {
+            "model": model or self.default_model,
+            "system": system_prompt,
+            "messages": payload,
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+        }
+        if timeout is not None:
+            request_args["timeout"] = timeout
+        try:
+            response = self._client.messages.create(**request_args)
+        except Exception as exc:  # noqa: BLE001
+            raise ProviderError(f"Anthropic completion failed: {exc}") from exc
+
+        text_chunks = [block.text for block in response.content if hasattr(block, "text")]
+        return "".join(text_chunks)
+
+    def stream(
+        self,
+        *,
+        model: str,
+        system_prompt: str,
+        messages: List[Message],
+        temperature: float = 0.0,
+        max_tokens: int = 1000,
+        timeout: float | None = None,
+    ) -> Iterable[str]:
+        payload = self._format_messages(messages)
+        request_args = {
+            "model": model or self.default_model,
+            "system": system_prompt,
+            "messages": payload,
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+            "stream": True,
+        }
+        if timeout is not None:
+            request_args["timeout"] = timeout
+        try:
+            stream = self._client.messages.create(**request_args)
+        except Exception as exc:  # noqa: BLE001
+            raise ProviderError(f"Anthropic streaming failed: {exc}") from exc
+
+        for event in stream:
+            if getattr(event, "type", None) == "content_block_delta":
+                delta = getattr(event, "delta", None)
+                text = getattr(delta, "text", None) if delta else None
+                if text:
+                    yield text
+
+    def _format_messages(self, messages: List[Message]):
+        formatted = []
+        for message in messages:
+            role = message.role.value
+            if role == Role.TOOL.value:
+                role = Role.ASSISTANT.value
+            formatted.append({"role": role, "content": [{"type": "text", "text": message.content}]})
+        return formatted
+
+
+class GeminiProvider(Provider):
+    """Google Gemini adapter using google-generativeai SDK."""
+
+    name = "gemini"
+    supports_streaming = True
+
+    def __init__(self, api_key: str | None = None, default_model: str = "gemini-1.5-flash"):
+        load_default_env()
+        self.api_key = api_key or os.getenv("GEMINI_API_KEY")
+        if not self.api_key:
+            raise ProviderError("GEMINI_API_KEY is not set. Set it in env or pass api_key.")
+
+        try:
+            import google.generativeai as genai
+        except ImportError as exc:  # noqa: BLE001
+            raise ProviderError(
+                "google-generativeai package not installed. Install with `pip install google-generativeai`."
+            ) from exc
+
+        genai.configure(api_key=self.api_key)
+        self._genai = genai
+        self.default_model = default_model
+
+    def complete(
+        self,
+        *,
+        model: str,
+        system_prompt: str,
+        messages: List[Message],
+        temperature: float = 0.0,
+        max_tokens: int = 1000,
+        timeout: float | None = None,
+    ) -> str:
+        model_obj = self._genai.GenerativeModel(model or self.default_model)
+        prompt_parts = self._build_prompt(system_prompt, messages)
+        request_options = {"timeout": timeout} if timeout is not None else None
+        try:
+            response = model_obj.generate_content(
+                prompt_parts,
+                temperature=temperature,
+                max_output_tokens=max_tokens,
+                request_options=request_options,
+            )
+        except Exception as exc:  # noqa: BLE001
+            raise ProviderError(f"Gemini completion failed: {exc}") from exc
+
+        return response.text or ""
+
+    def stream(
+        self,
+        *,
+        model: str,
+        system_prompt: str,
+        messages: List[Message],
+        temperature: float = 0.0,
+        max_tokens: int = 1000,
+        timeout: float | None = None,
+    ) -> Iterable[str]:
+        model_obj = self._genai.GenerativeModel(model or self.default_model)
+        prompt_parts = self._build_prompt(system_prompt, messages)
+        request_options = {"timeout": timeout} if timeout is not None else None
+        try:
+            stream = model_obj.generate_content(
+                prompt_parts,
+                temperature=temperature,
+                max_output_tokens=max_tokens,
+                request_options=request_options,
+                stream=True,
+            )
+        except Exception as exc:  # noqa: BLE001
+            raise ProviderError(f"Gemini streaming failed: {exc}") from exc
+
+        for chunk in stream:
+            if getattr(chunk, "text", None):
+                yield chunk.text
+
+    def _build_prompt(self, system_prompt: str, messages: List[Message]):
+        conversation = [system_prompt]
+        for message in messages:
+            prefix = message.role.value.capitalize()
+            conversation.append(f"{prefix}: {message.content}")
+        return "\n".join(conversation)
+
+
+class LocalProvider(Provider):
+    """
+    Local fallback provider.
+
+    This does not call a model. It echoes the latest user content and is useful
+    for offline/manual testing or as a safe default.
+    """
+
+    name = "local"
+    supports_streaming = True
+
+    def complete(
+        self,
+        *,
+        model: str,
+        system_prompt: str,
+        messages: List[Message],
+        temperature: float = 0.0,
+        max_tokens: int = 1000,
+        timeout: float | None = None,
+    ) -> str:
+        last_user = next((m for m in reversed(messages) if m.role == Role.USER), None)
+        user_text = last_user.content if last_user else ""
+        return f"[local provider: {model}] {user_text or 'No user message provided.'}"
+
+    def stream(
+        self,
+        *,
+        model: str,
+        system_prompt: str,
+        messages: List[Message],
+        temperature: float = 0.0,
+        max_tokens: int = 1000,
+        timeout: float | None = None,
+    ):
+        text = self.complete(
+            model=model,
+            system_prompt=system_prompt,
+            messages=messages,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            timeout=timeout,
+        )
+        for token in text.split():
+            yield token + " "
+
+
+__all__ = ["AnthropicProvider", "GeminiProvider", "LocalProvider"]

toolcalling/tools.py

@@ -0,0 +1,233 @@
+"""
+Tool metadata, schemas, and runtime validation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import inspect
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
+
+
+JsonSchema = Dict[str, Any]
+ParameterValue = Union[str, int, float, bool, dict, list]
+ParamMetadata = Dict[str, Any]
+
+
+def _python_type_to_json(param_type: type) -> str:
+    """Map a Python type to a JSON schema type string."""
+    type_map = {
+        str: "string",
+        int: "integer",
+        float: "number",
+        bool: "boolean",
+        list: "array",
+        dict: "object",
+    }
+    return type_map.get(param_type, "string")
+
+
+@dataclass
+class ToolParameter:
+    """Schema definition for a single tool parameter."""
+
+    name: str
+    param_type: type
+    description: str
+    required: bool = True
+    enum: Optional[List[str]] = None
+
+    def to_schema(self) -> JsonSchema:
+        """Return a JSON-schema compatible definition."""
+        schema: JsonSchema = {
+            "type": _python_type_to_json(self.param_type),
+            "description": self.description,
+        }
+        if self.enum:
+            schema["enum"] = self.enum
+        return schema
+
+
+class Tool:
+    """
+    Encapsulates a callable tool with validation and schema generation.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        parameters: List[ToolParameter],
+        function: Callable[..., str],
+        *,
+        injected_kwargs: Optional[Dict[str, Any]] = None,
+        config_injector: Optional[Callable[[], Dict[str, Any]]] = None,
+    ):
+        self.name = name
+        self.description = description
+        self.parameters = parameters
+        self.function = function
+        self.injected_kwargs = injected_kwargs or {}
+        self.config_injector = config_injector
+
+    def schema(self) -> JsonSchema:
+        """Return a JSON-schema style dict describing this tool."""
+        properties = {param.name: param.to_schema() for param in self.parameters}
+        required = [param.name for param in self.parameters if param.required]
+
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": {
+                "type": "object",
+                "properties": properties,
+                "required": required,
+            },
+        }
+
+    def _validate_single(self, param: ToolParameter, value: ParameterValue) -> Optional[str]:
+        """Validate a single parameter, returning an error message if invalid."""
+        if value is None:
+            return f"Parameter '{param.name}' is None"
+
+        if param.param_type is float:
+            if not isinstance(value, (float, int)):
+                return f"Parameter '{param.name}' must be a number"
+            return None
+
+        if not isinstance(value, param.param_type):
+            return f"Parameter '{param.name}' must be of type {param.param_type.__name__}, got {type(value).__name__}"
+        return None
+
+    def validate(self, params: Dict[str, ParameterValue]) -> Tuple[bool, Optional[str]]:
+        """
+        Validate a parameter dictionary against this tool's schema.
+
+        Returns (is_valid, error_message)
+        """
+        for param in self.parameters:
+            if param.required and param.name not in params:
+                return False, f"Missing required parameter: {param.name}"
+            if param.name not in params:
+                continue
+            error = self._validate_single(param, params[param.name])
+            if error:
+                return False, error
+        return True, None
+
+    def execute(self, params: Dict[str, ParameterValue]) -> str:
+        """Validate parameters then execute the underlying callable."""
+        is_valid, error = self.validate(params)
+        if not is_valid:
+            raise ValueError(f"Invalid parameters for tool '{self.name}': {error}")
+
+        call_args: Dict[str, Any] = dict(params)
+        call_args.update(self.injected_kwargs)
+        if self.config_injector:
+            call_args.update(self.config_injector() or {})
+
+        return self.function(**call_args)
+
+
+def _infer_parameters_from_callable(
+    func: Callable[..., Any],
+    param_metadata: Optional[Dict[str, ParamMetadata]] = None,
+) -> List[ToolParameter]:
+    """Create ToolParameter objects from a callable signature and annotations."""
+    param_metadata = param_metadata or {}
+    signature = inspect.signature(func)
+    parameters: List[ToolParameter] = []
+    for name, param in signature.parameters.items():
+        if name.startswith("_"):
+            continue
+        annotation = param.annotation if param.annotation is not inspect._empty else str
+        meta = param_metadata.get(name, {})
+        description = meta.get("description", "")
+        enum = meta.get("enum")
+        required = param.default is inspect._empty
+        parameters.append(
+            ToolParameter(
+                name=name,
+                param_type=annotation if isinstance(annotation, type) else str,
+                description=description or f"Parameter '{name}'",
+                required=required,
+                enum=enum,
+            )
+        )
+    return parameters
+
+
+def tool(
+    *,
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    param_metadata: Optional[Dict[str, ParamMetadata]] = None,
+    injected_kwargs: Optional[Dict[str, Any]] = None,
+    config_injector: Optional[Callable[[], Dict[str, Any]]] = None,
+):
+    """
+    Decorator to register a function as a Tool with schema inference.
+
+    Example:
+        @tool(name="search")
+        def search(query: str, count: int = 3) -> str:
+            ...
+    """
+
+    def wrapper(func: Callable[..., str]) -> Tool:
+        params = _infer_parameters_from_callable(func, param_metadata=param_metadata)
+        tool_obj = Tool(
+            name=name or func.__name__,
+            description=description or (func.__doc__ or "").strip() or f"Tool {func.__name__}",
+            parameters=params,
+            function=func,
+            injected_kwargs=injected_kwargs,
+            config_injector=config_injector,
+        )
+        return tool_obj
+
+    return wrapper
+
+
+class ToolRegistry:
+    """Simple registry for reusable tool instances."""
+
+    def __init__(self):
+        self._tools: Dict[str, Tool] = {}
+
+    def register(self, tool_obj: Tool) -> Tool:
+        self._tools[tool_obj.name] = tool_obj
+        return tool_obj
+
+    def tool(
+        self,
+        *,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        param_metadata: Optional[Dict[str, ParamMetadata]] = None,
+        injected_kwargs: Optional[Dict[str, Any]] = None,
+        config_injector: Optional[Callable[[], Dict[str, Any]]] = None,
+    ):
+        """Decorator variant that also registers the tool in this registry."""
+
+        def decorator(func: Callable[..., str]) -> Tool:
+            tool_obj = tool(
+                name=name,
+                description=description,
+                param_metadata=param_metadata,
+                injected_kwargs=injected_kwargs,
+                config_injector=config_injector,
+            )(func)
+            self.register(tool_obj)
+            return tool_obj
+
+        return decorator
+
+    def get(self, name: str) -> Optional[Tool]:
+        return self._tools.get(name)
+
+    def all(self) -> List[Tool]:
+        return list(self._tools.values())
+
+
+__all__ = ["Tool", "ToolParameter", "ToolRegistry", "tool"]

toolcalling/types.py

@@ -0,0 +1,76 @@
+"""
+Core message and role types for the tool-calling library.
+
+These primitives are provider-agnostic and are reused across adapters,
+the agent loop, and tests.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, Optional
+import base64
+
+
+class Role(str, Enum):
+    """Conversation role."""
+
+    USER = "user"
+    ASSISTANT = "assistant"
+    SYSTEM = "system"
+    TOOL = "tool"
+
+
+def _encode_image(image_path: str) -> str:
+    """Load and base64-encode an image from disk."""
+    path = Path(image_path).expanduser().resolve()
+    if not path.exists():
+        raise FileNotFoundError(f"Image file not found: {path}")
+
+    data = path.read_bytes()
+    return base64.b64encode(data).decode("utf-8")
+
+
+@dataclass
+class Message:
+    """
+    Conversation message with optional inline image payload and tool metadata.
+
+    The `image_base64` field is populated automatically when `image_path` is
+    provided so adapters can forward vision content to providers without
+    re-encoding.
+    """
+
+    role: Role
+    content: str
+    image_path: Optional[str] = None
+    tool_name: Optional[str] = None
+    tool_result: Optional[str] = None
+    image_base64: Optional[str] = field(init=False, default=None)
+
+    def __post_init__(self) -> None:
+        if self.image_path:
+            self.image_base64 = _encode_image(self.image_path)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return a plain-JSON-safe representation for logging or debugging."""
+        return {
+            "role": self.role.value,
+            "content": self.content,
+            "image_base64": self.image_base64,
+            "tool_name": self.tool_name,
+            "tool_result": self.tool_result,
+        }
+
+
+@dataclass
+class ToolCall:
+    """Structured representation of a parsed tool call."""
+
+    tool_name: str
+    parameters: Dict[str, Any]
+
+
+__all__ = ["Role", "Message", "ToolCall"]