Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

feat(py): support type-safe generic get_tools() based on given provider (#2469)

Alberto Schiabelff1e89b7c2e1
diff --git a/.claude/commands/changelog.md b/.claude/commands/changelog.md
index e8fbcd329..8308af98f 100644
--- a/.claude/commands/changelog.md
+++ b/.claude/commands/changelog.md
@@ -1,68 +1,103 @@
-Check the changes between the current branch and next branch, and create a changelog file inside `/fern/pages/src/changelog` in the file format of `MM-DD-YY-<title>.md`.
+Check the changes between the current branch and next branch, and create a changelog file inside `/docs/content/changelog` in the file format of `MM-DD-YY-<title>.mdx`.
-## Changelog File Structure
+## File Naming
-### Required Sections
+```
+MM-DD-YY.mdx # e.g., 12-29-25.mdx
+MM-DD-YY-suffix.mdx # Multiple same day: 12-10-25-masking.mdx
+```
+
+## Template
-1. **Title** (H1): A clear, descriptive title of the change
-2. **Version Information**: Include SDK versions for both TypeScript and Python
-3. **Description**: Brief explanation of what changed and why
+```mdx
+---
+title: "Your Title Here"
+description: "Brief description of the change"
+date: "YYYY-MM-DD"
+---
-### Version Information Format
+Brief intro paragraph explaining what changed.
-```markdown
-## Version Information
+### SDK Versions
-### TypeScript/JavaScript
-- Package: `@composio/core` (and provider packages if applicable)
-- Version: `X.Y.Z`+
+| SDK | Version |
+|-----|---------|
+| Python | vX.Y.Z+ |
+| TypeScript | vX.Y.Z+ |
-### Python
-- Package: `composio` (and provider packages if applicable)
-- Version: `X.Y.Z`+
+### What Changed (if applicable)
+
+**Before:**
+```python
+old_code()
```
-Use `+` suffix to indicate "this version and later".
+**After:**
+```python
+new_code()
+```
-### Optional Sections (include as needed)
+### Breaking Changes (if applicable)
-- **What Changed**: Before/after comparison with code examples
-- **Why This Change?**: Explanation of the motivation
-- **New Features/Capabilities**: For feature additions
-- **Migration Guide**: For breaking changes
-- **Backward Compatibility**: Compatibility notes
-- **Impact Summary**: Table showing breaking changes and migration requirements
-- **How to Update**: Package manager commands for updating
+<Callout type="warn">
+**Breaking Change**
-### Alerts
+What breaks and why.
+</Callout>
-Use these MDX components for important notices:
-- `<Warning>` for breaking changes
-- `<Note>` for important information
+### What's New / Improvements / Bug Fixes
-### Code Examples
+- Change 1
+- Change 2
-Use `<CodeBlocks>` for side-by-side Python/TypeScript examples:
+### Backward Compatibility
-```markdown
-<CodeBlocks>
-```python title="Python SDK"
-# Python code
+Notes about backward compatibility.
```
-```typescript title="TypeScript SDK"
-// TypeScript code
-```
-</CodeBlocks>
+## Rules
+
+1. **Frontmatter required** - `title`, `description`, and `date` (YYYY-MM-DD format)
+2. **No `#` heading** - Title renders automatically from frontmatter
+3. **Use `###` for sections** - Content headings start at h3
+4. **No emojis** - No checkmarks, warning symbols, etc. in prose (okay in code comments)
+5. **TypeScript code blocks** - Add `// @noErrors` on first line to skip type checking
+
+## Change Types
+
+| Type | How to Format |
+|------|---------------|
+| Breaking Change | `<Callout type="warn">` + before/after code + migration guide |
+| New Feature | `### What's New` |
+| Improvement | `### Improvements` |
+| Bug Fix | `### Bug Fixes` or inline description |
+| Deprecation | `<Callout>` with timeline |
+
+## Code Examples
+
+For TypeScript code that shouldn't be type-checked:
+
+```typescript
+// @noErrors
+const result = await composio.tools.get(userId);
```
-## Examples
+For before/after comparisons, use labeled sections:
-- Bug fix: `01-21-26-initiate-active-status-filter.md`
-- Breaking change: `01-14-26-auth-config-patch-semantics.md`
-- New feature: `01-12-26-tool-router-improvements.md`
-- Simple change: `01-09-26.md`
+**Before:**
+```python
+old_code()
+```
+
+**After:**
+```python
+new_code()
+```
-## Instructions
-- Avoid using emojies in top level, it's okay within code samples only when necessary
+## Examples
+Reference these existing changelogs for style:
+- Bug fix: `01-21-26-initiate-active-status-filter.mdx`
+- Breaking change: `01-14-26-auth-config-patch-semantics.mdx`
+- New feature: `01-12-26-tool-router-improvements.mdx`
+- Simple change: `01-30-26-simplified-optional-schemas.mdx`
diff --git a/.github/workflows/py.check.yaml b/.github/workflows/py.check.yaml
index 28af31365..5f0d83775 100644
--- a/.github/workflows/py.check.yaml
+++ b/.github/workflows/py.check.yaml
@@ -62,3 +62,11 @@ jobs:
run: |
cd python/
uv run nox -s chk
+
+ - name: Type inference tests
+ shell: bash
+ run: |
+ cd python/
+ uv run nox -s type_inference
+ env:
+ COMPOSIO_API_KEY: ${{ secrets.COMPOSIO_API_KEY }}
diff --git a/docs/content/changelog/02-01-26-type-safe-get-tools-python.mdx b/docs/content/changelog/02-01-26-type-safe-get-tools-python.mdx
new file mode 100644
index 000000000..ab48a2a55
--- /dev/null
+++ b/docs/content/changelog/02-01-26-type-safe-get-tools-python.mdx
@@ -0,0 +1,134 @@
+---
+title: "Type-Safe get_tools() for Python SDK"
+description: "The Python SDK now provides automatic type inference for tools.get() based on the provider"
+date: "2026-02-01"
+---
+
+The Python SDK's `Composio` class is now generic over the provider type. When you pass a provider to `Composio()`, the return type of `tools.get()` is automatically inferred based on that provider.
+
+### SDK Versions
+
+| SDK | Version |
+|-----|---------|
+| Python | v0.11.1+ |
+
+### What Changed
+
+**Before:** The return type of `tools.get()` was always untyped or required manual type annotations.
+
+**After:** Type checkers (mypy, Pyright) automatically infer the correct tool type from the provider you pass.
+
+**Before (untyped):**
+```python
+from composio import Composio
+from composio_anthropic import AnthropicProvider
+
+composio = Composio(provider=AnthropicProvider())
+tools = composio.tools.get(user_id="user_123", toolkits=["github"])
+# tools: Unknown type - no inference
+```
+
+**After (type-safe):**
+```python
+from composio import Composio
+from composio_anthropic import AnthropicProvider
+
+composio = Composio(provider=AnthropicProvider())
+tools = composio.tools.get(user_id="user_123", toolkits=["github"])
+# tools: list[ToolParam] - automatically inferred!
+```
+
+### Automatic Type Inference
+
+The `Composio` class now uses Python generics to provide type-safe return values:
+
+```python
+from composio import Composio
+from composio_openai import OpenAIProvider
+from composio_anthropic import AnthropicProvider
+
+# OpenAI provider -> list[ChatCompletionToolParam]
+composio_openai = Composio(provider=OpenAIProvider())
+openai_tools = composio_openai.tools.get(user_id="user", toolkits=["github"])
+
+# Anthropic provider -> list[ToolParam]
+composio_anthropic = Composio(provider=AnthropicProvider())
+anthropic_tools = composio_anthropic.tools.get(user_id="user", toolkits=["github"])
+
+# Default (no provider) -> list[ChatCompletionToolParam] (OpenAI)
+composio_default = Composio()
+default_tools = composio_default.tools.get(user_id="user", toolkits=["github"])
+```
+
+### Custom Provider Support
+
+Custom providers automatically get proper type inference without requiring any changes to the Composio SDK:
+
+```python
+import typing as t
+from typing import Sequence
+
+from composio import Composio
+from composio.client.types import Tool
+from composio.core.provider import NonAgenticProvider
+
+
+class MyCustomTool(t.TypedDict):
+ """Your custom tool format."""
+ name: str
+ description: str
+ parameters: dict
+
+
+MyCustomToolCollection = t.List[MyCustomTool]
+
+
+class MyCustomProvider(
+ NonAgenticProvider[MyCustomTool, MyCustomToolCollection],
+ name="my-custom"
+):
+ def wrap_tool(self, tool: Tool) -> MyCustomTool:
+ return MyCustomTool(
+ name=tool.slug,
+ description=tool.description or "",
+ parameters=tool.input_parameters or {},
+ )
+
+ def wrap_tools(self, tools: Sequence[Tool]) -> MyCustomToolCollection:
+ return [self.wrap_tool(tool) for tool in tools]
+
+
+# Type inference works automatically!
+composio = Composio(provider=MyCustomProvider())
+tools = composio.tools.get(user_id="user", toolkits=["github"])
+# tools: list[MyCustomTool] - correctly inferred
+```
+
+### Supported Providers
+
+Type inference is supported for all built-in providers:
+
+| Provider | Tool Type |
+|----------|-----------|
+| OpenAI | `ChatCompletionToolParam` |
+| OpenAI Responses | `dict[str, Any]` |
+| Anthropic | `ToolParam` |
+| Google (GenAI) | `FunctionDeclaration` |
+| Gemini | `FunctionDeclaration` |
+| Google ADK | `Tool` |
+| LangChain | `StructuredTool` |
+| LangGraph | `StructuredTool` |
+| LlamaIndex | `FunctionTool` |
+| CrewAI | `Tool` |
+| AutoGen | `FunctionTool` |
+| OpenAI Agents | `FunctionTool` |
+| Claude Agent SDK | `Tool` |
+
+### Backward Compatibility
+
+This change is fully backward compatible:
+
+- Existing code continues to work without modifications
+- Type inference is opt-in via static type checkers
+- No runtime behavior changes
+- No migration required
diff --git a/python/Makefile b/python/Makefile
index ba5c72915..ea7c82b14 100644
--- a/python/Makefile
+++ b/python/Makefile
@@ -57,6 +57,9 @@ snt:
tst:
@nox -s tst
+type_inference:
+ @nox -s type_inference
+
bump: clean-build
@uv run python scripts/bump.py
diff --git a/python/composio/core/models/tool_router.py b/python/composio/core/models/tool_router.py
index 43b68dd0f..8bd795fe5 100644
--- a/python/composio/core/models/tool_router.py
+++ b/python/composio/core/models/tool_router.py
@@ -18,7 +18,8 @@ import typing_extensions as te
from composio.client import HttpClient
from composio.core.models.base import Resource
from composio.core.models.connected_accounts import ConnectionRequest
-from composio.core.provider import TProvider
+from composio.core.provider import TTool, TToolCollection
+from composio.core.provider.base import BaseProvider
if t.TYPE_CHECKING:
from composio.core.models._modifiers import Modifiers
@@ -33,10 +34,21 @@ ToolkitsFn = t.Callable[
]
-class ToolsFn(t.Protocol):
- """Protocol for the tools function that returns provider-wrapped tools."""
+# Local type variable for ToolsFn protocol (covariant for return type)
+_TToolCollectionReturn = t.TypeVar("_TToolCollectionReturn", covariant=True)
- def __call__(self, modifiers: t.Optional["Modifiers"] = None) -> t.Any:
+
+class ToolsFn(t.Protocol[_TToolCollectionReturn]):
+ """Protocol for the tools function that returns provider-wrapped tools.
+
+ The return type is generic to support provider-specific tool collections.
+ For example, AnthropicProvider returns list[ToolParam], OpenAIProvider
+ returns list[ChatCompletionToolParam], etc.
+ """
+
+ def __call__(
+ self, modifiers: t.Optional["Modifiers"] = None
+ ) -> _TToolCollectionReturn:
"""Get provider-wrapped tools for execution with your AI framework."""
...
@@ -309,10 +321,14 @@ class ToolRouterSessionExperimental:
@dataclass
-class ToolRouterSession(t.Generic[TProvider]):
+class ToolRouterSession(t.Generic[TTool, TToolCollection]):
"""
Tool router session containing session information and helper functions.
+ Generic Parameters:
+ TTool: The individual tool type returned by the provider.
+ TToolCollection: The collection type returned by tools().
+
Attributes:
session_id: Unique session identifier
mcp: MCP server configuration
@@ -320,17 +336,21 @@ class ToolRouterSession(t.Generic[TProvider]):
authorize: Function to authorize a toolkit
toolkits: Function to get toolkit connection states
experimental: Optional experimental features data from the session response
+
+ Note:
+ The `tools` function returns a provider-specific tool collection.
+ The return type is inferred from the provider's generic parameters.
"""
session_id: str
mcp: ToolRouterMCPServerConfig
- tools: ToolsFn
+ tools: "ToolsFn[TToolCollection]"
authorize: AuthorizeFn
toolkits: ToolkitsFn
experimental: t.Optional[ToolRouterSessionExperimental] = None
-class ToolRouter(Resource, t.Generic[TProvider]):
+class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
"""
ToolRouter class for managing tool routing sessions.
@@ -361,7 +381,7 @@ class ToolRouter(Resource, t.Generic[TProvider]):
def __init__(
self,
client: HttpClient,
- provider: t.Optional[TProvider] = None,
+ provider: t.Optional["BaseProvider[TTool, TToolCollection]"] = None,
auto_upload_download_files: bool = True,
):
"""
@@ -602,7 +622,7 @@ class ToolRouter(Resource, t.Generic[TProvider]):
def _create_tools_fn(
self,
session_id: str,
- ) -> ToolsFn:
+ ) -> ToolsFn[TToolCollection]:
"""
Create a tools function that wraps tools for the provider.
@@ -625,7 +645,7 @@ class ToolRouter(Resource, t.Generic[TProvider]):
auto_upload_download_files=self._auto_upload_download_files,
)
- def tools_fn(modifiers: t.Optional[Modifiers] = None) -> t.Any:
+ def tools_fn(modifiers: t.Optional[Modifiers] = None) -> TToolCollection:
"""
Get provider-wrapped tools for execution with your AI framework.
@@ -702,15 +722,23 @@ class ToolRouter(Resource, t.Generic[TProvider]):
# Wrap tools with provider
if issubclass(type(self._provider), NonAgenticProvider):
- return t.cast(NonAgenticProvider, self._provider).wrap_tools(
- tools=router_tools
+ return t.cast(
+ TToolCollection,
+ t.cast(
+ NonAgenticProvider[TTool, TToolCollection], self._provider
+ ).wrap_tools(tools=router_tools),
)
- return t.cast(AgenticProvider, self._provider).wrap_tools(
- tools=router_tools,
- execute_tool=tools_model._wrap_execute_tool_for_tool_router(
- session_id=session_id,
- modifiers=modifiers,
+ return t.cast(
+ TToolCollection,
+ t.cast(
+ AgenticProvider[TTool, TToolCollection], self._provider
+ ).wrap_tools(
+ tools=router_tools,
+ execute_tool=tools_model._wrap_execute_tool_for_tool_router(
+ session_id=session_id,
+ modifiers=modifiers,
+ ),
),
)
@@ -775,7 +803,7 @@ class ToolRouter(Resource, t.Generic[TProvider]):
connected_accounts: t.Optional[t.Dict[str, str]] = None,
workbench: t.Optional[ToolRouterWorkbenchConfig] = None,
experimental: t.Optional[ToolRouterExperimentalConfig] = None,
- ) -> ToolRouterSession[TProvider]:
+ ) -> ToolRouterSession[TTool, TToolCollection]:
"""
Create a new tool router session for a user.
@@ -1071,7 +1099,7 @@ class ToolRouter(Resource, t.Generic[TProvider]):
experimental=experimental_response,
)
- def use(self, session_id: str) -> ToolRouterSession[TProvider]:
+ def use(self, session_id: str) -> ToolRouterSession[TTool, TToolCollection]:
"""
Retrieve and use an existing tool router session.
diff --git a/python/composio/core/models/tools.py b/python/composio/core/models/tools.py
index d51823ed6..c6fbcca17 100644
--- a/python/composio/core/models/tools.py
+++ b/python/composio/core/models/tools.py
@@ -16,18 +16,14 @@ from composio.client.types import (
from composio.core.models._files import FileHelper
from composio.core.models.base import Resource
from composio.core.models.custom_tools import CustomTools
-from composio.core.provider import (
- TProvider,
-)
+from composio.core.provider import TTool, TToolCollection
from composio.core.provider.agentic import AgenticProvider, AgenticProviderExecuteFn
-from composio.core.provider.none_agentic import (
- NonAgenticProvider,
-)
+from composio.core.provider.base import BaseProvider, ExecuteToolFn
+from composio.core.provider.none_agentic import NonAgenticProvider
from composio.core.types import ToolkitVersionParam
from composio.exceptions import InvalidParams, NotFoundError, ToolVersionRequiredError
from composio.utils.pydantic import none_to_omit
from composio.utils.toolkit_version import get_toolkit_version
-from composio.core.provider.base import ExecuteToolFn
from ._modifiers import (
Modifiers,
@@ -45,20 +41,27 @@ class ToolExecutionResponse(te.TypedDict):
successful: bool
-class Tools(Resource, t.Generic[TProvider]):
+class Tools(Resource, t.Generic[TTool, TToolCollection]):
"""
Tools class definition
This class is used to manage tools in the Composio SDK.
It provides methods to list, get, and execute tools.
+
+ Generic Parameters:
+ TTool: The individual tool type returned by the provider (e.g., ChatCompletionToolParam for OpenAI).
+ TToolCollection: The collection type returned by get() (e.g., list[ChatCompletionToolParam]).
+
+ The return type of get() is automatically inferred from the provider's generic parameters.
+ This works for both built-in providers (OpenAI, Anthropic, etc.) and custom providers.
"""
- provider: TProvider
+ provider: BaseProvider[TTool, TToolCollection]
def __init__(
self,
client: HttpClient,
- provider: TProvider,
+ provider: BaseProvider[TTool, TToolCollection],
file_download_dir: t.Optional[str] = None,
toolkit_versions: t.Optional[ToolkitVersionParam] = None,
auto_upload_download_files: bool = True,
@@ -238,7 +241,7 @@ class Tools(Resource, t.Generic[TProvider]):
scopes: t.Optional[t.List[str]] = None,
modifiers: t.Optional[Modifiers] = None,
limit: t.Optional[int] = None,
- ):
+ ) -> TToolCollection:
"""Get a list of tools based on the provided filters."""
tools_list = self.get_raw_composio_tools(
tools=tools,
@@ -280,72 +283,24 @@ class Tools(Resource, t.Generic[TProvider]):
)
if issubclass(type(self.provider), NonAgenticProvider):
- return t.cast(NonAgenticProvider, self.provider).wrap_tools(
- tools=tools_list
+ return t.cast(
+ TToolCollection,
+ t.cast(
+ NonAgenticProvider[TTool, TToolCollection], self.provider
+ ).wrap_tools(tools=tools_list),
)
- return t.cast(AgenticProvider, self.provider).wrap_tools(
- tools=tools_list,
- execute_tool=self._wrap_execute_tool(
- user_id=user_id,
- modifiers=modifiers,
+ return t.cast(
+ TToolCollection,
+ t.cast(AgenticProvider[TTool, TToolCollection], self.provider).wrap_tools(
+ tools=tools_list,
+ execute_tool=self._wrap_execute_tool(
+ user_id=user_id,
+ modifiers=modifiers,
+ ),
),
)
- @t.overload
- def get(
- self,
- user_id: str,
- *,
- slug: str,
- modifiers: t.Optional[Modifiers] = None,
- ):
- """Get tool by slug"""
-
- @t.overload
- def get(
- self,
- user_id: str,
- *,
- tools: list[str],
- modifiers: t.Optional[Modifiers] = None,
- ):
- """Get tools by tool slugs"""
-
- @t.overload
- def get(
- self,
- user_id: str,
- *,
- toolkits: list[str],
- scopes: t.Optional[t.List[str]] = None,
- limit: t.Optional[int] = None,
- modifiers: t.Optional[Modifiers] = None,
- ):
- """Get tools by toolkit slugs (Only important tools are returned)"""
-
- @t.overload
- def get(
- self,
- user_id: str,
- *,
- search: str,
- modifiers: t.Optional[Modifiers] = None,
- ):
- """Search tool by search term"""
-
- @t.overload
- def get(
- self,
- user_id: str,
- *,
- toolkits: list[str],
- search: t.Optional[str] = None,
- limit: t.Optional[int] = None,
- modifiers: t.Optional[Modifiers] = None,
- ):
- """Get tool by search term and/or toolkit slugs and search term"""
-
def get(
self,
user_id: str,
@@ -357,8 +312,26 @@ class Tools(Resource, t.Generic[TProvider]):
scopes: t.Optional[t.List[str]] = None,
modifiers: t.Optional[Modifiers] = None,
limit: t.Optional[int] = None,
- ):
- """Get a tool or list of tools based on the provided arguments."""
+ ) -> TToolCollection:
+ """
+ Get a tool or list of tools based on the provided arguments.
+
+ The return type is automatically inferred based on the provider's generic parameters.
+ For example:
+ - OpenAIProvider -> list[ChatCompletionToolParam]
+ - AnthropicProvider -> list[ToolParam]
+ - CustomProvider[MyTool, list[MyTool]] -> list[MyTool]
+
+ :param user_id: The user ID to get tools for.
+ :param slug: Get a single tool by slug.
+ :param tools: Get tools by a list of tool slugs.
+ :param search: Search tools by search term.
+ :param toolkits: Get tools from specific toolkits.
+ :param scopes: Filter by scopes.
+ :param modifiers: Optional modifiers to apply.
+ :param limit: Limit the number of tools returned.
+ :return: Provider-specific tool collection (TToolCollection).
+ """
if slug is not None:
return self._get(user_id=user_id, tools=[slug], modifiers=modifiers)
return self._get(
diff --git a/python/composio/core/provider/__init__.py b/python/composio/core/provider/__init__.py
index 5878b088c..7d90f97b3 100644
--- a/python/composio/core/provider/__init__.py
+++ b/python/composio/core/provider/__init__.py
@@ -1,12 +1,12 @@
-import typing as t
+from __future__ import annotations
from .agentic import AgenticProvider, AgenticProviderExecuteFn
+from .base import TTool, TToolCollection
from .none_agentic import NonAgenticProvider
-TProvider = t.TypeVar("TProvider", bound=AgenticProvider | NonAgenticProvider)
-
__all__ = [
- "TProvider",
+ "TTool",
+ "TToolCollection",
"AgenticProvider",
"NonAgenticProvider",
"AgenticProviderExecuteFn",
diff --git a/python/composio/core/provider/agentic.py b/python/composio/core/provider/agentic.py
index 7ab3908bc..6cca07655 100644
--- a/python/composio/core/provider/agentic.py
+++ b/python/composio/core/provider/agentic.py
@@ -1,3 +1,5 @@
+from __future__ import annotations
+
import typing as t
from composio.client.types import Tool
@@ -20,15 +22,12 @@ class AgenticProviderExecuteFn(t.Protocol):
...
-class AgenticProvider(BaseProvider, t.Generic[TTool, TToolCollection]):
+class AgenticProvider(BaseProvider[TTool, TToolCollection]):
"""
Base class for all agentic providers. This class is not meant to be used
directly but rather to be extended by concrete provider implementations.
"""
- tool_type: t.Type[TTool]
- tool_collection_type: t.Type[TToolCollection]
-
def __init_subclass__(cls, name: str) -> None:
cls.name = name
diff --git a/python/composio/core/provider/base.py b/python/composio/core/provider/base.py
index 06d6d305d..ef0e80082 100644
--- a/python/composio/core/provider/base.py
+++ b/python/composio/core/provider/base.py
@@ -13,8 +13,8 @@ import typing_extensions as te
if t.TYPE_CHECKING:
from composio.core.models.tools import Modifiers, ToolExecutionResponse
-TTool = t.TypeVar("TTool", covariant=True)
-TToolCollection = t.TypeVar("TToolCollection", covariant=True)
+TTool = t.TypeVar("TTool")
+TToolCollection = t.TypeVar("TToolCollection")
class ExecuteToolFn(t.Protocol):
@@ -69,5 +69,5 @@ class BaseProvider(t.Generic[TTool, TToolCollection]):
"skip_defaults", self.__schema_skip_defaults__
)
- def set_execute_tool_fn(self, execute_tool_fn: ExecuteToolFn):
+ def set_execute_tool_fn(self, execute_tool_fn: ExecuteToolFn) -> None:
self.execute_tool = execute_tool_fn
diff --git a/python/composio/core/provider/none_agentic.py b/python/composio/core/provider/none_agentic.py
index 99897264e..16c99a967 100644
--- a/python/composio/core/provider/none_agentic.py
+++ b/python/composio/core/provider/none_agentic.py
@@ -6,7 +6,7 @@ from composio.client.types import Tool
from composio.core.provider.base import BaseProvider, TTool, TToolCollection
-class NonAgenticProvider(BaseProvider, t.Generic[TTool, TToolCollection]):
+class NonAgenticProvider(BaseProvider[TTool, TToolCollection]):
"""
Base class for all non-agentic providers, such as `openai` This class is not
meant to be used directly, but rather to be extended by concrete implementations
diff --git a/python/composio/sdk.py b/python/composio/sdk.py
index f1eb65b3e..22d8b5ffd 100644
--- a/python/composio/sdk.py
+++ b/python/composio/sdk.py
@@ -17,8 +17,13 @@ from composio.core.models import (
)
from composio.core.models.base import allow_tracking
from composio.core.models.mcp import MCP
-from composio.core.provider import TProvider
-from composio.core.provider._openai import OpenAIProvider
+from composio.core.provider import TTool, TToolCollection
+from composio.core.provider._openai import (
+ OpenAIProvider,
+ OpenAITool,
+ OpenAIToolCollection,
+)
+from composio.core.provider.base import BaseProvider
from composio.core.types import ToolkitVersionParam
from composio.utils.logging import WithLogger
from composio.utils.toolkit_version import get_toolkit_versions
@@ -38,36 +43,57 @@ class SDKConfig(te.TypedDict):
auto_upload_download_files: te.NotRequired[bool]
-# class ExperimentalNamespace:
-# """Namespace for experimental Composio features."""
+class Composio(t.Generic[TTool, TToolCollection], WithLogger):
+ """
+ Composio SDK for Python.
-# def __init__(self, tool_router: ToolRouter):
-# """
-# Initialize experimental namespace.
+ Generic parameters:
+ TTool: The individual tool type returned by the provider (e.g., ChatCompletionToolParam for OpenAI).
+ TToolCollection: The collection type returned by get_tools (e.g., list[ChatCompletionToolParam]).
-# :param tool_router: Experimental ToolRouter instance
-# """
-# self.tool_router = tool_router
+ The generic types are automatically inferred from the provider passed to __init__.
+ When no provider is passed, defaults to OpenAI types.
+ Examples:
+ # Implicit type inference - recommended
+ composio = Composio(provider=OpenAIProvider()) # Composio[OpenAITool, list[OpenAITool]]
+ composio = Composio(provider=AnthropicProvider()) # Composio[ToolParam, list[ToolParam]]
+ composio = Composio() # Composio[OpenAITool, list[OpenAITool]] (default)
-class Composio(t.Generic[TProvider], WithLogger):
- """
- Composio SDK for Python.
+ # Custom provider - types are inferred automatically
+ composio = Composio(provider=MyCustomProvider()) # Composio[MyTool, list[MyTool]]
"""
- tools: Tools[TProvider]
- tool_router: ToolRouter[TProvider]
- # experimental: ExperimentalNamespace
+ tools: "Tools[TTool, TToolCollection]"
+ tool_router: "ToolRouter[TTool, TToolCollection]"
+
+ @t.overload
+ def __init__(
+ self: "Composio[OpenAITool, OpenAIToolCollection]",
+ provider: None = None,
+ **kwargs: te.Unpack[SDKConfig],
+ ) -> None:
+ """Initialize with default OpenAI provider."""
+ ...
+
+ @t.overload
+ def __init__(
+ self,
+ provider: BaseProvider[TTool, TToolCollection],
+ **kwargs: te.Unpack[SDKConfig],
+ ) -> None:
+ """Initialize with an explicit provider. Types are inferred from the provider."""
+ ...
def __init__(
self,
- provider: TProvider = _DEFAULT_PROVIDER, # type: ignore
+ provider: t.Optional[BaseProvider[t.Any, t.Any]] = None,
**kwargs: te.Unpack[SDKConfig],
) -> None:
"""
Initialize the Composio SDK.
- :param provider: The provider to use for the SDK.
+ :param provider: The provider to use for the SDK. Defaults to OpenAIProvider.
:param environment: The environment to use for the SDK.
:param api_key: The API key to use for the SDK.
:param base_url: The base URL to use for the SDK.
@@ -84,22 +110,29 @@ class Composio(t.Generic[TProvider], WithLogger):
if not api_key:
raise exceptions.ApiKeyNotProvidedError()
+ # Use default provider if none provided
+ # Cast to BaseProvider[TTool, TToolCollection] for type consistency
+ actual_provider: BaseProvider[TTool, TToolCollection] = t.cast(
+ BaseProvider[TTool, TToolCollection],
+ provider if provider is not None else _DEFAULT_PROVIDER,
+ )
+
# Process toolkit versions with environment variable support
toolkit_versions = get_toolkit_versions(kwargs.get("toolkit_versions"))
allow_tracking.set(kwargs.get("allow_tracking", True))
self._client = HttpClient(
environment=kwargs.get("environment", "production"),
- provider=provider.name,
+ provider=actual_provider.name,
api_key=api_key,
base_url=kwargs.get("base_url"),
timeout=kwargs.get("timeout"),
max_retries=kwargs.get("max_retries", DEFAULT_MAX_RETRIES),
)
- self.provider = provider
+ self.provider = actual_provider
self.tools = Tools(
client=self._client,
- provider=self.provider,
+ provider=actual_provider,
file_download_dir=kwargs.get("file_download_dir"),
toolkit_versions=toolkit_versions,
auto_upload_download_files=kwargs.get("auto_upload_download_files", True),
@@ -114,12 +147,12 @@ class Composio(t.Generic[TProvider], WithLogger):
# initialize tool router methods
self.tool_router = ToolRouter(
client=self._client,
- provider=self.provider,
+ provider=actual_provider,
auto_upload_download_files=kwargs.get("auto_upload_download_files", True),
)
self.create = self.tool_router.create
self.use = self.tool_router.use
@property
- def client(self):
+ def client(self) -> HttpClient:
return self._client
diff --git a/python/config/mypy.ini b/python/config/mypy.ini
index f4c409d5d..cff500e3f 100644
--- a/python/config/mypy.ini
+++ b/python/config/mypy.ini
@@ -1,5 +1,8 @@
[mypy]
-exclude = ^(apps/composio/|utils/|\.nox/|.*/setup\.py|.*/build/|examples/|.*demo.*)
+; Exclude directories and files from type checking
+; - External provider type inference tests require those provider packages to be installed
+; The core test_type_inference.py and test_type_inference_custom_provider.py can be checked
+exclude = ^(apps/composio/|utils/|\.nox/|.*/setup\.py|.*/build/|examples/|.*demo.*|tests/test_type_inference_(?!custom_provider).*)
strict_optional=True
disable_error_code=var-annotated
@@ -33,4 +36,44 @@ ignore_missing_imports=true
ignore_missing_imports=true
[mypy-claude_agent_sdk.*]
+ignore_missing_imports=true
+
+[mypy-mcp.*]
+ignore_missing_imports=true
+
+[mypy-llama_index.*]
+ignore_missing_imports=true
+
+[mypy-agents.*]
+ignore_missing_imports=true
+
+; Composio provider packages (may not be installed)
+[mypy-composio_anthropic.*]
+ignore_missing_imports=true
+
+[mypy-composio_langchain.*]
+ignore_missing_imports=true
+
+[mypy-composio_langgraph.*]
+ignore_missing_imports=true
+
+[mypy-composio_llamaindex.*]
+ignore_missing_imports=true
+
+[mypy-composio_openai_agents.*]
+ignore_missing_imports=true
+
+[mypy-composio_crewai.*]
+ignore_missing_imports=true
+
+[mypy-composio_autogen.*]
+ignore_missing_imports=true
+
+[mypy-composio_google.*]
+ignore_missing_imports=true
+
+[mypy-composio_google_adk.*]
+ignore_missing_imports=true
+
+[mypy-composio_claude_agent_sdk.*]
ignore_missing_imports=true
\ No newline at end of file
diff --git a/python/noxfile.py b/python/noxfile.py
index 84bae1bb8..1e7615a5b 100644
--- a/python/noxfile.py
+++ b/python/noxfile.py
@@ -66,3 +66,53 @@ def fix(session: Session):
"""Fix linter issues"""
session.install("ruff")
session.run(*ruff, "check", "--fix", *modules_for_ruff)
+
+
+def type_inference(session: Session):
+ """Type check provider return type inference tests.
+
+ This session verifies that mypy correctly infers provider-specific return
+ types from `Composio.tools.get()` when using @overload signatures.
+
+ Unlike the `chk` session, this installs all provider packages so mypy can
+ resolve the provider types and verify the type inference works correctly.
+ """
+ # Install core SDK and mypy
+ session.install(".", "mypy==1.13.0", *type_stubs)
+
+ # Install all provider packages for type resolution
+ session.install(
+ "./providers/anthropic",
+ "./providers/autogen",
+ "./providers/claude_agent_sdk",
+ "./providers/crewai",
+ "./providers/gemini",
+ "./providers/google",
+ "./providers/google_adk",
+ "./providers/langchain",
+ "./providers/langgraph",
+ "./providers/llamaindex",
+ "./providers/openai",
+ "./providers/openai_agents",
+ )
+
+ # Run mypy on type inference test files
+ # Note: explicitly listed files are checked even if they match the exclude pattern in `mypy.ini`
+ session.run(
+ "mypy",
+ "--config-file",
+ "config/mypy.ini",
+ "tests/test_type_inference.py",
+ "tests/test_type_inference_anthropic.py",
+ "tests/test_type_inference_autogen.py",
+ "tests/test_type_inference_claude_agent_sdk.py",
+ "tests/test_type_inference_crewai.py",
+ "tests/test_type_inference_gemini.py",
+ "tests/test_type_inference_google.py",
+ "tests/test_type_inference_google_adk.py",
+ "tests/test_type_inference_langchain.py",
+ "tests/test_type_inference_langgraph.py",
+ "tests/test_type_inference_llamaindex.py",
+ "tests/test_type_inference_openai_agents.py",
+ )
diff --git a/python/providers/anthropic/pyproject.toml b/python/providers/anthropic/pyproject.toml
index 81751cc0e..1838927b6 100644
--- a/python/providers/anthropic/pyproject.toml
+++ b/python/providers/anthropic/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-anthropic"
-version = "0.11.0"
+version = "0.11.1"
description = "Use Composio to get an array of tools with your Anthropic LLMs."
readme = "README.md"
requires-python = ">=3.10,<4"
diff --git a/python/providers/anthropic/setup.py b/python/providers/anthropic/setup.py
index 6dfae2b60..3be25c8d6 100644
--- a/python/providers/anthropic/setup.py
+++ b/python/providers/anthropic/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_anthropic",
- version="0.11.0",
+ version="0.11.1",
author="Composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your Anthropic LLMs.",
diff --git a/python/providers/autogen/pyproject.toml b/python/providers/autogen/pyproject.toml
index f6e06b1d1..0bdce6897 100644
--- a/python/providers/autogen/pyproject.toml
+++ b/python/providers/autogen/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-autogen"
-version = "0.11.0"
+version = "0.11.1"
description = "Use Composio to get an array of tools with your autogen agent."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/autogen/setup.py b/python/providers/autogen/setup.py
index 6226319a6..9bea399d5 100644
--- a/python/providers/autogen/setup.py
+++ b/python/providers/autogen/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_autogen",
- version="0.11.0",
+ version="0.11.1",
author="Composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your Autogen agent.",
diff --git a/python/providers/claude_agent_sdk/pyproject.toml b/python/providers/claude_agent_sdk/pyproject.toml
index 194452391..4fed81bb4 100644
--- a/python/providers/claude_agent_sdk/pyproject.toml
+++ b/python/providers/claude_agent_sdk/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-claude-agent-sdk"
-version = "0.11.0"
+version = "0.11.1"
description = "Use Composio to get an array of tools with Claude Code Agents SDK."
readme = "README.md"
requires-python = ">=3.10,<4"
diff --git a/python/providers/claude_agent_sdk/setup.py b/python/providers/claude_agent_sdk/setup.py
index 28e030621..99dd2becf 100644
--- a/python/providers/claude_agent_sdk/setup.py
+++ b/python/providers/claude_agent_sdk/setup.py
@@ -8,7 +8,7 @@ from setuptools import find_packages, setup
setup(
name="composio_claude_agent_sdk",
- version="0.11.0",
+ version="0.11.1",
author="Composio",
author_email="[email protected]",
description="Use Composio to get array of tools for Claude Agent SDK",
diff --git a/python/providers/crewai/pyproject.toml b/python/providers/crewai/pyproject.toml
index 35e81d5a1..4f4739e13 100644
--- a/python/providers/crewai/pyproject.toml
+++ b/python/providers/crewai/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-crewai"
-version = "0.11.0"
+version = "0.11.1"
description = "Use Composio to get an array of tools with your CrewAI agent."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/crewai/setup.py b/python/providers/crewai/setup.py
index 39aefa824..cc75cb119 100644
--- a/python/providers/crewai/setup.py
+++ b/python/providers/crewai/setup.py
@@ -6,7 +6,7 @@ from setuptools import setup
setup(
name="composio_crewai",
- version="0.11.0",
+ version="0.11.1",
author="Composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your CrewAI agent.",
diff --git a/python/providers/gemini/pyproject.toml b/python/providers/gemini/pyproject.toml
index 3656ce42a..e0422c177 100644
--- a/python/providers/gemini/pyproject.toml
+++ b/python/providers/gemini/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-gemini"
-version = "0.11.0"
+version = "0.11.1"
description = "Use Composio to get an array of tools with your Gemini agent."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/gemini/setup.py b/python/providers/gemini/setup.py
index 046e8a69f..786cf10dd 100644
--- a/python/providers/gemini/setup.py
+++ b/python/providers/gemini/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_gemini",
- version="0.11.0",
+ version="0.11.1",
author="Composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your Gemini agent.",
diff --git a/python/providers/google/pyproject.toml b/python/providers/google/pyproject.toml
index 8009ff559..cdacf2992 100644
--- a/python/providers/google/pyproject.toml
+++ b/python/providers/google/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-google"
-version = "0.11.0"
+version = "0.11.1"
description = "Use Composio to get an array of tools with your Google AI Python Gemini model."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/google/setup.py b/python/providers/google/setup.py
index 45bbefaa6..30fd9b304 100644
--- a/python/providers/google/setup.py
+++ b/python/providers/google/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_google",
- version="0.11.0",
+ version="0.11.1",
author="Composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your Google AI Python Gemini model.",
diff --git a/python/providers/google_adk/pyproject.toml b/python/providers/google_adk/pyproject.toml
index 8d84f9bab..460860229 100644
--- a/python/providers/google_adk/pyproject.toml
+++ b/python/providers/google_adk/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-google-adk"
-version = "0.11.0"
+version = "0.11.1"
description = "Use Composio to get an array of tools with your Google AI Python Gemini model."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/google_adk/setup.py b/python/providers/google_adk/setup.py
index 31000af43..57aa5806c 100644
--- a/python/providers/google_adk/setup.py
+++ b/python/providers/google_adk/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_google_adk",
- version="0.11.0",
+ version="0.11.1",
author="Composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your Google AI Python Gemini model.",
diff --git a/python/providers/langchain/pyproject.toml b/python/providers/langchain/pyproject.toml
index 4de7e72eb..6bee42051 100644
--- a/python/providers/langchain/pyproject.toml
+++ b/python/providers/langchain/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-langchain"
-version = "0.11.0"
+version = "0.11.1"
description = "Use Composio to get an array of tools with your Langchain agent."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/langchain/setup.py b/python/providers/langchain/setup.py
index cb353ff7a..c450d6046 100644
--- a/python/providers/langchain/setup.py
+++ b/python/providers/langchain/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_langchain",
- version="0.11.0",
+ version="0.11.1",
author="composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your Langchain agent.",
diff --git a/python/providers/langgraph/pyproject.toml b/python/providers/langgraph/pyproject.toml
index 091aff6a2..fa0f23e12 100644
--- a/python/providers/langgraph/pyproject.toml
+++ b/python/providers/langgraph/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-langgraph"
-version = "0.11.0"
+version = "0.11.1"
description = "Use Composio to get array of tools with LangGraph Agent Workflows."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/langgraph/setup.py b/python/providers/langgraph/setup.py
index 862e4c2ce..4c9f43419 100644
--- a/python/providers/langgraph/setup.py
+++ b/python/providers/langgraph/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_langgraph",
- version="0.11.0",
+ version="0.11.1",
author="composio",
author_email="[email protected]",
description="Use Composio to get array of tools with LangGraph Agent Workflows",
diff --git a/python/providers/llamaindex/pyproject.toml b/python/providers/llamaindex/pyproject.toml
index 9d7b10f2e..fdc8e51be 100644
--- a/python/providers/llamaindex/pyproject.toml
+++ b/python/providers/llamaindex/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-llamaindex"
-version = "0.11.0"
+version = "0.11.1"
description = "Use Composio to get array of tools with LlamaIndex Agent Workflows."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/llamaindex/setup.py b/python/providers/llamaindex/setup.py
index f72bdab5e..d3265b776 100644
--- a/python/providers/llamaindex/setup.py
+++ b/python/providers/llamaindex/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_llamaindex",
- version="0.11.0",
+ version="0.11.1",
author="composio",
author_email="[email protected]",
description="Use Composio to get array of tools with LlamaIndex Agent Workflows",
diff --git a/python/providers/openai/pyproject.toml b/python/providers/openai/pyproject.toml
index 3ccd8bd80..782796159 100644
--- a/python/providers/openai/pyproject.toml
+++ b/python/providers/openai/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-openai"
-version = "0.11.0"
+version = "0.11.1"
description = "Use Composio to get an array of tools with your OpenAI Function Call."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/openai/setup.py b/python/providers/openai/setup.py
index 966ca816c..531cf3b1e 100644
--- a/python/providers/openai/setup.py
+++ b/python/providers/openai/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_openai",
- version="0.11.0",
+ version="0.11.1",
author="Composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your OpenAI Function Call.",
diff --git a/python/providers/openai_agents/pyproject.toml b/python/providers/openai_agents/pyproject.toml
index 5c689ded8..8ad1cde50 100644
--- a/python/providers/openai_agents/pyproject.toml
+++ b/python/providers/openai_agents/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-openai-agents"
-version = "0.11.0"
+version = "0.11.1"
description = "Use Composio to get array of strongly typed tools for OpenAI Agents"
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/openai_agents/setup.py b/python/providers/openai_agents/setup.py
index e8be29ced..6cc3a424d 100644
--- a/python/providers/openai_agents/setup.py
+++ b/python/providers/openai_agents/setup.py
@@ -8,7 +8,7 @@ from setuptools import find_packages, setup
setup(
name="composio_openai_agents",
- version="0.11.0",
+ version="0.11.1",
author="Composio",
author_email="[email protected]",
description="Use Composio to get array of strongly typed tools for OpenAI Agents",
diff --git a/python/pyproject.toml b/python/pyproject.toml
index ace3ad98f..86118bfb2 100644
--- a/python/pyproject.toml
+++ b/python/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio"
-version = "0.11.0"
+version = "0.11.1"
description = "SDK for integrating Composio with your applications."
readme = "README.md"
requires-python = ">=3.10,<4"
diff --git a/python/pytest.ini b/python/pytest.ini
index b1a00fa9d..0ff9611ec 100644
--- a/python/pytest.ini
+++ b/python/pytest.ini
@@ -3,7 +3,7 @@ testpaths = tests
python_files = test_*.py
python_classes = Test*
python_functions = test_*
-addopts = -v --tb=short
+addopts = -v --tb=short --ignore-glob=tests/test_type_inference*.py
markers =
slow: marks tests as slow (deselect with '-m "not slow"')
integration: marks tests as integration tests
diff --git a/python/tests/test_type_inference.py b/python/tests/test_type_inference.py
new file mode 100644
index 000000000..ac46e1c4f
--- /dev/null
+++ b/python/tests/test_type_inference.py
@@ -0,0 +1,116 @@
+"""
+Type inference verification tests for the Composio SDK.
+
+This file verifies that type checkers (mypy) correctly infer
+provider-specific return types from `Composio.tools.get()`.
+
+**This file is NOT executed at runtime.** It is analyzed statically by type
+checkers to verify that type inference works correctly.
+
+Run: mypy tests/test_type_inference.py
+
+Requirements:
+ - composio (core SDK)
+ - openai (for type stubs)
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from composio import Composio
+from composio.core.provider._openai import (
+ OpenAIProvider,
+ OpenAITool,
+ OpenAIToolCollection,
+)
+from composio.core.provider._openai_responses import (
+ OpenAIResponsesProvider,
+ ResponsesTool,
+ ResponsesToolCollection,
+)
+
+if TYPE_CHECKING:
+ from typing_extensions import assert_type
+
+ from openai.types.chat.chat_completion_tool_param import ChatCompletionToolParam
+
+
+def test_openai_provider_explicit() -> None:
+ """Verify OpenAI provider with explicit type returns list[ChatCompletionToolParam]."""
+ composio: Composio[OpenAITool, OpenAIToolCollection] = Composio(
+ provider=OpenAIProvider()
+ )
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Type checker should infer: list[ChatCompletionToolParam]
+ if TYPE_CHECKING:
+ assert_type(tools, list[ChatCompletionToolParam])
+
+
+def test_openai_provider_inferred() -> None:
+ """Verify OpenAI provider with inferred type returns list[ChatCompletionToolParam]."""
+ composio = Composio(provider=OpenAIProvider())
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Type checker should infer: list[ChatCompletionToolParam]
+ if TYPE_CHECKING:
+ assert_type(tools, list[ChatCompletionToolParam])
+
+
+def test_default_provider() -> None:
+ """Verify default provider (OpenAI) returns list[ChatCompletionToolParam]."""
+ # Default provider is OpenAIProvider
+ composio = Composio()
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Type checker should infer: list[ChatCompletionToolParam]
+ if TYPE_CHECKING:
+ assert_type(tools, list[ChatCompletionToolParam])
+
+
+def test_openai_provider_slug_parameter() -> None:
+ """Verify slug parameter returns same type."""
+ composio = Composio(provider=OpenAIProvider())
+ tools = composio.tools.get(user_id="test", slug="GITHUB_CREATE_REPO")
+
+ if TYPE_CHECKING:
+ assert_type(tools, list[ChatCompletionToolParam])
+
+
+def test_openai_provider_tools_parameter() -> None:
+ """Verify tools parameter returns same type."""
+ composio = Composio(provider=OpenAIProvider())
+ tools = composio.tools.get(user_id="test", tools=["GITHUB_CREATE_REPO"])
+
+ if TYPE_CHECKING:
+ assert_type(tools, list[ChatCompletionToolParam])
+
+
+def test_openai_provider_search_parameter() -> None:
+ """Verify search parameter returns same type."""
+ composio = Composio(provider=OpenAIProvider())
+ tools = composio.tools.get(user_id="test", search="github")
+
+ if TYPE_CHECKING:
+ assert_type(tools, list[ChatCompletionToolParam])
+
+
+def test_openai_responses_provider() -> None:
+ """Verify OpenAI Responses provider returns list[dict]."""
+ if TYPE_CHECKING:
+ composio = Composio(provider=OpenAIResponsesProvider())
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Type checker should infer: list[Dict[str, Any]]
+ # Note: ResponsesTool is typed as Dict[str, Any]
+ assert_type(tools, list[dict[str, Any]])
+
+
+def test_openai_responses_provider_explicit() -> None:
+ """Verify OpenAI Responses provider with explicit generic types."""
+ if TYPE_CHECKING:
+ composio: Composio[ResponsesTool, ResponsesToolCollection] = Composio(
+ provider=OpenAIResponsesProvider()
+ )
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ assert_type(tools, list[dict[str, Any]])
diff --git a/python/tests/test_type_inference_anthropic.py b/python/tests/test_type_inference_anthropic.py
new file mode 100644
index 000000000..40a118d6b
--- /dev/null
+++ b/python/tests/test_type_inference_anthropic.py
@@ -0,0 +1,85 @@
+"""
+Type inference verification tests for Anthropic provider.
+
+This file verifies that type checkers correctly infer `list[ToolParam]`
+when using the Anthropic provider with Composio.
+
+**This file is NOT executed at runtime.** It is analyzed statically by type
+checkers to verify that type inference works correctly.
+
+Run: mypy tests/test_type_inference_anthropic.py
+
+Requirements:
+ - composio (core SDK)
+ - composio-anthropic
+ - anthropic
+"""
+
+from typing import TYPE_CHECKING
+
+from composio import Composio
+
+if TYPE_CHECKING:
+ from typing_extensions import assert_type
+
+ from anthropic.types.tool_param import ToolParam
+
+ from composio_anthropic import AnthropicProvider
+
+
+def test_anthropic_provider_toolkits() -> None:
+ """Verify Anthropic provider returns list[ToolParam] for toolkits query."""
+ if TYPE_CHECKING:
+ composio: Composio[ToolParam, list[ToolParam]] = Composio(
+ provider=AnthropicProvider()
+ )
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Type checker should infer: list[ToolParam]
+ assert_type(tools, list[ToolParam])
+
+
+def test_anthropic_provider_slug() -> None:
+ """Verify Anthropic provider returns list[ToolParam] for slug query."""
+ if TYPE_CHECKING:
+ composio: Composio[ToolParam, list[ToolParam]] = Composio(
+ provider=AnthropicProvider()
+ )
+ tools = composio.tools.get(user_id="test", slug="GITHUB_CREATE_REPO")
+
+ assert_type(tools, list[ToolParam])
+
+
+def test_anthropic_provider_tools_list() -> None:
+ """Verify Anthropic provider returns list[ToolParam] for tools list query."""
+ if TYPE_CHECKING:
+ composio: Composio[ToolParam, list[ToolParam]] = Composio(
+ provider=AnthropicProvider()
+ )
+ tools = composio.tools.get(
+ user_id="test",
+ tools=["GITHUB_CREATE_REPO", "GITHUB_GET_USER"],
+ )
+
+ assert_type(tools, list[ToolParam])
+
+
+def test_anthropic_provider_search() -> None:
+ """Verify Anthropic provider returns list[ToolParam] for search query."""
+ if TYPE_CHECKING:
+ composio: Composio[ToolParam, list[ToolParam]] = Composio(
+ provider=AnthropicProvider()
+ )
+ tools = composio.tools.get(user_id="test", search="github repository")
+
+ assert_type(tools, list[ToolParam])
+
+
+def test_anthropic_provider_inferred() -> None:
+ """Verify Anthropic provider type is correctly inferred without explicit annotation."""
+ if TYPE_CHECKING:
+ composio = Composio(provider=AnthropicProvider())
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Should infer list[ToolParam] from provider type
+ assert_type(tools, list[ToolParam])
diff --git a/python/tests/test_type_inference_autogen.py b/python/tests/test_type_inference_autogen.py
new file mode 100644
index 000000000..046c639cc
--- /dev/null
+++ b/python/tests/test_type_inference_autogen.py
@@ -0,0 +1,85 @@
+"""
+Type inference verification tests for Autogen provider.
+
+This file verifies that type checkers correctly infer `list[FunctionTool]`
+when using the Autogen provider with Composio.
+
+**This file is NOT executed at runtime.** It is analyzed statically by type
+checkers to verify that type inference works correctly.
+
+Run: mypy tests/test_type_inference_autogen.py
+
+Requirements:
+ - composio (core SDK)
+ - composio-autogen
+ - autogen-core
+"""
+
+from typing import TYPE_CHECKING
+
+from composio import Composio
+
+if TYPE_CHECKING:
+ from typing_extensions import assert_type
+
+ from autogen_core.tools import FunctionTool
+
+ from composio_autogen import AutogenProvider
+
+
+def test_autogen_provider_toolkits() -> None:
+ """Verify Autogen provider returns list[FunctionTool] for toolkits query."""
+ if TYPE_CHECKING:
+ composio: Composio[FunctionTool, list[FunctionTool]] = Composio(
+ provider=AutogenProvider()
+ )
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Type checker should infer: list[FunctionTool]
+ assert_type(tools, list[FunctionTool])
+
+
+def test_autogen_provider_slug() -> None:
+ """Verify Autogen provider returns list[FunctionTool] for slug query."""
+ if TYPE_CHECKING:
+ composio: Composio[FunctionTool, list[FunctionTool]] = Composio(
+ provider=AutogenProvider()
+ )
+ tools = composio.tools.get(user_id="test", slug="GITHUB_CREATE_REPO")
+
+ assert_type(tools, list[FunctionTool])
+
+
+def test_autogen_provider_tools_list() -> None:
+ """Verify Autogen provider returns list[FunctionTool] for tools list query."""
+ if TYPE_CHECKING:
+ composio: Composio[FunctionTool, list[FunctionTool]] = Composio(
+ provider=AutogenProvider()
+ )
+ tools = composio.tools.get(
+ user_id="test",
+ tools=["GITHUB_CREATE_REPO", "GITHUB_GET_USER"],
+ )
+
+ assert_type(tools, list[FunctionTool])
+
+
+def test_autogen_provider_search() -> None:
+ """Verify Autogen provider returns list[FunctionTool] for search query."""
+ if TYPE_CHECKING:
+ composio: Composio[FunctionTool, list[FunctionTool]] = Composio(
+ provider=AutogenProvider()
+ )
+ tools = composio.tools.get(user_id="test", search="github repository")
+
+ assert_type(tools, list[FunctionTool])
+
+
+def test_autogen_provider_inferred() -> None:
+ """Verify Autogen provider type is correctly inferred without explicit annotation."""
+ if TYPE_CHECKING:
+ composio = Composio(provider=AutogenProvider())
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Should infer list[FunctionTool] from provider type
+ assert_type(tools, list[FunctionTool])
diff --git a/python/tests/test_type_inference_claude_agent_sdk.py b/python/tests/test_type_inference_claude_agent_sdk.py
new file mode 100644
index 000000000..4b712c4d7
--- /dev/null
+++ b/python/tests/test_type_inference_claude_agent_sdk.py
@@ -0,0 +1,85 @@
+"""
+Type inference verification tests for Claude Agent SDK provider.
+
+This file verifies that type checkers correctly infer `list[SdkMcpTool]`
+when using the Claude Agent SDK provider with Composio.
+
+**This file is NOT executed at runtime.** It is analyzed statically by type
+checkers to verify that type inference works correctly.
+
+Run: mypy tests/test_type_inference_claude_agent_sdk.py
+
+Requirements:
+ - composio (core SDK)
+ - composio-claude-agent-sdk
+ - claude-agent-sdk
+"""
+
+from typing import TYPE_CHECKING
+
+from composio import Composio
+
+if TYPE_CHECKING:
+ from typing_extensions import assert_type
+
+ from claude_agent_sdk import SdkMcpTool
+
+ from composio_claude_agent_sdk import ClaudeAgentSDKProvider
+
+
+def test_claude_agent_sdk_provider_toolkits() -> None:
+ """Verify Claude Agent SDK provider returns list[SdkMcpTool] for toolkits query."""
+ if TYPE_CHECKING:
+ composio: Composio[SdkMcpTool, list[SdkMcpTool]] = Composio(
+ provider=ClaudeAgentSDKProvider()
+ )
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Type checker should infer: list[SdkMcpTool]
+ assert_type(tools, list[SdkMcpTool])
+
+
+def test_claude_agent_sdk_provider_slug() -> None:
+ """Verify Claude Agent SDK provider returns list[SdkMcpTool] for slug query."""
+ if TYPE_CHECKING:
+ composio: Composio[SdkMcpTool, list[SdkMcpTool]] = Composio(
+ provider=ClaudeAgentSDKProvider()
+ )
+ tools = composio.tools.get(user_id="test", slug="GITHUB_CREATE_REPO")
+
+ assert_type(tools, list[SdkMcpTool])
+
+
+def test_claude_agent_sdk_provider_tools_list() -> None:
+ """Verify Claude Agent SDK provider returns list[SdkMcpTool] for tools list query."""
+ if TYPE_CHECKING:
+ composio: Composio[SdkMcpTool, list[SdkMcpTool]] = Composio(
+ provider=ClaudeAgentSDKProvider()
+ )
+ tools = composio.tools.get(
+ user_id="test",
+ tools=["GITHUB_CREATE_REPO", "GITHUB_GET_USER"],
+ )
+
+ assert_type(tools, list[SdkMcpTool])
+
+
+def test_claude_agent_sdk_provider_search() -> None:
+ """Verify Claude Agent SDK provider returns list[SdkMcpTool] for search query."""
+ if TYPE_CHECKING:
+ composio: Composio[SdkMcpTool, list[SdkMcpTool]] = Composio(
+ provider=ClaudeAgentSDKProvider()
+ )
+ tools = composio.tools.get(user_id="test", search="github repository")
+
+ assert_type(tools, list[SdkMcpTool])
+
+
+def test_claude_agent_sdk_provider_inferred() -> None:
+ """Verify Claude Agent SDK provider type is correctly inferred without explicit annotation."""
+ if TYPE_CHECKING:
+ composio = Composio(provider=ClaudeAgentSDKProvider())
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Should infer list[SdkMcpTool] from provider type
+ assert_type(tools, list[SdkMcpTool])
diff --git a/python/tests/test_type_inference_crewai.py b/python/tests/test_type_inference_crewai.py
new file mode 100644
index 000000000..48be5a871
--- /dev/null
+++ b/python/tests/test_type_inference_crewai.py
@@ -0,0 +1,85 @@
+"""
+Type inference verification tests for CrewAI provider.
+
+This file verifies that type checkers correctly infer `list[BaseTool]`
+when using the CrewAI provider with Composio.
+
+**This file is NOT executed at runtime.** It is analyzed statically by type
+checkers to verify that type inference works correctly.
+
+Run: mypy tests/test_type_inference_crewai.py
+
+Requirements:
+ - composio (core SDK)
+ - composio-crewai
+ - crewai
+"""
+
+from typing import TYPE_CHECKING
+
+from composio import Composio
+
+if TYPE_CHECKING:
+ from typing_extensions import assert_type
+
+ from crewai.tools import BaseTool
+
+ from composio_crewai import CrewAIProvider
+
+
+def test_crewai_provider_toolkits() -> None:
+ """Verify CrewAI provider returns list[BaseTool] for toolkits query."""
+ if TYPE_CHECKING:
+ composio: Composio[BaseTool, list[BaseTool]] = Composio(
+ provider=CrewAIProvider()
+ )
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Type checker should infer: list[BaseTool]
+ assert_type(tools, list[BaseTool])
+
+
+def test_crewai_provider_slug() -> None:
+ """Verify CrewAI provider returns list[BaseTool] for slug query."""
+ if TYPE_CHECKING:
+ composio: Composio[BaseTool, list[BaseTool]] = Composio(
+ provider=CrewAIProvider()
+ )
+ tools = composio.tools.get(user_id="test", slug="GITHUB_CREATE_REPO")
+
+ assert_type(tools, list[BaseTool])
+
+
+def test_crewai_provider_tools_list() -> None:
+ """Verify CrewAI provider returns list[BaseTool] for tools list query."""
+ if TYPE_CHECKING:
+ composio: Composio[BaseTool, list[BaseTool]] = Composio(
+ provider=CrewAIProvider()
+ )
+ tools = composio.tools.get(
+ user_id="test",
+ tools=["GITHUB_CREATE_REPO", "GITHUB_GET_USER"],
+ )
+
+ assert_type(tools, list[BaseTool])
+
+
+def test_crewai_provider_search() -> None:
+ """Verify CrewAI provider returns list[BaseTool] for search query."""
+ if TYPE_CHECKING:
+ composio: Composio[BaseTool, list[BaseTool]] = Composio(
+ provider=CrewAIProvider()
+ )
+ tools = composio.tools.get(user_id="test", search="github repository")
+
+ assert_type(tools, list[BaseTool])
+
+
+def test_crewai_provider_inferred() -> None:
+ """Verify CrewAI provider type is correctly inferred without explicit annotation."""
+ if TYPE_CHECKING:
+ composio = Composio(provider=CrewAIProvider())
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Should infer list[BaseTool] from provider type
+ assert_type(tools, list[BaseTool])
diff --git a/python/tests/test_type_inference_custom_provider.py b/python/tests/test_type_inference_custom_provider.py
new file mode 100644
index 000000000..07b030df8
--- /dev/null
+++ b/python/tests/test_type_inference_custom_provider.py
@@ -0,0 +1,112 @@
+"""
+Type inference verification for CUSTOM providers.
+
+This test proves the new generic approach works for user-defined providers.
+This is the KEY BENEFIT of the two-parameter generic approach over @overload:
+custom providers get proper type inference without requiring any changes
+to the Composio SDK.
+
+Run: mypy tests/test_type_inference_custom_provider.py
+
+Requirements:
+ - composio (core SDK)
+"""
+
+from typing import TYPE_CHECKING, Sequence
+import typing as t
+
+from composio import Composio
+from composio.client.types import Tool
+from composio.core.provider.none_agentic import NonAgenticProvider
+
+if TYPE_CHECKING:
+ from typing_extensions import assert_type
+
+# ============================================
+# Custom provider defined by a hypothetical user
+# ============================================
+
+
+class MyCustomTool(t.TypedDict):
+ """User's custom tool format."""
+
+ name: str
+ description: str
+ parameters: dict
+
+
+MyCustomToolCollection = t.List[MyCustomTool]
+
+
+class MyCustomProvider(
+ NonAgenticProvider[MyCustomTool, MyCustomToolCollection], name="my-custom"
+):
+ """User-defined custom provider."""
+
+ def wrap_tool(self, tool: Tool) -> MyCustomTool:
+ return MyCustomTool(
+ name=tool.slug,
+ description=tool.description or "",
+ parameters=tool.input_parameters or {},
+ )
+
+ def wrap_tools(self, tools: Sequence[Tool]) -> MyCustomToolCollection:
+ return [self.wrap_tool(tool) for tool in tools]
+
+
+# ============================================
+# Type inference tests
+# ============================================
+
+
+def test_custom_provider_type_inference() -> None:
+ """Custom provider correctly infers return type.
+
+ THIS IS THE KEY TEST: Custom providers get proper type inference
+ without requiring any changes to the Composio SDK.
+ """
+ composio = Composio(provider=MyCustomProvider())
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ if TYPE_CHECKING:
+ # The return type should be inferred as list[MyCustomTool]
+ assert_type(tools, list[MyCustomTool])
+
+
+def test_custom_provider_explicit_annotation() -> None:
+ """Custom provider works with explicit type annotation."""
+ composio: Composio[MyCustomTool, MyCustomToolCollection] = Composio(
+ provider=MyCustomProvider()
+ )
+ tools = composio.tools.get(user_id="test", slug="GITHUB_CREATE_REPO")
+
+ if TYPE_CHECKING:
+ assert_type(tools, list[MyCustomTool])
+
+
+def test_custom_provider_all_parameters() -> None:
+ """Custom provider type inference works with all get() parameters."""
+ composio = Composio(provider=MyCustomProvider())
+
+ # Test different parameter combinations
+ tools_by_toolkit = composio.tools.get(user_id="test", toolkits=["github"])
+ tools_by_slug = composio.tools.get(user_id="test", slug="GITHUB_CREATE_REPO")
+ tools_by_search = composio.tools.get(user_id="test", search="repository")
+ tools_by_list = composio.tools.get(user_id="test", tools=["GITHUB_CREATE_REPO"])
+
+ if TYPE_CHECKING:
+ assert_type(tools_by_toolkit, list[MyCustomTool])
+ assert_type(tools_by_slug, list[MyCustomTool])
+ assert_type(tools_by_search, list[MyCustomTool])
+ assert_type(tools_by_list, list[MyCustomTool])
+
+
+def test_custom_provider_tools_attribute_type() -> None:
+ """Verify the tools attribute has correct type."""
+ from composio.core.models.tools import Tools
+
+ composio = Composio(provider=MyCustomProvider())
+
+ if TYPE_CHECKING:
+ # The tools attribute should be Tools[MyCustomTool, list[MyCustomTool]]
+ assert_type(composio.tools, Tools[MyCustomTool, list[MyCustomTool]])
diff --git a/python/tests/test_type_inference_gemini.py b/python/tests/test_type_inference_gemini.py
new file mode 100644
index 000000000..0fa300e06
--- /dev/null
+++ b/python/tests/test_type_inference_gemini.py
@@ -0,0 +1,82 @@
+"""
+Type inference verification tests for Gemini provider.
+
+This file verifies that type checkers correctly infer `list[Any]`
+when using the Gemini provider with Composio.
+
+**This file is NOT executed at runtime.** It is analyzed statically by type
+checkers to verify that type inference works correctly.
+
+Run: mypy tests/test_type_inference_gemini.py
+
+Requirements:
+ - composio (core SDK)
+ - composio-gemini
+"""
+
+from typing import TYPE_CHECKING, Any, Callable
+
+from composio import Composio
+
+if TYPE_CHECKING:
+ from typing_extensions import assert_type
+
+ from composio_gemini import GeminiProvider
+
+
+def test_gemini_provider_toolkits() -> None:
+ """Verify Gemini provider returns list[Callable[..., Any]] for toolkits query."""
+ if TYPE_CHECKING:
+ composio: Composio[Callable[..., Any], list[Callable[..., Any]]] = Composio(
+ provider=GeminiProvider()
+ )
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Type checker should infer: list[Callable[..., Any]]
+ assert_type(tools, list[Callable[..., Any]])
+
+
+def test_gemini_provider_slug() -> None:
+ """Verify Gemini provider returns list[Callable[..., Any]] for slug query."""
+ if TYPE_CHECKING:
+ composio: Composio[Callable[..., Any], list[Callable[..., Any]]] = Composio(
+ provider=GeminiProvider()
+ )
+ tools = composio.tools.get(user_id="test", slug="GITHUB_CREATE_REPO")
+
+ assert_type(tools, list[Callable[..., Any]])
+
+
+def test_gemini_provider_tools_list() -> None:
+ """Verify Gemini provider returns list[Callable[..., Any]] for tools list query."""
+ if TYPE_CHECKING:
+ composio: Composio[Callable[..., Any], list[Callable[..., Any]]] = Composio(
+ provider=GeminiProvider()
+ )
+ tools = composio.tools.get(
+ user_id="test",
+ tools=["GITHUB_CREATE_REPO", "GITHUB_GET_USER"],
+ )
+
+ assert_type(tools, list[Callable[..., Any]])
+
+
+def test_gemini_provider_search() -> None:
+ """Verify Gemini provider returns list[Callable[..., Any]] for search query."""
+ if TYPE_CHECKING:
+ composio: Composio[Callable[..., Any], list[Callable[..., Any]]] = Composio(
+ provider=GeminiProvider()
+ )
+ tools = composio.tools.get(user_id="test", search="github repository")
+
+ assert_type(tools, list[Callable[..., Any]])
+
+
+def test_gemini_provider_inferred() -> None:
+ """Verify Gemini provider type is correctly inferred without explicit annotation."""
+ if TYPE_CHECKING:
+ composio = Composio(provider=GeminiProvider())
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Should infer list[Callable[..., Any]] from provider type
+ assert_type(tools, list[Callable[..., Any]])
diff --git a/python/tests/test_type_inference_google.py b/python/tests/test_type_inference_google.py
new file mode 100644
index 000000000..bd85bf4ec
--- /dev/null
+++ b/python/tests/test_type_inference_google.py
@@ -0,0 +1,85 @@
+"""
+Type inference verification tests for Google (Vertex AI) provider.
+
+This file verifies that type checkers correctly infer `list[FunctionDeclaration]`
+when using the Google provider with Composio.
+
+**This file is NOT executed at runtime.** It is analyzed statically by type
+checkers to verify that type inference works correctly.
+
+Run: mypy tests/test_type_inference_google.py
+
+Requirements:
+ - composio (core SDK)
+ - composio-google
+ - google-cloud-aiplatform
+"""
+
+from typing import TYPE_CHECKING
+
+from composio import Composio
+
+if TYPE_CHECKING:
+ from typing_extensions import assert_type
+
+ from vertexai.generative_models import FunctionDeclaration
+
+ from composio_google import GoogleProvider
+
+
+def test_google_provider_toolkits() -> None:
+ """Verify Google provider returns list[FunctionDeclaration] for toolkits query."""
+ if TYPE_CHECKING:
+ composio: Composio[FunctionDeclaration, list[FunctionDeclaration]] = Composio(
+ provider=GoogleProvider()
+ )
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Type checker should infer: list[FunctionDeclaration]
+ assert_type(tools, list[FunctionDeclaration])
+
+
+def test_google_provider_slug() -> None:
+ """Verify Google provider returns list[FunctionDeclaration] for slug query."""
+ if TYPE_CHECKING:
+ composio: Composio[FunctionDeclaration, list[FunctionDeclaration]] = Composio(
+ provider=GoogleProvider()
+ )
+ tools = composio.tools.get(user_id="test", slug="GITHUB_CREATE_REPO")
+
+ assert_type(tools, list[FunctionDeclaration])
+
+
+def test_google_provider_tools_list() -> None:
+ """Verify Google provider returns list[FunctionDeclaration] for tools list query."""
+ if TYPE_CHECKING:
+ composio: Composio[FunctionDeclaration, list[FunctionDeclaration]] = Composio(
+ provider=GoogleProvider()
+ )
+ tools = composio.tools.get(
+ user_id="test",
+ tools=["GITHUB_CREATE_REPO", "GITHUB_GET_USER"],
+ )
+
+ assert_type(tools, list[FunctionDeclaration])
+
+
+def test_google_provider_search() -> None:
+ """Verify Google provider returns list[FunctionDeclaration] for search query."""
+ if TYPE_CHECKING:
+ composio: Composio[FunctionDeclaration, list[FunctionDeclaration]] = Composio(
+ provider=GoogleProvider()
+ )
+ tools = composio.tools.get(user_id="test", search="github repository")
+
+ assert_type(tools, list[FunctionDeclaration])
+
+
+def test_google_provider_inferred() -> None:
+ """Verify Google provider type is correctly inferred without explicit annotation."""
+ if TYPE_CHECKING:
+ composio = Composio(provider=GoogleProvider())
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Should infer list[FunctionDeclaration] from provider type
+ assert_type(tools, list[FunctionDeclaration])
diff --git a/python/tests/test_type_inference_google_adk.py b/python/tests/test_type_inference_google_adk.py
new file mode 100644
index 000000000..0098facee
--- /dev/null
+++ b/python/tests/test_type_inference_google_adk.py
@@ -0,0 +1,85 @@
+"""
+Type inference verification tests for Google ADK provider.
+
+This file verifies that type checkers correctly infer `list[FunctionTool]`
+when using the Google ADK provider with Composio.
+
+**This file is NOT executed at runtime.** It is analyzed statically by type
+checkers to verify that type inference works correctly.
+
+Run: mypy tests/test_type_inference_google_adk.py
+
+Requirements:
+ - composio (core SDK)
+ - composio-google-adk
+ - google-adk
+"""
+
+from typing import TYPE_CHECKING
+
+from composio import Composio
+
+if TYPE_CHECKING:
+ from typing_extensions import assert_type
+
+ from google.adk.tools import FunctionTool
+
+ from composio_google_adk import GoogleAdkProvider
+
+
+def test_google_adk_provider_toolkits() -> None:
+ """Verify Google ADK provider returns list[FunctionTool] for toolkits query."""
+ if TYPE_CHECKING:
+ composio: Composio[FunctionTool, list[FunctionTool]] = Composio(
+ provider=GoogleAdkProvider()
+ )
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Type checker should infer: list[FunctionTool]
+ assert_type(tools, list[FunctionTool])
+
+
+def test_google_adk_provider_slug() -> None:
+ """Verify Google ADK provider returns list[FunctionTool] for slug query."""
+ if TYPE_CHECKING:
+ composio: Composio[FunctionTool, list[FunctionTool]] = Composio(
+ provider=GoogleAdkProvider()
+ )
+ tools = composio.tools.get(user_id="test", slug="GITHUB_CREATE_REPO")
+
+ assert_type(tools, list[FunctionTool])
+
+
+def test_google_adk_provider_tools_list() -> None:
+ """Verify Google ADK provider returns list[FunctionTool] for tools list query."""
+ if TYPE_CHECKING:
+ composio: Composio[FunctionTool, list[FunctionTool]] = Composio(
+ provider=GoogleAdkProvider()
+ )
+ tools = composio.tools.get(
+ user_id="test",
+ tools=["GITHUB_CREATE_REPO", "GITHUB_GET_USER"],
+ )
+
+ assert_type(tools, list[FunctionTool])
+
+
+def test_google_adk_provider_search() -> None:
+ """Verify Google ADK provider returns list[FunctionTool] for search query."""
+ if TYPE_CHECKING:
+ composio: Composio[FunctionTool, list[FunctionTool]] = Composio(
+ provider=GoogleAdkProvider()
+ )
+ tools = composio.tools.get(user_id="test", search="github repository")
+
+ assert_type(tools, list[FunctionTool])
+
+
+def test_google_adk_provider_inferred() -> None:
+ """Verify Google ADK provider type is correctly inferred without explicit annotation."""
+ if TYPE_CHECKING:
+ composio = Composio(provider=GoogleAdkProvider())
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Should infer list[FunctionTool] from provider type
+ assert_type(tools, list[FunctionTool])
diff --git a/python/tests/test_type_inference_langchain.py b/python/tests/test_type_inference_langchain.py
new file mode 100644
index 000000000..b3948c07e
--- /dev/null
+++ b/python/tests/test_type_inference_langchain.py
@@ -0,0 +1,86 @@
+"""
+Type inference verification tests for LangChain provider.
+
+This file verifies that type checkers correctly infer `list[StructuredTool]`
+when using the LangChain provider with Composio.
+
+**This file is NOT executed at runtime.** It is analyzed statically by type
+checkers to verify that type inference works correctly.
+
+Run: mypy tests/test_type_inference_langchain.py
+
+Requirements:
+ - composio (core SDK)
+ - composio-langchain
+ - langchain-core
+"""
+
+from typing import TYPE_CHECKING
+
+from composio import Composio
+
+if TYPE_CHECKING:
+ from typing_extensions import assert_type
+
+ from composio_langchain.provider import StructuredTool
+
+ from composio_langchain import LangchainProvider
+
+
+def test_langchain_provider_toolkits() -> None:
+ """Verify LangChain provider returns list[StructuredTool] for toolkits query."""
+ if TYPE_CHECKING:
+ composio: Composio[StructuredTool, list[StructuredTool]] = Composio(
+ provider=LangchainProvider()
+ )
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Type checker should infer: list[StructuredTool]
+ assert_type(tools, list[StructuredTool])
+
+
+def test_langchain_provider_slug() -> None:
+ """Verify LangChain provider returns list[StructuredTool] for slug query."""
+ if TYPE_CHECKING:
+ composio: Composio[StructuredTool, list[StructuredTool]] = Composio(
+ provider=LangchainProvider()
+ )
+ tools = composio.tools.get(user_id="test", slug="GITHUB_CREATE_REPO")
+
+ assert_type(tools, list[StructuredTool])
+
+
+def test_langchain_provider_tools_list() -> None:
+ """Verify LangChain provider returns list[StructuredTool] for tools list query."""
+ if TYPE_CHECKING:
+ composio: Composio[StructuredTool, list[StructuredTool]] = Composio(
+ provider=LangchainProvider()
+ )
+ tools = composio.tools.get(
+ user_id="test",
+ tools=["GITHUB_CREATE_REPO", "GITHUB_GET_USER"],
+ )
+
+ assert_type(tools, list[StructuredTool])
+
+
+def test_langchain_provider_search() -> None:
+ """Verify LangChain provider returns list[StructuredTool] for search query."""
+ if TYPE_CHECKING:
+ composio: Composio[StructuredTool, list[StructuredTool]] = Composio(
+ provider=LangchainProvider()
+ )
+ tools = composio.tools.get(user_id="test", search="github repository")
+
+ assert_type(tools, list[StructuredTool])
+
+
+def test_langchain_provider_inferred() -> None:
+ """Verify LangChain provider type is correctly inferred without explicit annotation."""
+ if TYPE_CHECKING:
+ composio = Composio(provider=LangchainProvider())
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Should infer list[StructuredTool] from provider type
+ # Note: The provider's StructuredTool is a subclass of langchain_core's StructuredTool
+ assert_type(tools, list[StructuredTool])
diff --git a/python/tests/test_type_inference_langgraph.py b/python/tests/test_type_inference_langgraph.py
new file mode 100644
index 000000000..0fbf6aac1
--- /dev/null
+++ b/python/tests/test_type_inference_langgraph.py
@@ -0,0 +1,86 @@
+"""
+Type inference verification tests for LangGraph provider.
+
+This file verifies that type checkers correctly infer `list[StructuredTool]`
+when using the LangGraph provider with Composio.
+
+**This file is NOT executed at runtime.** It is analyzed statically by type
+checkers to verify that type inference works correctly.
+
+Run: mypy tests/test_type_inference_langgraph.py
+
+Requirements:
+ - composio (core SDK)
+ - composio-langgraph
+ - langchain-core
+"""
+
+from typing import TYPE_CHECKING
+
+from composio import Composio
+
+if TYPE_CHECKING:
+ from typing_extensions import assert_type
+
+ from composio_langgraph.provider import StructuredTool
+
+ from composio_langgraph import LanggraphProvider
+
+
+def test_langgraph_provider_toolkits() -> None:
+ """Verify LangGraph provider returns list[StructuredTool] for toolkits query."""
+ if TYPE_CHECKING:
+ composio: Composio[StructuredTool, list[StructuredTool]] = Composio(
+ provider=LanggraphProvider()
+ )
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Type checker should infer: list[StructuredTool]
+ assert_type(tools, list[StructuredTool])
+
+
+def test_langgraph_provider_slug() -> None:
+ """Verify LangGraph provider returns list[StructuredTool] for slug query."""
+ if TYPE_CHECKING:
+ composio: Composio[StructuredTool, list[StructuredTool]] = Composio(
+ provider=LanggraphProvider()
+ )
+ tools = composio.tools.get(user_id="test", slug="GITHUB_CREATE_REPO")
+
+ assert_type(tools, list[StructuredTool])
+
+
+def test_langgraph_provider_tools_list() -> None:
+ """Verify LangGraph provider returns list[StructuredTool] for tools list query."""
+ if TYPE_CHECKING:
+ composio: Composio[StructuredTool, list[StructuredTool]] = Composio(
+ provider=LanggraphProvider()
+ )
+ tools = composio.tools.get(
+ user_id="test",
+ tools=["GITHUB_CREATE_REPO", "GITHUB_GET_USER"],
+ )
+
+ assert_type(tools, list[StructuredTool])
+
+
+def test_langgraph_provider_search() -> None:
+ """Verify LangGraph provider returns list[StructuredTool] for search query."""
+ if TYPE_CHECKING:
+ composio: Composio[StructuredTool, list[StructuredTool]] = Composio(
+ provider=LanggraphProvider()
+ )
+ tools = composio.tools.get(user_id="test", search="github repository")
+
+ assert_type(tools, list[StructuredTool])
+
+
+def test_langgraph_provider_inferred() -> None:
+ """Verify LangGraph provider type is correctly inferred without explicit annotation."""
+ if TYPE_CHECKING:
+ composio = Composio(provider=LanggraphProvider())
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Should infer list[StructuredTool] from provider type
+ # Note: The provider's StructuredTool is a subclass of langchain_core's StructuredTool
+ assert_type(tools, list[StructuredTool])
diff --git a/python/tests/test_type_inference_llamaindex.py b/python/tests/test_type_inference_llamaindex.py
new file mode 100644
index 000000000..4e50f81d5
--- /dev/null
+++ b/python/tests/test_type_inference_llamaindex.py
@@ -0,0 +1,85 @@
+"""
+Type inference verification tests for LlamaIndex provider.
+
+This file verifies that type checkers correctly infer `list[FunctionTool]`
+when using the LlamaIndex provider with Composio.
+
+**This file is NOT executed at runtime.** It is analyzed statically by type
+checkers to verify that type inference works correctly.
+
+Run: mypy tests/test_type_inference_llamaindex.py
+
+Requirements:
+ - composio (core SDK)
+ - composio-llamaindex
+ - llama-index-core
+"""
+
+from typing import TYPE_CHECKING
+
+from composio import Composio
+
+if TYPE_CHECKING:
+ from typing_extensions import assert_type
+
+ from llama_index.core.tools import FunctionTool
+
+ from composio_llamaindex import LlamaIndexProvider
+
+
+def test_llamaindex_provider_toolkits() -> None:
+ """Verify LlamaIndex provider returns list[FunctionTool] for toolkits query."""
+ if TYPE_CHECKING:
+ composio: Composio[FunctionTool, list[FunctionTool]] = Composio(
+ provider=LlamaIndexProvider()
+ )
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Type checker should infer: list[FunctionTool]
+ assert_type(tools, list[FunctionTool])
+
+
+def test_llamaindex_provider_slug() -> None:
+ """Verify LlamaIndex provider returns list[FunctionTool] for slug query."""
+ if TYPE_CHECKING:
+ composio: Composio[FunctionTool, list[FunctionTool]] = Composio(
+ provider=LlamaIndexProvider()
+ )
+ tools = composio.tools.get(user_id="test", slug="GITHUB_CREATE_REPO")
+
+ assert_type(tools, list[FunctionTool])
+
+
+def test_llamaindex_provider_tools_list() -> None:
+ """Verify LlamaIndex provider returns list[FunctionTool] for tools list query."""
+ if TYPE_CHECKING:
+ composio: Composio[FunctionTool, list[FunctionTool]] = Composio(
+ provider=LlamaIndexProvider()
+ )
+ tools = composio.tools.get(
+ user_id="test",
+ tools=["GITHUB_CREATE_REPO", "GITHUB_GET_USER"],
+ )
+
+ assert_type(tools, list[FunctionTool])
+
+
+def test_llamaindex_provider_search() -> None:
+ """Verify LlamaIndex provider returns list[FunctionTool] for search query."""
+ if TYPE_CHECKING:
+ composio: Composio[FunctionTool, list[FunctionTool]] = Composio(
+ provider=LlamaIndexProvider()
+ )
+ tools = composio.tools.get(user_id="test", search="github repository")
+
+ assert_type(tools, list[FunctionTool])
+
+
+def test_llamaindex_provider_inferred() -> None:
+ """Verify LlamaIndex provider type is correctly inferred without explicit annotation."""
+ if TYPE_CHECKING:
+ composio = Composio(provider=LlamaIndexProvider())
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Should infer list[FunctionTool] from provider type
+ assert_type(tools, list[FunctionTool])
diff --git a/python/tests/test_type_inference_openai_agents.py b/python/tests/test_type_inference_openai_agents.py
new file mode 100644
index 000000000..fd146615a
--- /dev/null
+++ b/python/tests/test_type_inference_openai_agents.py
@@ -0,0 +1,85 @@
+"""
+Type inference verification tests for OpenAI Agents provider.
+
+This file verifies that type checkers correctly infer `list[FunctionTool]`
+when using the OpenAI Agents provider with Composio.
+
+**This file is NOT executed at runtime.** It is analyzed statically by type
+checkers to verify that type inference works correctly.
+
+Run: mypy tests/test_type_inference_openai_agents.py
+
+Requirements:
+ - composio (core SDK)
+ - composio-openai-agents
+ - openai-agents
+"""
+
+from typing import TYPE_CHECKING
+
+from composio import Composio
+
+if TYPE_CHECKING:
+ from typing_extensions import assert_type
+
+ from agents import FunctionTool
+
+ from composio_openai_agents import OpenAIAgentsProvider
+
+
+def test_openai_agents_provider_toolkits() -> None:
+ """Verify OpenAI Agents provider returns list[FunctionTool] for toolkits query."""
+ if TYPE_CHECKING:
+ composio: Composio[FunctionTool, list[FunctionTool]] = Composio(
+ provider=OpenAIAgentsProvider()
+ )
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Type checker should infer: list[FunctionTool]
+ assert_type(tools, list[FunctionTool])
+
+
+def test_openai_agents_provider_slug() -> None:
+ """Verify OpenAI Agents provider returns list[FunctionTool] for slug query."""
+ if TYPE_CHECKING:
+ composio: Composio[FunctionTool, list[FunctionTool]] = Composio(
+ provider=OpenAIAgentsProvider()
+ )
+ tools = composio.tools.get(user_id="test", slug="GITHUB_CREATE_REPO")
+
+ assert_type(tools, list[FunctionTool])
+
+
+def test_openai_agents_provider_tools_list() -> None:
+ """Verify OpenAI Agents provider returns list[FunctionTool] for tools list query."""
+ if TYPE_CHECKING:
+ composio: Composio[FunctionTool, list[FunctionTool]] = Composio(
+ provider=OpenAIAgentsProvider()
+ )
+ tools = composio.tools.get(
+ user_id="test",
+ tools=["GITHUB_CREATE_REPO", "GITHUB_GET_USER"],
+ )
+
+ assert_type(tools, list[FunctionTool])
+
+
+def test_openai_agents_provider_search() -> None:
+ """Verify OpenAI Agents provider returns list[FunctionTool] for search query."""
+ if TYPE_CHECKING:
+ composio: Composio[FunctionTool, list[FunctionTool]] = Composio(
+ provider=OpenAIAgentsProvider()
+ )
+ tools = composio.tools.get(user_id="test", search="github repository")
+
+ assert_type(tools, list[FunctionTool])
+
+
+def test_openai_agents_provider_inferred() -> None:
+ """Verify OpenAI Agents provider type is correctly inferred without explicit annotation."""
+ if TYPE_CHECKING:
+ composio = Composio(provider=OpenAIAgentsProvider())
+ tools = composio.tools.get(user_id="test", toolkits=["github"])
+
+ # Should infer list[FunctionTool] from provider type
+ assert_type(tools, list[FunctionTool])
diff --git a/uv.lock b/uv.lock
index d62914a7c..670102841 100644
--- a/uv.lock
+++ b/uv.lock
@@ -477,7 +477,7 @@ wheels = [
[[package]]
name = "composio"
-version = "0.11.0"
+version = "0.11.1"
source = { virtual = "python" }
dependencies = [
{ name = "composio-client" },
@@ -534,7 +534,7 @@ dev = [
[[package]]
name = "composio-anthropic"
-version = "0.11.0"
+version = "0.11.1"
source = { virtual = "python/providers/anthropic" }
dependencies = [
{ name = "anthropic" },
@@ -566,7 +566,7 @@ wheels = [
[[package]]
name = "composio-crewai"
-version = "0.11.0"
+version = "0.11.1"
source = { virtual = "python/providers/crewai" }
dependencies = [
{ name = "composio" },
@@ -581,7 +581,7 @@ requires-dist = [
[[package]]
name = "composio-gemini"
-version = "0.11.0"
+version = "0.11.1"
source = { virtual = "python/providers/gemini" }
dependencies = [
{ name = "composio" },
@@ -596,7 +596,7 @@ requires-dist = [
[[package]]
name = "composio-google"
-version = "0.11.0"
+version = "0.11.1"
source = { virtual = "python/providers/google" }
dependencies = [
{ name = "composio" },
@@ -611,7 +611,7 @@ requires-dist = [
[[package]]
name = "composio-google-adk"
-version = "0.11.0"
+version = "0.11.1"
source = { virtual = "python/providers/google_adk" }
dependencies = [
{ name = "composio" },
@@ -626,7 +626,7 @@ requires-dist = [
[[package]]
name = "composio-langchain"
-version = "0.11.0"
+version = "0.11.1"
source = { virtual = "python/providers/langchain" }
dependencies = [
{ name = "composio" },
@@ -641,7 +641,7 @@ requires-dist = [
[[package]]
name = "composio-openai"
-version = "0.11.0"
+version = "0.11.1"
source = { virtual = "python/providers/openai" }
dependencies = [
{ name = "composio" },
@@ -656,7 +656,7 @@ requires-dist = [
[[package]]
name = "composio-openai-agents"
-version = "0.11.0"
+version = "0.11.1"
source = { virtual = "python/providers/openai_agents" }
dependencies = [
{ name = "composio" },