@devries-cameron20 / composio-1 / commits / 31521bd1a
Fork 0

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

Fix typedocs and examples for toolkit version (#2212)

Co-authored-by: jkomyno <12381818+jkomyno@users.noreply.github.com>

Musthaq Ahamad committed Dec 4, 2025 at 16:03 UTC 31521bd1a5094069d2b1f2b22080743a8a756b0e
19 files changed +73 -54
.changeset/silly-parrots-grab.md new
+5
@@ -0,0 +1,5 @@
1 +---
2 +'@composio/core': patch
3 +---
4 +
5 +Update typedocs and examples for toolkit versions
.github/workflows/ts.test.yml
+2
@@ -14,6 +14,8 @@ jobs:
14 test:
15 name: Test Typescript SDK
16 runs-on: ubuntu-latest
17 + permissions:
18 + pull-requests: write
19
20 steps:
21 - name: Checkout Code
pnpm-lock.yaml
+7 -4
@@ -15,6 +15,9 @@ catalogs:
15 '@composio/client':
16 specifier: 0.1.0-alpha.46
17 version: 0.1.0-alpha.46
18 + '@modelcontextprotocol/sdk':
19 + specifier: ^1.22.0
20 + version: 1.23.0
21 tsup:
22 specifier: ^8.5.0
23 version: 8.5.1
@@ -371,7 +374,7 @@ importers:
374 specifier: ^1.1.0
375 version: 1.30.0(@modelcontextprotocol/sdk@1.23.0(@cfworker/json-schema@4.1.1)(zod@4.1.13))
376 '@modelcontextprotocol/sdk':
374 - specifier: ^1.18.0
377 + specifier: 'catalog:'
378 version: 1.23.0(@cfworker/json-schema@4.1.1)(zod@4.1.13)
379 dotenv:
380 specifier: ^16.4.1
@@ -508,7 +511,7 @@ importers:
511 specifier: workspace:*
512 version: link:../../packages/providers/vercel
513 '@modelcontextprotocol/sdk':
511 - specifier: ^1.18.0
514 + specifier: 'catalog:'
515 version: 1.23.0(@cfworker/json-schema@4.1.1)(zod@4.1.13)
516 ai:
517 specifier: '>=5.0.102'
@@ -558,7 +561,7 @@ importers:
561 specifier: workspace:*
562 version: link:../../packages/providers/openai-agents
563 '@modelcontextprotocol/sdk':
561 - specifier: ^1.18.0
564 + specifier: 'catalog:'
565 version: 1.23.0(@cfworker/json-schema@4.1.1)(zod@4.1.13)
566 '@openai/agents':
567 specifier: ^0.1.4
@@ -729,7 +732,7 @@ importers:
732 specifier: workspace:*
733 version: link:../../packages/providers/vercel
734 '@modelcontextprotocol/sdk':
732 - specifier: ^1.18.0
735 + specifier: 'catalog:'
736 version: 1.23.0(@cfworker/json-schema@4.1.1)(zod@4.1.13)
737 ai:
738 specifier: '>=5.0.102'
pnpm-workspace.yaml
+2 -1
@@ -16,7 +16,8 @@ catalog:
16 '@cloudflare/vitest-pool-workers': ^0.9.2
17 '@cloudflare/workers-types': ^4.20250917.0
18 '@composio/client': 0.1.0-alpha.46
19 - ai: ^5.0.102
19 + '@modelcontextprotocol/sdk': ^1.22.0
20 + ai: 5.0.52
21 openai: ^5.20.3
22 tsup: ^8.5.0
23 tsx: ^4.20.5
python/README.md
+1 -1
@@ -208,7 +208,7 @@ composio = Composio(
208 allow_tracking=True, # Enable/disable telemetry (default: True)
209 file_download_dir="./downloads", # Directory for file downloads
210 provider=OpenAIProvider(), # Custom provider (default: OpenAIProvider)
211 - toolkit_versions="latest" # Toolkit versions to use
211 + toolkit_versions={ "github": "12202025_01" } # Toolkit versions to use
212 )
213 ```
214
python/composio/core/types.py
+4 -5
@@ -6,12 +6,11 @@ import typing_extensions as te
6
7 # Tool versioning types
8 ToolkitLatestVersion = te.Literal["latest"]
9 -ToolkitVersion = str # Can be "latest" or any version string like "20250906_01"
9 +ToolkitVersion = t.Union[
10 + ToolkitLatestVersion, str
11 +] # Can be "latest" or any version string like "20250906_01"
12 ToolkitVersions = t.Dict[str, ToolkitVersion]
11 -ToolkitVersionParam = t.Union[
12 - str, ToolkitVersions, None
13 -] # String can be any global version
14 -
13 +ToolkitVersionParam = t.Union[ToolkitVersions, ToolkitLatestVersion, None]
14
15 __all__ = [
16 "ToolkitLatestVersion",
python/composio/sdk.py
+3 -3
@@ -73,10 +73,10 @@ class Composio(t.Generic[TProvider], WithLogger):
73 :param base_url: The base URL to use for the SDK.
74 :param timeout: The timeout to use for the SDK.
75 :param max_retries: The maximum number of retries to use for the SDK.
76 - :param toolkit_versions: The versions of the toolkits to use. Can be:
76 + :param toolkit_versions: A dictionary mapping toolkit names to specific versions:
77 + - A dictionary mapping toolkit names to specific versions
78 - A string (e.g., 'latest', '20250906_01') to use the same version for all toolkits
78 - - A dict mapping toolkit names to specific versions
79 - - None to use 'latest' as default
79 + - None or omitted to use 'latest' as default
80 """
81 WithLogger.__init__(self)
82 api_key = kwargs.get("api_key", os.environ.get("COMPOSIO_API_KEY"))
python/composio/utils/toolkit_version.py
+5 -8
@@ -38,19 +38,16 @@ def get_toolkit_versions(
38 Gets toolkit versions configuration by merging environment variables, user-provided defaults, and fallbacks.
39
40 Priority order:
41 - 1. If default_versions is a string, use it as global version for all toolkits (e.g., "latest", "20250906_01")
41 + 1. If default_versions is a string, use it as a global version for all toolkits
42 2. User-provided toolkit version mappings (default_versions dict)
43 3. Environment variables (COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_NAME>)
44 4. Fallback to 'latest' if no versions are configured
45
46 - :param default_versions: Optional default versions configuration (string for global version
47 - or dict mapping toolkit names to versions). String can be any version
48 - like "latest", "20250906_01", etc.
49 - :return: Toolkit versions configuration - either a global version string,
50 - toolkit-specific version mapping, or 'latest'
46 + :param default_versions: Optional default versions configuration (string for global version or dict mapping toolkit names to versions)
47 + :return: Toolkit versions configuration - either a string for global version or dict mapping toolkit names to versions
48 """
52 - # If already set by user as a string (e.g., 'latest', '20250906_01'), use it as global version for all toolkits
53 - if default_versions and isinstance(default_versions, str):
49 + # If already set by user as a string, use it as global version for all toolkits
50 + if isinstance(default_versions, str):
51 return default_versions
52
53 # Check if there are envs similar to COMPOSIO_TOOLKIT_VERSION_GITHUB then extract the toolkit name
python/tests/test_core_types.py
+7 -3
@@ -16,9 +16,13 @@ class TestCoreTypes:
16 # Should be a Literal["latest"]
17 assert hasattr(ToolkitLatestVersion, "__origin__")
18
19 - def test_toolkit_version_is_string(self):
20 - """Test ToolkitVersion is string type."""
21 - assert ToolkitVersion is str
19 + def test_toolkit_version_is_union(self):
20 + """Test ToolkitVersion is a Union type."""
21 + # ToolkitVersion should be Union[Literal["latest"], str]
22 + import typing
23 +
24 + assert hasattr(ToolkitVersion, "__origin__")
25 + assert ToolkitVersion.__origin__ is typing.Union
26
27 def test_toolkit_versions_is_dict(self):
28 """Test ToolkitVersions is dict type."""
python/tests/test_toolkit_version.py
+1 -1
@@ -136,7 +136,7 @@ class TestToolkitVersion:
136 with pytest.MonkeyPatch().context() as m:
137 # Test 1: String global version overrides everything
138 m.setenv("COMPOSIO_TOOLKIT_VERSION_GITHUB", "env_version")
139 - result = get_toolkit_versions("global_version")
139 + result = get_toolkit_version("github", "global_version")
140 assert result == "global_version"
141
142 # Test 2: User dict overrides env vars
ts/docs/api/tools.md
+1 -1
@@ -63,7 +63,7 @@ const customTool = await composio.tools.get('default', 'GITHUB_GET_REPOS', {
63
64 Executes a given tool with the provided parameters manually.
65
66 -> **Important:** When manually executing tools (especially in workflows), a specific version is **required**. The method will throw an error if `'latest'` is used as the version. This ensures there are no mismatches in tool arguments when new versions are released. You can bypass this requirement using `dangerouslySkipVersionCheck: true`, but this is **not recommended for production**.
66 +> **Important:** When manually executing tools (especially in workflows), a specific version is **required**. The method will throw an error if toolkitVersion is not provided or `latest` is used as the version. This ensures there are no mismatches in tool arguments when new versions are released. You can bypass this requirement using `dangerouslySkipVersionCheck: true`, but this is **not recommended for production**.
67
68 ```typescript
69 // Execute with a pinned version (REQUIRED for workflows and manual execution)
ts/docs/api/triggers.md
+1 -1
@@ -280,7 +280,7 @@ const triggerType = await composio.triggers.getType('GMAIL_NEW_GMAIL_MESSAGE');
280
281 **Behavior:**
282
283 -- The method uses the global toolkit version configured in the Composio client (defaults to `'latest'`)
283 +- The method uses the global toolkit version configured in the Composio client (defaults to `'latest'` if not provided)
284 - To use a specific toolkit version, configure `toolkitVersions` when initializing the Composio instance
285 - See [Toolkit Versions Configuration](../getting-started.md#toolkit-versions) for details on setting toolkit versions
286
ts/docs/getting-started.md
+12 -15
@@ -62,20 +62,7 @@ Example: `12082025_00` represents version 00 released on August 12, 2025.
62
63 #### Configuration Options
64
65 -**Option 1: Global Version for All Toolkits**
66 -
67 -```typescript
68 -const composio = new Composio({
69 - toolkitVersions: 'latest' // Use latest version for all toolkits
70 -});
71 -
72 -// Or pin a specific version globally
73 -const composio = new Composio({
74 - toolkitVersions: '12082025_00' // All toolkits use this version
75 -});
76 -```
77 -
78 -**Option 2: Specific Versions per Toolkit (Recommended for Production)**
65 +**Option 1: Specific Versions per Toolkit (Recommended for Production)**
66
67 ```typescript
68 const composio = new Composio({
@@ -87,7 +74,7 @@ const composio = new Composio({
74 });
75 ```
76
90 -**Option 3: Using Environment Variables**
77 +**Option 2: Using Environment Variables**
78
79 You can set toolkit versions using environment variables:
80
@@ -107,6 +94,16 @@ const composio = new Composio({
94 });
95 ```
96
97 +**Option 3: Latest version for all toolkits**
98 +If omitted, SDK will use `latest` version for all the toolkits
99 +
100 +```typescript
101 +const composio = new Composio({
102 + apiKey: 'your-api-key',
103 + // since omitted, this will use `latest` for all toolkits
104 +})
105 +```
106 +
107 #### Version Behavior
108
109 - **Tools & Triggers:** The toolkit version configuration applies to both tools and triggers
ts/examples/google/package.json
+1 -1
@@ -24,7 +24,7 @@
24 "@composio/core": "workspace:*",
25 "@composio/google": "workspace:*",
26 "@google/genai": "^1.1.0",
27 - "@modelcontextprotocol/sdk": "^1.18.0",
27 + "@modelcontextprotocol/sdk": "catalog:",
28 "dotenv": "^16.4.1"
29 },
30 "devDependencies": {
ts/examples/mcp/package.json
+1 -1
@@ -21,7 +21,7 @@
21 "@ai-sdk/openai": "^2.0.35",
22 "@composio/core": "workspace:*",
23 "@composio/vercel": "workspace:*",
24 - "@modelcontextprotocol/sdk": "^1.18.0",
24 + "@modelcontextprotocol/sdk": "catalog:",
25 "ai": "catalog:",
26 "dotenv": "^16.4.1"
27 },
ts/examples/openai/package.json
+1 -1
@@ -22,7 +22,7 @@
22 "@composio/core": "workspace:*",
23 "@composio/openai": "workspace:*",
24 "@composio/openai-agents": "workspace:*",
25 - "@modelcontextprotocol/sdk": "^1.18.0",
25 + "@modelcontextprotocol/sdk": "catalog:",
26 "@openai/agents": "^0.1.4",
27 "dotenv": "^16.4.1",
28 "openai": "^5.16.0",
ts/examples/vercel/package.json
+1 -1
@@ -18,7 +18,7 @@
18 "@ai-sdk/openai": "^2.0.16",
19 "@composio/core": "workspace:*",
20 "@composio/vercel": "workspace:*",
21 - "@modelcontextprotocol/sdk": "^1.18.0",
21 + "@modelcontextprotocol/sdk": "catalog:",
22 "ai": "catalog:",
23 "dotenv": "^16.5.0",
24 "zod-to-json-schema": "^3.24.6"
ts/packages/core/src/composio.ts
+3 -2
@@ -78,6 +78,7 @@ export type ComposioConfig<
78 disableVersionCheck?: boolean;
79 /**
80 * The versions of the toolkits to use for tool execution and retrieval.
81 + * Omit to use 'latest' for all toolkits.
82 *
83 * **Version Control:**
84 * When executing tools manually (via `tools.execute()`), if this resolves to "latest",
@@ -89,9 +90,9 @@ export type ComposioConfig<
90 * Defaults to 'latest' if nothing is provided.
91 * You can specify individual toolkit versions via environment variables: `COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00`
92 *
92 - * @example Global version for all toolkits
93 + * @example Global version for all toolkits, omit to use 'latest'
94 * ```typescript
94 - * const composio = new Composio({ toolkitVersions: 'latest' });
95 + * const composio = new Composio();
96 * ```
97 *
98 * @example Specific versions for different toolkits (recommended for production)
ts/packages/core/src/types/tool.types.ts
+15 -5
@@ -142,30 +142,40 @@ export type ToolListResponse = z.infer<typeof ToolListResponseSchema>;
142 */
143 export type ToolList = Array<Tool>;
144
145 +export const ToolkitLatestVersionSchema = z.literal('latest');
146 /**
147 * latest toolkit version param
148 */
148 -export type ToolkitLatestVersion = 'latest';
149 +export type ToolkitLatestVersion = z.infer<typeof ToolkitLatestVersionSchema>;
150 +
151 +export const ToolkitVersionSchema = z.union([ToolkitLatestVersionSchema, z.string()]);
152 /**
153 * Versioning a tool based on it's toolkit version, either 'latest' or actual tool version as string '20250902_00'
154 * @example
155 * 'latest'
156 * '20250902_00'
157 */
155 -export type ToolkitVersion = ToolkitLatestVersion | string;
158 +export type ToolkitVersion = z.infer<typeof ToolkitVersionSchema>;
159 +
160 +export const ToolkitVersionsSchema = z.record(z.string(), ToolkitVersionSchema);
161 /**
162 * Versioning multiple toolkits
163 * @example
164 * { 'github': 'latest', 'slack': '20250902_00' }
165 */
166 export type ToolkitVersions = Record<string, ToolkitVersion>;
167 +
168 +export const ToolkitVersionParamSchema = z
169 + .union([ToolkitVersionsSchema, ToolkitLatestVersionSchema, z.undefined()])
170 + .describe('The versioning of the toolkits. eg: { "github": "latest", "slack": "20250902_00" }');
171 /**
163 - * Versioning a toolkit based on it's tool versions, either 'latest' or actual tool version as string '20250902_00'
172 + * Versioning a tool based on it's toolkit version
173 * @example
165 - * 'latest'
174 + * ```json
175 * { 'github': 'latest', 'slack': '20250902_00' }
176 + * ```
177 */
168 -export type ToolkitVersionParam = ToolkitLatestVersion | ToolkitVersions | undefined;
178 +export type ToolkitVersionParam = z.infer<typeof ToolkitVersionParamSchema>;
179
180 export const ToolListParamsSchema = z.object({
181 tools: z.array(z.string()).optional(),