Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 22, 20:45 UTC
Chore: Add changelog for toolkit versioning (#1942)
Musthaq Ahamad committed
Sep 16, 2025 at 12:32 UTC
56e1fbab2e09968356e41de5983db005b766d5e6
2 files changed
+123
-124
fern/pages/src/changelog/09-16-25.md
new
+123
@@ -0,0 +1,123 @@
1
+# Toolkit Versioning in SDKs
2
+
3
+Composio Toolkit Versioning provides **granular control over tool versions** across all your integrations. Instead of always using the latest version of tools, developers can now specify exact toolkit versions, ensuring consistent behavior and controlled updates in production environments.
4
+
5
+## Why Use Toolkit Versioning?
6
+
7
+- **Version Stability**: Pin specific toolkit versions to avoid unexpected changes in production
8
+- **Controlled Updates**: Test new toolkit versions before deploying to production
9
+- **Environment Consistency**: Ensure the same toolkit versions across development, staging, and production
10
+- **Rollback Capability**: Easily revert to previous toolkit versions if issues arise
11
+- **Fine-grained Control**: Set different versions for different toolkits based on your needs
12
+
13
+---
14
+
15
+## Python SDK (v0.8.11)
16
+
17
+**Added**
18
+
19
+- **Toolkit Versioning Support**: New `toolkit_versions` parameter for controlling tool versions
20
+ - Added `toolkit_versions` parameter to `Composio` class initialization
21
+ - Support for global version setting (e.g., `'latest'`)
22
+ - Support for per-toolkit version mapping (e.g., `{'github': '20250902_00', 'slack': '20250902_00'}`)
23
+ - Environment variable support with `COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_NAME>` pattern
24
+ - New `toolkit_version.py` utility module for version resolution logic
25
+
26
+**Examples:**
27
+
28
+```python
29
+# Global version for all toolkits, only `latest` is supported
30
+composio = Composio(toolkit_versions='latest')
31
+
32
+# Per-toolkit version mapping
33
+composio = Composio(toolkit_versions={
34
+ 'github': '20250902_00',
35
+ 'slack': '20250902_00',
36
+ 'gmail': '20250901_01'
37
+})
38
+
39
+# Using environment variables
40
+# Set COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00
41
+composio = Composio() # Automatically picks up env vars
42
+
43
+# Get tools with specific versions
44
+tools = composio.tools.get('default', {'toolkits': ['github']})
45
+```
46
+
47
+## TypeScript SDK (v0.1.52)
48
+
49
+**Added**
50
+
51
+- **Toolkit Versioning Support**: Added `toolkitVersions` configuration option
52
+ - New `toolkitVersions` parameter in `Composio` class constructor
53
+ - Support for global version string or per-toolkit version mapping
54
+ - Environment variable parsing with `getToolkitVersionsFromEnv()` utility
55
+ - Enhanced `getRawComposioToolBySlug()` method for version-specific tool retrieval
56
+ - Version-aware tool filtering and search capabilities
57
+
58
+**Examples:**
59
+
60
+```typescript
61
+// Global version for all toolkits
62
+const composio = new Composio({
63
+ toolkitVersions: '20250902_00'
64
+});
65
+
66
+// Per-toolkit version mapping
67
+const composio = new Composio({
68
+ toolkitVersions: {
69
+ 'github': '20250902_00',
70
+ 'slack': '20250902_00',
71
+ 'gmail': '20250901_01'
72
+ }
73
+});
74
+
75
+// Using environment variables
76
+// Set COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00
77
+const composio = new Composio(); // Automatically picks up env vars
78
+
79
+// Get specific tool version
80
+const tool = await composio.tools.getRawComposioToolBySlug(
81
+ 'GITHUB_GET_REPO',
82
+);
83
+
84
+// Get tools with version-aware filtering
85
+const tools = await composio.tools.get('default', {
86
+ toolkits: ['github'],
87
+ limit: 10
88
+});
89
+```
90
+
91
+## Key Benefits
92
+
93
+- **Environment Variables**: Set `COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_NAME>=<VERSION>` for automatic version resolution
94
+- **Flexible Configuration**: Choose between global versions or per-toolkit version mapping
95
+- **Backward Compatibility**: Existing code works unchanged - versioning is opt-in
96
+- **Version Fallback**: Automatically falls back to 'latest' when no version is specified
97
+- **Cross-Platform Consistency**: Identical developer experience across Python and TypeScript
98
+
99
+## Version Format
100
+
101
+Toolkit versions follow the format: `YYYYMMDD_NN` (e.g., `20250902_00`) or use `'latest'` for the most recent version only supported at global scope and not individual toolkit level.
102
+
103
+## Environment Variables
104
+
105
+```bash
106
+# Set specific versions for different toolkits
107
+export COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00
108
+export COMPOSIO_TOOLKIT_VERSION_SLACK=20250902_00
109
+export COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_01
110
+```
111
+
112
+## Migration Note
113
+
114
+This feature is fully backward compatible. Existing code will continue to work without changes, using the latest versions by default. To enable versioning, simply add the `toolkit_versions` parameter during SDK initialization.
115
+
116
+---
117
+
118
+## Additional Updates
119
+
120
+- **Package Updates**: Bumped all Python provider packages to v0.8.10
121
+- **Documentation**: Enhanced API documentation with versioning examples
122
+- **Testing**: Added comprehensive test coverage (400+ new test cases) for versioning functionality
123
+- **Examples**: New versioning examples demonstrating practical usage patterns
ts/examples/tools/src/versioning.ts
deleted
-124
@@ -1,124 +0,0 @@
1
-import { Composio } from '@composio/core';
2
-
3
-const composio = new Composio();
4
-
5
-async function demonstrateRawToolFetching() {
6
- console.log('=== Raw Composio Tool Fetching Examples ===\n');
7
-
8
- // Example 1: Get a single tool by slug (latest version)
9
- console.log('1. Getting latest version of HACKERNEWS_GET_USER:');
10
- const latestTool = await composio.tools.getRawComposioToolBySlug('HACKERNEWS_GET_USER');
11
- console.log(`Tool: ${latestTool.name} (v${latestTool.version})`);
12
- console.log(`Available versions: ${latestTool.availableVersions?.join(', ')}\n`);
13
-
14
- // Example 2: Get a specific version of a tool
15
- console.log('2. Getting specific version of a tool:');
16
- try {
17
- const specificVersionTool = await composio.tools.getRawComposioToolBySlug(
18
- 'HACKERNEWS_GET_USER',
19
- '20250909_00' // specific version
20
- );
21
- console.log(`Tool: ${specificVersionTool.name} (v${specificVersionTool.version})\n`);
22
- } catch (error) {
23
- console.log('Note: Specific version may not be available, using latest instead\n');
24
- }
25
-
26
- // Example 3: Get a tool with schema transformation
27
- console.log('3. Getting tool with schema transformation:');
28
- const customizedTool = await composio.tools.getRawComposioToolBySlug(
29
- 'HACKERNEWS_GET_USER',
30
- 'latest',
31
- {
32
- modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
33
- return {
34
- ...schema,
35
- description: `Enhanced ${schema.description} - Modified at ${new Date().toISOString()}`,
36
- customMetadata: {
37
- toolkit: toolkitSlug,
38
- modifiedBy: 'versioning-example',
39
- features: ['enhanced-logging', 'custom-validation']
40
- }
41
- };
42
- }
43
- }
44
- );
45
- console.log(`Modified tool description: ${customizedTool.description}`);
46
- console.log(`Custom metadata:`, (customizedTool as any).customMetadata);
47
- console.log();
48
-
49
- // Example 4: Get multiple tools with filters
50
- console.log('4. Getting multiple tools with filters:');
51
- const hackerNewsTools = await composio.tools.getRawComposioTools({
52
- toolkits: ['hackernews'],
53
- limit: 3
54
- });
55
- console.log(`Found ${hackerNewsTools.length} HackerNews tools:`);
56
- hackerNewsTools.forEach(tool => {
57
- console.log(`- ${tool.slug}: ${tool.name} (v${tool.version})`);
58
- });
59
- console.log();
60
-
61
- // Example 5: Get tools with version control
62
- console.log('5. Getting tools with version control:');
63
- const versionedTools = await composio.tools.getRawComposioTools({
64
- toolkits: ['hackernews'],
65
- toolkitVersions: 'latest' // or specify specific versions: { hackernews: '20250909_00' }
66
- });
67
- console.log(`Found ${versionedTools.length} versioned tools:`);
68
- versionedTools.forEach(tool => {
69
- console.log(`- ${tool.slug} (v${tool.version})`);
70
- });
71
- console.log();
72
-
73
- // Example 6: Get tools with schema transformation
74
- console.log('6. Getting multiple tools with schema transformation:');
75
- const enhancedTools = await composio.tools.getRawComposioTools({
76
- toolkits: ['hackernews'],
77
- limit: 2
78
- }, {
79
- modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
80
- return {
81
- ...schema,
82
- tags: [...(schema.tags || []), 'enhanced', 'example'],
83
- customProperties: {
84
- lastFetched: new Date().toISOString(),
85
- exampleUsage: `This tool (${toolSlug}) is from the ${toolkitSlug} toolkit`
86
- }
87
- };
88
- }
89
- });
90
-
91
- console.log('Enhanced tools with custom properties:');
92
- enhancedTools.forEach(tool => {
93
- console.log(`- ${tool.slug}:`);
94
- console.log(` Tags: ${tool.tags?.join(', ')}`);
95
- console.log(` Custom properties:`, (tool as any).customProperties);
96
- });
97
- console.log();
98
-
99
- // Example 7: Search for tools
100
- console.log('7. Searching for tools:');
101
- try {
102
- const searchResults = await composio.tools.getRawComposioTools({
103
- search: 'user'
104
- });
105
- console.log(`Found ${searchResults.length} tools matching 'user':`);
106
- searchResults.slice(0, 3).forEach(tool => {
107
- console.log(`- ${tool.slug}: ${tool.name}`);
108
- });
109
- } catch (error) {
110
- console.log('Search might require additional parameters');
111
- }
112
- console.log();
113
-
114
- // Example 8: Using the wrapped tools (comparison)
115
- console.log('8. Comparison with wrapped tools:');
116
- const wrappedTools = await composio.tools.get('default', {
117
- tools: ['HACKERNEWS_GET_USER']
118
- });
119
- console.log('Wrapped tools (provider-specific format):');
120
- console.log(typeof wrappedTools, Object.keys(wrappedTools));
121
-}
122
-
123
-// Run the demonstration
124
-demonstrateRawToolFetching().catch(console.error);