maton-agent-toolkit 0.1.0__py3-none-any.whl

maton_agent_toolkit/__init__.py

@@ -0,0 +1,7 @@
+"""Maton Agent Toolkit - MCP-based toolkit for AI agent frameworks."""
+
+from .configuration import Configuration, Context
+from .shared.constants import VERSION
+
+__all__ = ["Configuration", "Context", "VERSION"]
+__version__ = VERSION

maton_agent_toolkit/configuration.py

@@ -0,0 +1,14 @@
+"""Configuration types for Maton Agent Toolkit."""
+
+from typing_extensions import TypedDict
+
+
+class Context(TypedDict, total=False):
+    """Context for MCP connection."""
+    connection: str | None
+    mode: str | None
+
+
+class Configuration(TypedDict, total=False):
+    """Configuration for Maton Agent Toolkit."""
+    context: Context | None

maton_agent_toolkit/crewai/__init__.py

@@ -0,0 +1,5 @@
+"""Maton Agent Toolkit for CrewAI."""
+
+from .toolkit import MatonAgentToolkit, create_maton_agent_toolkit
+
+__all__ = ["MatonAgentToolkit", "create_maton_agent_toolkit"]

maton_agent_toolkit/crewai/toolkit.py

@@ -0,0 +1,134 @@
+"""Maton Agent Toolkit for CrewAI."""
+
+import asyncio
+from typing import List, Any, Type, Callable, Awaitable
+
+from pydantic import BaseModel
+from crewai.tools import BaseTool
+
+from ..shared.toolkit_core import ToolkitCore
+from ..shared.mcp_client import McpTool
+from ..shared.schema_utils import json_schema_to_pydantic_model
+from ..configuration import Configuration
+
+
+class MatonTool(BaseTool):
+    """Tool for interacting with Maton via MCP."""
+
+    run_tool: Callable[..., Awaitable[str]]
+    method: str
+    name: str = ""
+    description: str = ""
+    args_schema: Type[BaseModel] | None = None
+
+    def _run(self, **kwargs: Any) -> str:
+        """Synchronous execution - wraps async call."""
+        loop = asyncio.get_event_loop()
+        if loop.is_running():
+            # If we're already in an async context, create a new loop
+            import concurrent.futures
+            with concurrent.futures.ThreadPoolExecutor() as pool:
+                future = pool.submit(
+                    asyncio.run,
+                    self.run_tool(self.method, kwargs)
+                )
+                return future.result()
+        else:
+            return loop.run_until_complete(
+                self.run_tool(self.method, kwargs)
+            )
+
+    async def _arun(self, **kwargs: Any) -> str:
+        """Async execution via MCP."""
+        return await self.run_tool(self.method, kwargs)
+
+
+class MatonAgentToolkit(ToolkitCore[List[MatonTool]]):
+    """
+    Maton Agent Toolkit for CrewAI.
+
+    Example:
+        toolkit = await create_maton_agent_toolkit(
+            api_key='YOUR_MATON_API_KEY',
+        )
+        tools = toolkit.get_tools()
+        agent = Agent(role="...", tools=tools)
+        await toolkit.close()
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        configuration: Configuration | None = None
+    ):
+        super().__init__(api_key, configuration)
+
+    def _empty_tools(self) -> List[MatonTool]:
+        """Return empty list of tools."""
+        return []
+
+    def _convert_tools(
+        self,
+        mcp_tools: List[McpTool]
+    ) -> List[MatonTool]:
+        """Convert MCP tools to CrewAI MatonTool instances."""
+        tools = []
+        for mcp_tool in mcp_tools:
+            # Convert JSON Schema to Pydantic model
+            args_schema = json_schema_to_pydantic_model(
+                mcp_tool.get("inputSchema"),
+                model_name=f"{mcp_tool['name']}_args"
+            )
+
+            tools.append(MatonTool(
+                run_tool=self.run_tool,
+                method=mcp_tool["name"],
+                name=mcp_tool["name"],
+                description=mcp_tool.get("description", mcp_tool["name"]),
+                args_schema=args_schema,
+            ))
+        return tools
+
+    @property
+    def tools(self) -> List[MatonTool]:
+        """
+        The tools available in the toolkit.
+
+        .. deprecated::
+            Access tools via get_tools() after calling initialize().
+        """
+        return self._get_tools_with_warning()
+
+
+async def create_maton_agent_toolkit(
+    api_key: str | None = None,
+    configuration: Configuration | None = None
+) -> MatonAgentToolkit:
+    """
+    Factory function to create and initialize a MatonAgentToolkit.
+
+    This is the recommended way to create a toolkit as it handles
+    async initialization automatically.
+
+    Example:
+        toolkit = await create_maton_agent_toolkit(
+            api_key='YOUR_MATON_API_KEY',
+        )
+        tools = toolkit.get_tools()
+
+        # Use with CrewAI agent
+        agent = Agent(role="Maton Agent", tools=tools)
+
+        # Clean up when done
+        await toolkit.close()
+
+    Args:
+        api_key: Maton API key. Create one at https://maton.ai
+        configuration: Optional configuration for context
+
+    Returns:
+        Initialized MatonAgentToolkit ready to use
+    """
+    toolkit = MatonAgentToolkit(api_key, configuration)
+    await toolkit.initialize()
+    return toolkit

maton_agent_toolkit/langchain/__init__.py

@@ -0,0 +1,5 @@
+"""Maton Agent Toolkit for LangChain."""
+
+from .toolkit import MatonAgentToolkit, create_maton_agent_toolkit
+
+__all__ = ["MatonAgentToolkit", "create_maton_agent_toolkit"]

maton_agent_toolkit/langchain/toolkit.py

@@ -0,0 +1,134 @@
+"""Maton Agent Toolkit for LangChain."""
+
+import asyncio
+from typing import List, Any, Type, Callable, Awaitable
+
+from pydantic import BaseModel
+from langchain_core.tools import BaseTool
+
+from ..shared.toolkit_core import ToolkitCore
+from ..shared.mcp_client import McpTool
+from ..shared.schema_utils import json_schema_to_pydantic_model
+from ..configuration import Configuration
+
+
+class MatonTool(BaseTool):
+    """Tool for interacting with Maton via MCP."""
+
+    run_tool: Callable[..., Awaitable[str]]
+    method: str
+    name: str = ""
+    description: str = ""
+    args_schema: Type[BaseModel] | None = None
+
+    def _run(self, **kwargs: Any) -> str:
+        """Synchronous execution - wraps async call."""
+        loop = asyncio.get_event_loop()
+        if loop.is_running():
+            # If we're already in an async context, create a new loop
+            import concurrent.futures
+            with concurrent.futures.ThreadPoolExecutor() as pool:
+                future = pool.submit(
+                    asyncio.run,
+                    self.run_tool(self.method, kwargs)
+                )
+                return future.result()
+        else:
+            return loop.run_until_complete(
+                self.run_tool(self.method, kwargs)
+            )
+
+    async def _arun(self, **kwargs: Any) -> str:
+        """Async execution via MCP."""
+        return await self.run_tool(self.method, kwargs)
+
+
+class MatonAgentToolkit(ToolkitCore[List[MatonTool]]):
+    """
+    Maton Agent Toolkit for LangChain.
+
+    Example:
+        toolkit = await create_maton_agent_toolkit(
+            api_key='YOUR_MATON_API_KEY',
+        )
+        tools = toolkit.get_tools()
+        agent = create_react_agent(llm, tools, prompt)
+        await toolkit.close()
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        configuration: Configuration | None = None
+    ):
+        super().__init__(api_key, configuration)
+
+    def _empty_tools(self) -> List[MatonTool]:
+        """Return empty list of tools."""
+        return []
+
+    def _convert_tools(
+        self,
+        mcp_tools: List[McpTool]
+    ) -> List[MatonTool]:
+        """Convert MCP tools to LangChain MatonTool instances."""
+        tools = []
+        for mcp_tool in mcp_tools:
+            # Convert JSON Schema to Pydantic model
+            args_schema = json_schema_to_pydantic_model(
+                mcp_tool.get("inputSchema"),
+                model_name=f"{mcp_tool['name']}_args"
+            )
+
+            tools.append(MatonTool(
+                run_tool=self.run_tool,
+                method=mcp_tool["name"],
+                name=mcp_tool["name"],
+                description=mcp_tool.get("description", mcp_tool["name"]),
+                args_schema=args_schema,
+            ))
+        return tools
+
+    @property
+    def tools(self) -> List[MatonTool]:
+        """
+        The tools available in the toolkit.
+
+        .. deprecated::
+            Access tools via get_tools() after calling initialize().
+        """
+        return self._get_tools_with_warning()
+
+
+async def create_maton_agent_toolkit(
+    api_key: str | None = None,
+    configuration: Configuration | None = None
+) -> MatonAgentToolkit:
+    """
+    Factory function to create and initialize a MatonAgentToolkit.
+
+    This is the recommended way to create a toolkit as it handles
+    async initialization automatically.
+
+    Example:
+        toolkit = await create_maton_agent_toolkit(
+            api_key='YOUR_MATON_API_KEY',
+        )
+        tools = toolkit.get_tools()
+
+        # Use with LangChain agent
+        agent = create_react_agent(llm, tools, prompt)
+
+        # Clean up when done
+        await toolkit.close()
+
+    Args:
+        api_key: Maton API key. Create one at https://maton.ai
+        configuration: Optional configuration for context
+
+    Returns:
+        Initialized MatonAgentToolkit ready to use
+    """
+    toolkit = MatonAgentToolkit(api_key, configuration)
+    await toolkit.initialize()
+    return toolkit

maton_agent_toolkit/openai/__init__.py

@@ -0,0 +1,5 @@
+"""Maton Agent Toolkit for OpenAI Agents SDK."""
+
+from .toolkit import MatonAgentToolkit, create_maton_agent_toolkit
+
+__all__ = ["MatonAgentToolkit", "create_maton_agent_toolkit"]

maton_agent_toolkit/openai/toolkit.py

@@ -0,0 +1,125 @@
+"""Maton Agent Toolkit for OpenAI Agents SDK."""
+
+import json
+from typing import List, Any
+
+from agents import FunctionTool
+from agents.run_context import RunContextWrapper
+
+from ..shared.toolkit_core import ToolkitCore
+from ..shared.mcp_client import McpTool
+from ..configuration import Configuration
+
+
+class MatonAgentToolkit(ToolkitCore[List[FunctionTool]]):
+    """
+    Maton Agent Toolkit for OpenAI Agents SDK.
+
+    Example:
+        toolkit = await create_maton_agent_toolkit(
+            api_key='YOUR_MATON_API_KEY',
+        )
+        tools = toolkit.get_tools()
+        agent = Agent(name="Maton Agent", tools=tools)
+        await toolkit.close()
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        configuration: Configuration | None = None
+    ):
+        super().__init__(api_key, configuration)
+
+    def _empty_tools(self) -> List[FunctionTool]:
+        """Return empty list of tools."""
+        return []
+
+    def _convert_tools(
+        self,
+        mcp_tools: List[McpTool]
+    ) -> List[FunctionTool]:
+        """Convert MCP tools to OpenAI FunctionTool instances."""
+        tools = []
+        for mcp_tool in mcp_tools:
+            tools.append(self._create_function_tool(mcp_tool))
+        return tools
+
+    def _create_function_tool(self, mcp_tool: McpTool) -> FunctionTool:
+        """Create a FunctionTool from an MCP tool definition."""
+        toolkit = self
+        tool_name = mcp_tool["name"]
+
+        async def on_invoke_tool(
+            ctx: RunContextWrapper[Any],
+            input_str: str
+        ) -> str:
+            args = json.loads(input_str)
+            return await toolkit.run_tool(tool_name, args)
+
+        # Prepare parameters schema
+        parameters = dict(mcp_tool.get("inputSchema", {}))
+        parameters["additionalProperties"] = False
+        parameters["type"] = "object"
+
+        # Clean up schema - remove fields not needed in OpenAI function schema
+        for key in ["description", "title"]:
+            parameters.pop(key, None)
+
+        if "properties" in parameters:
+            for prop in parameters["properties"].values():
+                for key in ["title", "default"]:
+                    if isinstance(prop, dict):
+                        prop.pop(key, None)
+
+        return FunctionTool(
+            name=tool_name,
+            description=mcp_tool.get("description", tool_name),
+            params_json_schema=parameters,
+            on_invoke_tool=on_invoke_tool,
+            strict_json_schema=False
+        )
+
+    @property
+    def tools(self) -> List[FunctionTool]:
+        """
+        The tools available in the toolkit.
+
+        .. deprecated::
+            Access tools via get_tools() after calling initialize().
+        """
+        return self._get_tools_with_warning()
+
+
+async def create_maton_agent_toolkit(
+    api_key: str | None = None,
+    configuration: Configuration | None = None
+) -> MatonAgentToolkit:
+    """
+    Factory function to create and initialize a MatonAgentToolkit.
+
+    This is the recommended way to create a toolkit as it handles
+    async initialization automatically.
+
+    Example:
+        toolkit = await create_maton_agent_toolkit(
+            api_key='YOUR_MATON_API_KEY',
+        )
+        tools = toolkit.get_tools()
+
+        # Use with agent
+        agent = Agent(name="Maton Agent", tools=tools)
+
+        # Clean up when done
+        await toolkit.close()
+
+    Args:
+        api_key: Maton API key. Create one at https://maton.ai
+        configuration: Optional configuration for context
+
+    Returns:
+        Initialized MatonAgentToolkit ready to use
+    """
+    toolkit = MatonAgentToolkit(api_key, configuration)
+    await toolkit.initialize()
+    return toolkit

maton_agent_toolkit/shared/__init__.py

@@ -0,0 +1,21 @@
+"""Shared infrastructure for Maton Agent Toolkit MCP integration."""
+
+from .constants import VERSION, MCP_SERVER_URL, TOOLKIT_HEADER, MCP_HEADER
+from .async_initializer import AsyncInitializer
+from .mcp_client import MatonMcpClient, McpTool, McpToolInputSchema
+from .schema_utils import json_schema_to_pydantic_model, json_schema_to_pydantic_fields
+from .toolkit_core import ToolkitCore
+
+__all__ = [
+    "VERSION",
+    "MCP_SERVER_URL",
+    "TOOLKIT_HEADER",
+    "MCP_HEADER",
+    "AsyncInitializer",
+    "MatonMcpClient",
+    "McpTool",
+    "McpToolInputSchema",
+    "json_schema_to_pydantic_model",
+    "json_schema_to_pydantic_fields",
+    "ToolkitCore",
+]

maton_agent_toolkit/shared/async_initializer.py

@@ -0,0 +1,71 @@
+"""Async initialization utility for Maton Agent Toolkit."""
+
+import asyncio
+from typing import Callable, Awaitable
+
+
+class AsyncInitializer:
+    """
+    A reusable utility for async initialization with future locking.
+    Ensures initialization runs only once, even if called concurrently.
+    """
+
+    def __init__(self) -> None:
+        self._initialized: bool = False
+        self._init_future: asyncio.Future[None] | None = None
+        self._lock: asyncio.Lock = asyncio.Lock()
+
+    async def initialize(
+        self, do_initialize: Callable[[], Awaitable[None]]
+    ) -> None:
+        """
+        Initialize using the provided coroutine function.
+
+        - If already initialized, returns immediately
+        - If initialization in progress, awaits existing future
+        - If initialization fails, allows retry on next call
+
+        Args:
+            do_initialize: Async function that performs the actual
+                initialization work.
+
+        Raises:
+            Exception: Re-raises any exception from do_initialize,
+                allowing retry on next call.
+        """
+        if self._initialized:
+            return
+
+        async with self._lock:
+            # Double-check after acquiring lock
+            if self._initialized:
+                return
+
+            if self._init_future is not None:
+                # Another coroutine is initializing, wait for it
+                await self._init_future
+                return
+
+            # Create a new future for this initialization attempt
+            loop = asyncio.get_running_loop()
+            self._init_future = loop.create_future()
+
+            try:
+                await do_initialize()
+                self._initialized = True
+                self._init_future.set_result(None)
+            except Exception as e:
+                # Reset future on failure to allow retry
+                self._init_future.set_exception(e)
+                self._init_future = None
+                raise
+
+    @property
+    def is_initialized(self) -> bool:
+        """Check if initialization has completed successfully."""
+        return self._initialized
+
+    def reset(self) -> None:
+        """Reset the initializer state. Used during close/cleanup."""
+        self._initialized = False
+        self._init_future = None

maton_agent_toolkit/shared/constants.py

@@ -0,0 +1,6 @@
+"""Shared constants for Maton Agent Toolkit."""
+
+VERSION = "0.1.0"
+MCP_SERVER_URL = "https://mcp.maton.ai"
+TOOLKIT_HEADER = "maton-agent-toolkit-python"
+MCP_HEADER = "maton-mcp-python"