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.

Chore: Add changelog for toolkit versioning (#1942)

Musthaq Ahamad56e1fbab2e09
diff --git a/fern/pages/src/changelog/09-16-25.md b/fern/pages/src/changelog/09-16-25.md
new file mode 100644
index 000000000..fd7b27bea
--- /dev/null
+++ b/fern/pages/src/changelog/09-16-25.md
@@ -0,0 +1,123 @@
+# Toolkit Versioning in SDKs
+
+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.
+
+## Why Use Toolkit Versioning?
+
+- **Version Stability**: Pin specific toolkit versions to avoid unexpected changes in production
+- **Controlled Updates**: Test new toolkit versions before deploying to production
+- **Environment Consistency**: Ensure the same toolkit versions across development, staging, and production
+- **Rollback Capability**: Easily revert to previous toolkit versions if issues arise
+- **Fine-grained Control**: Set different versions for different toolkits based on your needs
+
+---
+
+## Python SDK (v0.8.11)
+
+**Added**
+
+- **Toolkit Versioning Support**: New `toolkit_versions` parameter for controlling tool versions
+ - Added `toolkit_versions` parameter to `Composio` class initialization
+ - Support for global version setting (e.g., `'latest'`)
+ - Support for per-toolkit version mapping (e.g., `{'github': '20250902_00', 'slack': '20250902_00'}`)
+ - Environment variable support with `COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_NAME>` pattern
+ - New `toolkit_version.py` utility module for version resolution logic
+
+**Examples:**
+
+```python
+# Global version for all toolkits, only `latest` is supported
+composio = Composio(toolkit_versions='latest')
+
+# Per-toolkit version mapping
+composio = Composio(toolkit_versions={
+ 'github': '20250902_00',
+ 'slack': '20250902_00',
+ 'gmail': '20250901_01'
+})
+
+# Using environment variables
+# Set COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00
+composio = Composio() # Automatically picks up env vars
+
+# Get tools with specific versions
+tools = composio.tools.get('default', {'toolkits': ['github']})
+```
+
+## TypeScript SDK (v0.1.52)
+
+**Added**
+
+- **Toolkit Versioning Support**: Added `toolkitVersions` configuration option
+ - New `toolkitVersions` parameter in `Composio` class constructor
+ - Support for global version string or per-toolkit version mapping
+ - Environment variable parsing with `getToolkitVersionsFromEnv()` utility
+ - Enhanced `getRawComposioToolBySlug()` method for version-specific tool retrieval
+ - Version-aware tool filtering and search capabilities
+
+**Examples:**
+
+```typescript
+// Global version for all toolkits
+const composio = new Composio({
+ toolkitVersions: '20250902_00'
+});
+
+// Per-toolkit version mapping
+const composio = new Composio({
+ toolkitVersions: {
+ 'github': '20250902_00',
+ 'slack': '20250902_00',
+ 'gmail': '20250901_01'
+ }
+});
+
+// Using environment variables
+// Set COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00
+const composio = new Composio(); // Automatically picks up env vars
+
+// Get specific tool version
+const tool = await composio.tools.getRawComposioToolBySlug(
+ 'GITHUB_GET_REPO',
+);
+
+// Get tools with version-aware filtering
+const tools = await composio.tools.get('default', {
+ toolkits: ['github'],
+ limit: 10
+});
+```
+
+## Key Benefits
+
+- **Environment Variables**: Set `COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_NAME>=<VERSION>` for automatic version resolution
+- **Flexible Configuration**: Choose between global versions or per-toolkit version mapping
+- **Backward Compatibility**: Existing code works unchanged - versioning is opt-in
+- **Version Fallback**: Automatically falls back to 'latest' when no version is specified
+- **Cross-Platform Consistency**: Identical developer experience across Python and TypeScript
+
+## Version Format
+
+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.
+
+## Environment Variables
+
+```bash
+# Set specific versions for different toolkits
+export COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00
+export COMPOSIO_TOOLKIT_VERSION_SLACK=20250902_00
+export COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_01
+```
+
+## Migration Note
+
+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.
+
+---
+
+## Additional Updates
+
+- **Package Updates**: Bumped all Python provider packages to v0.8.10
+- **Documentation**: Enhanced API documentation with versioning examples
+- **Testing**: Added comprehensive test coverage (400+ new test cases) for versioning functionality
+- **Examples**: New versioning examples demonstrating practical usage patterns
diff --git a/ts/examples/tools/src/versioning.ts b/ts/examples/tools/src/versioning.ts
deleted file mode 100644
index 77adc6307..000000000
--- a/ts/examples/tools/src/versioning.ts
+++ /dev/null
@@ -1,124 +0,0 @@
-import { Composio } from '@composio/core';
-
-const composio = new Composio();
-
-async function demonstrateRawToolFetching() {
- console.log('=== Raw Composio Tool Fetching Examples ===\n');
-
- // Example 1: Get a single tool by slug (latest version)
- console.log('1. Getting latest version of HACKERNEWS_GET_USER:');
- const latestTool = await composio.tools.getRawComposioToolBySlug('HACKERNEWS_GET_USER');
- console.log(`Tool: ${latestTool.name} (v${latestTool.version})`);
- console.log(`Available versions: ${latestTool.availableVersions?.join(', ')}\n`);
-
- // Example 2: Get a specific version of a tool
- console.log('2. Getting specific version of a tool:');
- try {
- const specificVersionTool = await composio.tools.getRawComposioToolBySlug(
- 'HACKERNEWS_GET_USER',
- '20250909_00' // specific version
- );
- console.log(`Tool: ${specificVersionTool.name} (v${specificVersionTool.version})\n`);
- } catch (error) {
- console.log('Note: Specific version may not be available, using latest instead\n');
- }
-
- // Example 3: Get a tool with schema transformation
- console.log('3. Getting tool with schema transformation:');
- const customizedTool = await composio.tools.getRawComposioToolBySlug(
- 'HACKERNEWS_GET_USER',
- 'latest',
- {
- modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
- return {
- ...schema,
- description: `Enhanced ${schema.description} - Modified at ${new Date().toISOString()}`,
- customMetadata: {
- toolkit: toolkitSlug,
- modifiedBy: 'versioning-example',
- features: ['enhanced-logging', 'custom-validation']
- }
- };
- }
- }
- );
- console.log(`Modified tool description: ${customizedTool.description}`);
- console.log(`Custom metadata:`, (customizedTool as any).customMetadata);
- console.log();
-
- // Example 4: Get multiple tools with filters
- console.log('4. Getting multiple tools with filters:');
- const hackerNewsTools = await composio.tools.getRawComposioTools({
- toolkits: ['hackernews'],
- limit: 3
- });
- console.log(`Found ${hackerNewsTools.length} HackerNews tools:`);
- hackerNewsTools.forEach(tool => {
- console.log(`- ${tool.slug}: ${tool.name} (v${tool.version})`);
- });
- console.log();
-
- // Example 5: Get tools with version control
- console.log('5. Getting tools with version control:');
- const versionedTools = await composio.tools.getRawComposioTools({
- toolkits: ['hackernews'],
- toolkitVersions: 'latest' // or specify specific versions: { hackernews: '20250909_00' }
- });
- console.log(`Found ${versionedTools.length} versioned tools:`);
- versionedTools.forEach(tool => {
- console.log(`- ${tool.slug} (v${tool.version})`);
- });
- console.log();
-
- // Example 6: Get tools with schema transformation
- console.log('6. Getting multiple tools with schema transformation:');
- const enhancedTools = await composio.tools.getRawComposioTools({
- toolkits: ['hackernews'],
- limit: 2
- }, {
- modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
- return {
- ...schema,
- tags: [...(schema.tags || []), 'enhanced', 'example'],
- customProperties: {
- lastFetched: new Date().toISOString(),
- exampleUsage: `This tool (${toolSlug}) is from the ${toolkitSlug} toolkit`
- }
- };
- }
- });
-
- console.log('Enhanced tools with custom properties:');
- enhancedTools.forEach(tool => {
- console.log(`- ${tool.slug}:`);
- console.log(` Tags: ${tool.tags?.join(', ')}`);
- console.log(` Custom properties:`, (tool as any).customProperties);
- });
- console.log();
-
- // Example 7: Search for tools
- console.log('7. Searching for tools:');
- try {
- const searchResults = await composio.tools.getRawComposioTools({
- search: 'user'
- });
- console.log(`Found ${searchResults.length} tools matching 'user':`);
- searchResults.slice(0, 3).forEach(tool => {
- console.log(`- ${tool.slug}: ${tool.name}`);
- });
- } catch (error) {
- console.log('Search might require additional parameters');
- }
- console.log();
-
- // Example 8: Using the wrapped tools (comparison)
- console.log('8. Comparison with wrapped tools:');
- const wrappedTools = await composio.tools.get('default', {
- tools: ['HACKERNEWS_GET_USER']
- });
- console.log('Wrapped tools (provider-specific format):');
- console.log(typeof wrappedTools, Object.keys(wrappedTools));
-}
-
-// Run the demonstration
-demonstrateRawToolFetching().catch(console.error);