agent-handler-sdk 0.1.8__tar.gz

agent_handler_sdk-0.1.8/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: agent-handler-sdk
+Version: 0.1.8
+Summary: Agent Handler SDK for defining and invoking LLM tools
+Author: David Dalmaso
+Author-email: david.dalmaso@merge.dev
+Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: jsonschema (>=4.0,<5.0)
+Requires-Dist: pydantic (>=2.0,<3.0)

agent_handler_sdk-0.1.8/agent_handler_sdk/__init__.py

@@ -0,0 +1,3 @@
+# agent_handler_sdk package root
+
+__version__ = "0.1.8"

agent_handler_sdk-0.1.8/agent_handler_sdk/auth.py

@@ -0,0 +1,24 @@
+# agent_handler_sdk/auth.py
+
+from typing import Optional
+
+
+class AuthContext:
+    """
+    Auth context for tool execution that provides secure access to secrets.
+
+    This class provides an isolated container for secrets during tool execution.
+    Each tool execution should receive its own instance.
+    """
+
+    def __init__(self, secrets: Optional[dict[str, str]] = None, oauth2_token: Optional[str] = None):
+        self._secrets = secrets or {}
+        self._oauth2_token = oauth2_token
+
+    def get(self, key: str, default: Optional[str] = None) -> Optional[str]:
+        """Get a secret value by key"""
+        return self._secrets.get(key, default)
+
+    def get_oauth2_token(self) -> Optional[str]:
+        """Get the OAuth token from the secrets"""
+        return self._oauth2_token

agent_handler_sdk-0.1.8/agent_handler_sdk/cli.py

@@ -0,0 +1,81 @@
+import sys
+from pathlib import Path
+from typing import Any
+import importlib.resources as pkg_resources
+from agent_handler_sdk import __version__ as sdk_version
+
+# Use str() to convert Traversable to string path
+TEMPLATE_DIR = Path(str(pkg_resources.files("agent_handler_sdk"))) / "templates" / "connector"
+
+
+def get_sdk_version() -> str:
+    return sdk_version
+
+
+def render_template(filename: str, **context: Any) -> str:
+    """
+    Load a template file from the SDK's templates/connector directory
+    and format it with the given context.
+    """
+    template_path = TEMPLATE_DIR.joinpath(filename)
+    text = template_path.read_text()
+    return text.format(**context)
+
+
+def scaffold_connector() -> int:
+    """
+    Usage: ahs-scaffold <slug> [--target-dir <dir>]
+
+    Creates:
+      <target-dir>/connectors/<slug>/
+        pyproject.toml
+        metadata.yaml
+        <slug>_connector/
+          __init__.py
+          tools/
+        evals/
+        tests/
+          test_handlers.py
+    """
+    args = sys.argv[1:]
+    if not args:
+        print(scaffold_connector.__doc__)
+        sys.exit(1)
+
+    slug = args[0]
+    # Generate human-readable name by replacing hyphens with spaces and capitalizing words
+    human_readable_name = " ".join(word.capitalize() for word in slug.replace("-", " ").split())
+    target = Path(".")
+    if "--target-dir" in args:
+        idx = args.index("--target-dir")
+        target = Path(args[idx + 1])
+
+    version = get_sdk_version()
+
+    base = target / "connectors" / slug
+    pkg_dir = base / f"{slug}_connector"
+    tools_dir = pkg_dir / "tools"
+    tests_dir = base / "tests"
+    evals_dir = base / "evals"
+
+    # Create directories
+    for d in (base, pkg_dir, tools_dir, tests_dir, evals_dir):
+        d.mkdir(parents=True, exist_ok=True)
+
+    # Map template → output path
+    files_to_render = {
+        "pyproject.toml.tpl": base / "pyproject.toml",
+        "metadata.yaml.tpl": base / "metadata.yaml",
+        "init.py.tpl": pkg_dir / "__init__.py",
+        "test_handlers.py.tpl": tests_dir / "test_handlers.py",
+        "evals.json.tpl": evals_dir / "evals.json",
+        "README.md.tpl": base / "README.md",
+    }
+
+    # Render each template with both name & version
+    for tpl_name, out_path in files_to_render.items():
+        content = render_template(tpl_name, name=slug, version=version, human_readable_name=human_readable_name)
+        out_path.write_text(content, encoding="utf-8")
+
+    print(f"Scaffolded connector '{slug}' (SDK v{version}) at {base}")
+    return 0

agent_handler_sdk-0.1.8/agent_handler_sdk/connector.py

@@ -0,0 +1,106 @@
+from typing import List, Optional, Set, Dict, Any, Union, Awaitable, Callable
+from .registry import ConnectorRegistry
+
+
+class Connector:
+    def __init__(
+        self,
+        namespace: str,
+        include_tools: Optional[List[str]] = None,
+        include_tags: Optional[List[str]] = None,
+    ):
+        """
+        namespace: unique prefix (e.g. "jira").
+        include_tools: explicit list of fully-qualified tool names.
+        include_tags: whitelist of tags to filter tools by.
+        """
+        self.namespace = namespace
+        self.include_tools = set(include_tools) if include_tools else None
+        self.include_tags = set(include_tags) if include_tags else None
+
+    def tool(
+        self,
+        name: Optional[str] = None,
+        desc: str = "",
+        tags: Optional[List[str]] = None,
+        read_only: Optional[bool] = None,
+        destructive: Optional[bool] = None,
+        idempotent: Optional[bool] = None,
+        open_world: Optional[bool] = None,
+    ) -> Callable[[Callable], Callable]:
+        # Wraps agent_handler_sdk.tool to inject qualified name & tags
+        from .tool import tool as _tool
+
+        def decorator(fn: Callable) -> Callable:
+            qualified = f"{self.namespace}__{name or fn.__name__}"
+            return _tool(
+                name=qualified,
+                desc=desc,
+                tags=tags,
+                read_only=read_only,
+                destructive=destructive,
+                idempotent=idempotent,
+                open_world=open_world,
+            )(fn)
+
+        return decorator
+
+    def list_tools(self) -> List[Dict]:
+        # Get all specs that match the namespace
+        namespace_prefix = f"{self.namespace}__"
+        specs = [t for t in ConnectorRegistry.list_tools() if t["name"].startswith(namespace_prefix)]
+
+        # Filter by explicit tool names if specified
+        if self.include_tools is not None:
+            specs = [t for t in specs if t["name"] in self.include_tools]
+
+        # Filter by tags if specified
+        if self.include_tags is not None:
+            # Get the tool specs from the registry to access tags
+            tool_specs = {
+                t.name: t for t in ConnectorRegistry._tools.values() if t.name in [spec["name"] for spec in specs]
+            }
+
+            # Filter specs based on tags
+            specs = [spec for spec in specs if any(tag in self.include_tags for tag in tool_specs[spec["name"]].tags)]
+
+        return specs
+
+    def get_tool(self, name: str) -> Dict:
+        return ConnectorRegistry.get_tool(name)
+
+    def call_tool(self, tool_name: str, params: dict) -> Any:
+        """
+        Validate and invoke a registered tool by name.
+
+        For synchronous tools, returns the result directly.
+        For async tools, this will run the event loop and return the awaited result.
+
+        Args:
+            tool_name: The name of the tool to invoke
+            params: Dictionary of parameters to pass to the tool
+
+        Returns:
+            The result of the tool invocation
+        """
+        from .invocation import invoke as _invoke
+
+        return _invoke(tool_name, params, connector=self)
+
+    async def call_tool_async(self, tool_name: str, params: dict) -> Any:
+        """
+        Validate and invoke a registered tool by name asynchronously.
+
+        For synchronous tools, this will run them in a thread pool.
+        For async tools, this will await the coroutine directly.
+
+        Args:
+            tool_name: The name of the tool to invoke
+            params: Dictionary of parameters to pass to the tool
+
+        Returns:
+            The result of the tool invocation
+        """
+        from .invocation import invoke_async as _invoke_async
+
+        return await _invoke_async(tool_name, params, connector=self)

agent_handler_sdk-0.1.8/agent_handler_sdk/eval_types.py

@@ -0,0 +1,113 @@
+from typing import List, Dict, Any, Optional, Literal, Union
+from pydantic import BaseModel, Extra
+from datetime import datetime
+
+
+class JsonSchema(BaseModel):
+    type: Optional[str] = None
+    properties: Optional[Dict[str, "JsonSchema"]] = None
+    items: Optional[Union["JsonSchema", List["JsonSchema"]]] = None
+    required: Optional[List[str]] = None
+    enum: Optional[List[Any]] = None
+    description: Optional[str] = None
+    additional_properties: Optional[Union[bool, "JsonSchema"]] = None
+    model: Optional[str] = None
+
+    class Config:
+        arbitrary_types_allowed = True
+        extra = "allow"
+
+
+JsonSchema.model_rebuild()
+
+
+class DataSourceConfig(BaseModel):
+    input_schema: JsonSchema
+
+
+class MessageContent(BaseModel):
+    type: str
+    text: str
+
+
+class MessageInput(BaseModel):
+    type: str
+    role: str
+    content: MessageContent
+
+
+class BaseEvaluator(BaseModel):
+    name: str
+    id: str
+    type: str  # Discriminator for future extension
+
+
+class ReferenceToolCallsMatchEvaluator(BaseEvaluator):
+    type: Literal["reference_tool_calls_match"]
+    enforce_ordering: bool
+    fail_on_args_mismatch: bool
+
+
+class LabelModelEvaluator(BaseEvaluator):
+    type: Literal["label_model"]
+    passing_labels: Optional[List[str]]
+    labels: Optional[List[str]]
+    model: Optional[str]
+    input: List[MessageInput]
+
+
+Evaluator = Union[ReferenceToolCallsMatchEvaluator, LabelModelEvaluator, BaseEvaluator]
+
+
+class EvalMetadata(BaseModel):
+    description: Optional[str]
+
+
+class EvalItemInput(BaseModel, extra=Extra.allow):
+    input: str
+
+
+class EvalItem(BaseModel, extra=Extra.allow):
+    """
+    Schema for individual eval items.
+    Supports both runtime evaluation (with id and tool_calls) and connector eval files (flexible input).
+    """
+
+    input: Union[str, EvalItemInput]  # Can be either a string or EvalItemInput object
+    id: Optional[str] = None  # Optional for connector eval files
+
+
+class ConnectorEvalBundle(BaseModel):
+    """
+    Schema for eval bundles stored in connector /evals/ folders.
+    This matches the JSON structure that contains config, items, and prompts together.
+    """
+
+    data_source_config: DataSourceConfig
+    items: List[EvalItem]
+    prompts: List[MessageInput]
+    name: str
+    metadata: Optional[EvalMetadata] = None
+
+    def to_eval_config(self) -> "EvalConfig":
+        """
+        Convert this bundle to an EvalConfig for use with the eval runner.
+        Note: This creates a minimal EvalConfig without testing_evaluators.
+        """
+        return EvalConfig(
+            id=None,
+            created_at=None,
+            updated_at=None,
+            data_source_config=self.data_source_config,
+            testing_evaluators=[],  # Empty list since connector evals don't define evaluators
+            metadata=self.metadata,
+        )
+
+
+class EvalConfig(BaseModel):
+    id: Optional[str]
+    created_at: Optional[datetime]
+    updated_at: Optional[datetime]
+    data_source_config: DataSourceConfig
+    testing_evaluators: Optional[List[Evaluator]] = []
+    metadata: Optional[EvalMetadata]

agent_handler_sdk-0.1.8/agent_handler_sdk/exceptions.py

@@ -0,0 +1,4 @@
+class ToolError(Exception):
+    """Generic error raised by tool invocation failures."""
+
+    pass

agent_handler_sdk-0.1.8/agent_handler_sdk/invocation.py

@@ -0,0 +1,55 @@
+from typing import Any, Optional, Union, Awaitable
+import asyncio
+import jsonschema
+from .registry import ConnectorRegistry
+from .connector import Connector
+from .registry import ToolSpec
+
+
+def invoke(tool_name: str, params: dict, connector: Optional[Connector] = None) -> Any:
+    """
+    Validate and invoke a registered tool by name.
+    If a Connector is provided, enforce whitelist based on that instance.
+
+    For synchronous tools, returns the result directly.
+    For async tools, this will run the event loop and return the awaited result.
+    """
+    spec = _get_validated_tool_spec(tool_name, params, connector)
+
+    if spec.is_async:
+        # For async functions, run the event loop
+        return asyncio.run(spec.fn(**params))
+    else:
+        # For sync functions, call directly
+        return spec.fn(**params)
+
+
+async def invoke_async(tool_name: str, params: dict, connector: Optional[Connector] = None) -> Any:
+    """
+    Validate and invoke a registered tool by name asynchronously.
+    If a Connector is provided, enforce whitelist based on that instance.
+
+    For synchronous tools, this will run them in a thread pool.
+    For async tools, this will await the coroutine directly.
+    """
+    spec = _get_validated_tool_spec(tool_name, params, connector)
+
+    if spec.is_async:
+        # For async functions, await directly
+        return await spec.fn(**params)
+    else:
+        # For sync functions, run in a thread pool
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, lambda: spec.fn(**params))
+
+
+def _get_validated_tool_spec(tool_name: str, params: dict, connector: Optional[Connector] = None) -> ToolSpec:
+    """Helper function to get and validate a tool spec."""
+    if connector:
+        allowed = {t["name"] for t in connector.list_tools()}
+        if tool_name not in allowed:
+            raise PermissionError(f"{tool_name!r} not allowed in this context")
+
+    spec = ConnectorRegistry.get_tool_spec(tool_name)
+    jsonschema.validate(params, spec.param_schema)
+    return spec

agent_handler_sdk-0.1.8/agent_handler_sdk/registry.py

@@ -0,0 +1,89 @@
+from typing import Any, Dict, Callable, List, Optional, Tuple
+import inspect
+
+# Mapping from ToolSpec field name to MCP hint name
+TOOL_ANNOTATION_FIELDS: List[Tuple[str, str]] = [
+    ("read_only", "readOnlyHint"),
+    ("destructive", "destructiveHint"),
+    ("idempotent", "idempotentHint"),
+    ("open_world", "openWorldHint"),
+]
+
+
+class ToolSpec:
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        fn: Callable,
+        param_schema: Dict[str, Any],
+        tags: List[str],
+        read_only: Optional[bool] = None,
+        destructive: Optional[bool] = None,
+        idempotent: Optional[bool] = None,
+        open_world: Optional[bool] = None,
+    ):
+        self.name = name
+        self.description = description
+        self.fn = fn
+        self.param_schema = param_schema
+        self.tags = tags
+        self.is_async = inspect.iscoroutinefunction(fn)
+        self.read_only = read_only
+        self.destructive = destructive
+        self.idempotent = idempotent
+        self.open_world = open_world
+
+
+class ConnectorRegistry:
+    _tools: Dict[str, ToolSpec] = {}
+
+    @classmethod
+    def register_tool(
+        cls,
+        name: str,
+        description: str,
+        fn: Callable,
+        param_schema: Dict[str, Any],
+        tags: List[str],
+        read_only: Optional[bool] = None,
+        destructive: Optional[bool] = None,
+        idempotent: Optional[bool] = None,
+        open_world: Optional[bool] = None,
+    ) -> None:
+        cls._tools[name] = ToolSpec(
+            name, description, fn, param_schema, tags, read_only, destructive, idempotent, open_world
+        )
+
+    @classmethod
+    def _format_tool_spec(cls, spec: ToolSpec) -> Dict[str, Any]:
+        result: Dict[str, Any] = {
+            "name": spec.name,
+            "description": spec.description,
+            "input_schema": spec.param_schema,
+        }
+        # Add annotations if any are set
+        annotations: Dict[str, bool] = {}
+        for field_name, hint_name in TOOL_ANNOTATION_FIELDS:
+            value = getattr(spec, field_name, None)
+            if value is not None:
+                annotations[hint_name] = value
+        if annotations:
+            result["annotations"] = annotations
+        return result
+
+    @classmethod
+    def list_tools(cls) -> List[Dict[str, Any]]:
+        return [cls._format_tool_spec(t) for t in cls._tools.values()]
+
+    @classmethod
+    def get_tool(cls, name: str) -> Dict[str, Any]:
+        if name not in cls._tools:
+            raise ValueError(f"Tool {name!r} not found in registry")
+        return cls._format_tool_spec(cls._tools[name])
+
+    @classmethod
+    def get_tool_spec(cls, name: str) -> ToolSpec:
+        if name not in cls._tools:
+            raise ValueError(f"Tool {name!r} not found in registry")
+        return cls._tools[name]

agent_handler_sdk-0.1.8/agent_handler_sdk/templates/connector/README.md.tpl

@@ -0,0 +1,34 @@
+# {name} Connector
+
+Basic **{name}** connector for Agent Handler (SDK v{version}).
+
+## Overview
+
+This repository provides the `{name}` connector, exposing a set of tools under the **`{name}`** namespace that can be called by your LLM via the Agent Handler SDK.
+
+## Prerequisites
+
+Install **Poetry**:
+
+```bash
+# Install Poetry
+pip install poetry
+```
+
+## Installing
+
+Install the Agent Handler SDK and this connector:
+
+```bash
+# From your connector’s root (where pyproject.toml lives)
+poetry install
+```
+
+## Testing
+
+Run the unit tests for this connector:
+
+```bash
+# From your connector’s root (where pyproject.toml lives)
+poetry run pytest
+```

agent_handler_sdk-0.1.8/agent_handler_sdk/templates/connector/evals.json.tpl

@@ -0,0 +1,55 @@
+[
+    {
+      "data_source_config": {
+        "input_schema": {
+          "type": "object",
+          "properties": {
+            "input": { "type": "string" },
+            "reference_value": { "type": "string" },
+            "reference_tools": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "name": { "type": "string" },
+                  "args": { "type": "object" }
+                },
+                "required": ["name"]
+              }
+            }
+          },
+          "required": ["input"]
+        }
+      },
+      "items": [
+        {
+          "input": "Tell me about George Washington",
+          "reference_value": null,
+          "reference_tools": [
+            {
+              "name": "wikipedia__search",
+              "args": {
+                "query": "George Washington"
+              }
+            }
+          ]
+        },
+        {
+          "input": "Where does London's name come from? Don't use any tools to solve this.",
+          "reference_value": "London's name is believed to originate from the Latin word \"Londinium,\" which was the name used during the Roman period when the city was established as a settlement. The exact origin of \"Londinium\" is uncertain, but it may derive from a pre-Roman or Celtic word. Over time, the name evolved through various forms, such as \"Londinium\" in Latin and \"Lunden\" in Old English, eventually becoming \"London\" as we know it today.",
+          "reference_tools": []
+          ]
+        }
+      ],
+      "prompts": [
+        {
+          "type": "text",
+          "role": "user",
+          "content": {
+            "type": "text",
+            "text": "{{input.input}}"
+          }
+        }
+      ]
+    }
+]

agent_handler_sdk-0.1.8/agent_handler_sdk/templates/connector/init.py.tpl

@@ -0,0 +1,12 @@
+import pkgutil
+import importlib
+from agent_handler_sdk.connector import Connector
+
+# single Connector instance for this package
+{name} = Connector(namespace="{name}")
+
+# auto-import all modules in tools/
+package = __name__ + ".tools"
+path = f"{{__path__[0]}}/tools"
+for _, m, _ in pkgutil.iter_modules([path]):
+    importlib.import_module(f"{{package}}.{{m}}")

agent_handler_sdk-0.1.8/agent_handler_sdk/templates/connector/metadata.yaml.tpl

@@ -0,0 +1,3 @@
+name: {human_readable_name}
+description: Basic {human_readable_name} connector for Agent Handler
+logo_url: https://images.g2crowd.com/uploads/product/image/large_detail/large_detail_aad4de182d7a6a195c9a7a11a375e75c/merge.png

agent_handler_sdk-0.1.8/agent_handler_sdk/templates/connector/pyproject.toml.tpl

@@ -0,0 +1,29 @@
+[tool.poetry]
+name = "{name}-connector"
+version = "0.1.0"
+description = "Basic {name} connector for Agent Handler"
+readme = "README.md"
+authors = ["Your Name <you@example.com>"]
+
+[tool.poetry.dependencies]
+python = ">=3.10"
+agent-handler-sdk = "^{version}"
+
+[tool.poetry.dev-dependencies]
+pytest = "^8.3.0"
+pytest-cov = "^4.0.0"
+pytest-asyncio = "^0.24.0"
+pytest-mock = "^3.11.1"
+mypy = "^1.5.1"
+pre-commit = "^3.4.0"
+tox = "^4.11.1"
+ruff = "^0.7.4"
+
+[build-system]
+requires = ["poetry-core>=1.0.0,<2.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.mypy]
+files = ["{name}_connector/**/*.py"]
+python_version = "3.10"
+disallow_untyped_defs = true

agent_handler_sdk-0.1.8/agent_handler_sdk/templates/connector/test_handlers.py.tpl

@@ -0,0 +1,19 @@
+import pytest
+from {name}_connector import {name}
+from agent_handler_sdk.invocation import invoke
+
+@pytest.mark.parametrize("tool_name,params,expected", [
+    ("{name}__example", {{}}, {{"status": "ok"}}),
+])
+def test_{name}_operations(tool_name, params, expected):
+    # Directly invoke tools using the SDK
+    result = invoke(tool_name, params, connector={name})
+    assert result == expected
+
+@pytest.mark.parametrize("tool_name,params,expected", [
+    ("{name}__example", {{}}, {{"status": "ok"}}),
+])
+def test_{name}_operations_with_connector(tool_name, params, expected):
+    # Invoke tools using the Connector
+    result = {name}.call_tool(tool_name, params)
+    assert result == expected

agent_handler_sdk-0.1.8/agent_handler_sdk/tool.py

@@ -0,0 +1,141 @@
+import inspect
+from typing import (
+    Callable,
+    Optional,
+    List,
+    Any,
+    Dict,
+    get_type_hints,
+    get_origin,
+    get_args,
+    TypeVar,
+    cast,
+)
+from pydantic import BaseModel, create_model
+from .registry import ConnectorRegistry
+from .utils import convert_type_hint_to_json_schema
+
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def tool(
+    name: Optional[str] = None,
+    desc: str = "",
+    tags: Optional[List[str]] = None,
+    read_only: Optional[bool] = None,
+    destructive: Optional[bool] = None,
+    idempotent: Optional[bool] = None,
+    open_world: Optional[bool] = None,
+) -> Callable[[F], F]:
+    """
+    Decorator to register a function as a tool.
+
+    Args:
+        name: Optional name for the tool. Defaults to the function name.
+        desc: Description of the tool.
+        tags: Optional list of tags for the tool.
+        read_only: If True, the tool does not modify its environment (MCP annotation).
+        destructive: If True, the tool may perform destructive updates (MCP annotation).
+        idempotent: If True, repeated calls with same args have no additional effect (MCP annotation).
+        open_world: If True, the tool may interact with external entities (MCP annotation).
+
+    Returns:
+        The decorated function.
+    """
+    tags_list: List[str] = tags or []
+
+    def decorator(fn: F) -> F:
+        sig = inspect.signature(fn)
+        type_hints = get_type_hints(fn)
+
+        # Create a clean schema structure
+        schema: Dict[str, Any] = {"type": "object", "properties": {}}
+        required: List[str] = []
+
+        # Process each parameter
+        for param_name, param in sig.parameters.items():
+            # Get the type hint
+            type_hint = type_hints.get(param_name, Any)
+
+            # Determine if the parameter is required
+            if param.default is inspect.Parameter.empty:
+                required.append(param_name)
+
+            # Convert type hint to JSON schema
+            schema["properties"][param_name] = convert_type_hint_to_json_schema(type_hint)
+
+        # If there are required fields, add them to the schema
+        if required:
+            schema["required"] = required
+
+        # Check if the function is async
+        is_async = inspect.iscoroutinefunction(fn)
+
+        # Create a wrapper function that converts dictionaries to Pydantic models
+        if is_async:
+            # Type ignore for the conditional function variants issue
+            async def wrapped_fn(**kwargs: Any) -> Any:  # type: ignore
+                converted_kwargs = convert_kwargs(kwargs, type_hints)
+                return await fn(**converted_kwargs)
+
+        else:
+
+            def wrapped_fn(**kwargs: Any) -> Any:  # type: ignore
+                converted_kwargs = convert_kwargs(kwargs, type_hints)
+                return fn(**converted_kwargs)
+
+        # Preserve the original function's signature and docstring
+        wrapped_fn.__name__ = fn.__name__
+        wrapped_fn.__doc__ = fn.__doc__
+        wrapped_fn.__annotations__ = fn.__annotations__
+
+        tool_name = name or fn.__name__
+        ConnectorRegistry.register_tool(
+            name=tool_name,
+            description=desc,
+            fn=wrapped_fn,
+            param_schema=schema,
+            tags=tags_list,
+            read_only=read_only,
+            destructive=destructive,
+            idempotent=idempotent,
+            open_world=open_world,
+        )
+        return fn
+
+    return decorator
+
+
+def convert_kwargs(kwargs: Dict[str, Any], type_hints: Dict[str, Any]) -> Dict[str, Any]:
+    """Helper function to convert dictionaries to Pydantic models based on type hints."""
+    converted_kwargs: Dict[str, Any] = {}
+    for param_name, param_value in kwargs.items():
+        if param_name in type_hints:
+            param_type = type_hints[param_name]
+            # Check if it's a Pydantic model
+            if (
+                isinstance(param_value, dict)
+                and hasattr(param_type, "model_validate")
+                and issubclass(param_type, BaseModel)
+            ):
+                # Convert dict to Pydantic model
+                converted_kwargs[param_name] = param_type.model_validate(param_value)
+            # Handle List[PydanticModel]
+            elif (
+                isinstance(param_value, list)
+                and get_origin(param_type) is list
+                and len(get_args(param_type)) > 0
+                and hasattr(get_args(param_type)[0], "model_validate")
+                and issubclass(get_args(param_type)[0], BaseModel)
+            ):
+                model_class = get_args(param_type)[0]
+                converted_kwargs[param_name] = [
+                    model_class.model_validate(item) if isinstance(item, dict) else item for item in param_value
+                ]
+            else:
+                converted_kwargs[param_name] = param_value
+        else:
+            converted_kwargs[param_name] = param_value
+
+    return converted_kwargs

agent_handler_sdk-0.1.8/agent_handler_sdk/utils.py

@@ -0,0 +1,208 @@
+from typing import Any, Dict, List, Optional, Union, get_type_hints, get_origin, get_args, Type
+from enum import Enum
+from pydantic import BaseModel
+
+
+def convert_type_hint_to_json_schema(type_hint: Any) -> Dict[str, Any]:
+    """
+    Convert a Python type hint to a JSON schema representation.
+    Handles primitive types, lists, tuples, unions, optional types, and Pydantic models.
+    """
+    # Handle None type
+    if type_hint is type(None):
+        return {"type": "null"}
+
+    # Handle primitive types
+    if type_hint in (int, float, str, bool):
+        return _convert_primitive_type(type_hint)
+
+    # Handle Pydantic models
+    if hasattr(type_hint, "model_json_schema") and issubclass(type_hint, BaseModel):
+        return _convert_pydantic_type(type_hint)
+
+    # Handle container types (list, tuple, dict)
+    origin = get_origin(type_hint)
+    if origin is list:
+        return _convert_list_type(type_hint)
+    elif origin is tuple:
+        return _convert_tuple_type(type_hint)
+    elif origin is dict:
+        return _convert_dict_type(type_hint)
+
+    # Handle Union and Optional types
+    if origin is Union:
+        return _convert_union_type(type_hint)
+    if origin is Optional:
+        return _convert_optional_type(type_hint)
+
+    # Handle Enum types
+    if isinstance(type_hint, type) and issubclass(type_hint, Enum):
+        return _convert_enum_type(type_hint)
+
+    # Default to string for unknown types
+    return {"type": "string"}
+
+
+def _convert_primitive_type(type_hint: Type) -> Dict[str, Any]:
+    """Convert primitive Python types to JSON schema types."""
+    type_mapping = {
+        int: {"type": "integer"},
+        float: {"type": "number"},
+        str: {"type": "string"},
+        bool: {"type": "boolean"},
+    }
+    return type_mapping.get(type_hint, {"type": "string"})
+
+
+def _convert_list_type(type_hint: Any) -> Dict[str, Any]:
+    """Convert Python list type to JSON schema array."""
+    item_type = get_args(type_hint)[0] if get_args(type_hint) else Any
+    return {"type": "array", "items": convert_type_hint_to_json_schema(item_type)}
+
+
+def _convert_tuple_type(type_hint: Any) -> Dict[str, Any]:
+    """Convert Python tuple type to JSON schema array with constraints."""
+    args = get_args(type_hint)
+    if not args:
+        return {"type": "array"}
+
+    # Handle tuple with variable args (Tuple[int, ...])
+    if len(args) == 2 and args[1] is Ellipsis:
+        return {"type": "array", "items": convert_type_hint_to_json_schema(args[0])}
+
+    # Handle fixed-length tuples
+    return {
+        "type": "array",
+        "minItems": len(args),
+        "maxItems": len(args),
+        "items": [convert_type_hint_to_json_schema(arg) for arg in args],
+    }
+
+
+def _convert_dict_type(type_hint: Any) -> Dict[str, Any]:
+    """Convert Python dict type to JSON schema object."""
+    args = get_args(type_hint)
+    key_type = args[0] if len(args) > 0 else Any
+    value_type = args[1] if len(args) > 1 else Any
+
+    # Only str keys are supported in JSON
+    if key_type is not str and key_type is not Any:
+        key_type = str
+
+    return {"type": "object", "additionalProperties": convert_type_hint_to_json_schema(value_type)}
+
+
+def _convert_union_type(type_hint: Any) -> Dict[str, Any]:
+    """Convert Python Union type to JSON schema anyOf."""
+    union_args = get_args(type_hint)
+
+    # Handle Optional (Union[Type, None])
+    if len(union_args) == 2 and type(None) in union_args:
+        return _convert_optional_union(union_args)
+
+    # Handle regular Union types
+    return {"anyOf": [convert_type_hint_to_json_schema(arg) for arg in union_args]}
+
+
+def _convert_optional_union(union_args: tuple) -> Dict[str, Any]:
+    """Handle Optional as Union[Type, None]."""
+    # Get the non-None type
+    actual_type = union_args[0] if union_args[1] is type(None) else union_args[1]
+    return convert_type_hint_to_json_schema(actual_type)
+
+
+def _convert_optional_type(type_hint: Any) -> Dict[str, Any]:
+    """Convert Python Optional type to JSON schema."""
+    actual_type = get_args(type_hint)[0]
+    return convert_type_hint_to_json_schema(actual_type)
+
+
+def _convert_enum_type(type_hint: Type[Enum]) -> Dict[str, Any]:
+    """Convert Python Enum type to JSON schema enum."""
+    enum_values = [item.value for item in type_hint]
+    return {"enum": enum_values}
+
+
+def _convert_pydantic_type(model: Type[BaseModel]) -> Dict[str, Any]:
+    """
+    Convert a Pydantic model to a flattened JSON schema without references.
+    """
+    # Get the model schema
+    schema = model.model_json_schema()
+
+    # Create a flattened version without references
+    flattened_schema = {"type": "object", "properties": {}}
+
+    # Get the definitions section
+    defs = schema.get("$defs", {})
+
+    # Copy properties and resolve any references
+    if "properties" in schema:
+        flattened_schema["properties"] = _resolve_references(schema["properties"], defs)
+
+    # Copy required fields if present
+    if "required" in schema:
+        flattened_schema["required"] = schema["required"]
+
+    # Copy title if present
+    if "title" in schema:
+        flattened_schema["title"] = schema["title"]
+
+    return flattened_schema
+
+
+def _resolve_references(obj: Any, schema_defs: Dict[str, Any]) -> Any:
+    """
+    Recursively resolve JSON schema references.
+
+    Args:
+        obj: The object to resolve references in
+        schema_defs: The definitions dictionary containing referenced schemas
+
+    Returns:
+        The object with all references resolved
+    """
+    if isinstance(obj, dict):
+        # If this is a reference, resolve it
+        if "$ref" in obj and len(obj) == 1:
+            return _resolve_single_reference(obj, schema_defs)
+
+        # Process each property in the object
+        result = {}
+        for key, value in obj.items():
+            if key == "items" and "$ref" in value:
+                # Special handling for array items with references
+                ref_path = value["$ref"].split("/")[-1]
+                if ref_path in schema_defs:
+                    # Replace with the referenced schema
+                    result[key] = _resolve_references(schema_defs[ref_path], schema_defs)
+            else:
+                # Recursively process the value
+                result[key] = _resolve_references(value, schema_defs)
+        return result
+    elif isinstance(obj, list):
+        # Process each item in the list
+        return [_resolve_references(item, schema_defs) for item in obj]
+    else:
+        # Return primitive values as is
+        return obj
+
+
+def _resolve_single_reference(ref_obj: Dict[str, Any], schema_defs: Dict[str, Any]) -> Any:
+    """
+    Resolve a single reference object.
+
+    Args:
+        ref_obj: The reference object containing a $ref key
+        schema_defs: The definitions dictionary containing referenced schemas
+
+    Returns:
+        The resolved reference
+    """
+    ref_path = ref_obj["$ref"].split("/")[-1]
+    if ref_path in schema_defs:
+        # Replace with a copy of the referenced schema
+        resolved = schema_defs[ref_path].copy()
+        # Recursively resolve any references in the referenced schema
+        return _resolve_references(resolved, schema_defs)
+    return ref_obj  # Reference not found, return as is

agent_handler_sdk-0.1.8/pyproject.toml

@@ -0,0 +1,49 @@
+[tool.poetry]
+name = "agent-handler-sdk"
+version = "0.1.8"
+description = "Agent Handler SDK for defining and invoking LLM tools"
+authors = ["David Dalmaso <david.dalmaso@merge.dev>", "Gil Feig <gil@merge.dev>"]
+packages = [
+  { include = "agent_handler_sdk" }
+]
+
+[tool.poetry.dependencies]
+python = ">=3.10"
+pydantic = "^2.0"
+jsonschema = "^4.0"
+
+[tool.poetry.dev-dependencies]
+pytest = "^7.0"
+pytest-asyncio = "^0.20.3"
+mypy = "^1.4.1"
+black = "^23.3.0"
+pre-commit = "^2.20.0"
+types-jsonschema = "^4.17.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest-asyncio = "^0.20.3"
+pre-commit = "^2.20.0"
+types-jsonschema = "^4.23.0.20241208"
+
+[tool.poetry.scripts]
+ahs-scaffold = "agent_handler_sdk.cli:scaffold_connector"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 120
+target-version = ["py310"]
+include = '\.pyi?$'
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+strict_optional = true