mirror of
https://github.com/ComposioHQ/composio.git
synced 2026-09-22 11:46:35 +08:00
shams haroon
aefc3ec897
## Summary Adds TypeSafe Jev providers for TypeScript and Python that turn tool schemas and a request into a call, a partial call, or an abstention. ## What changed - adds `@composio/typesafe`, a provider for TypeSafe's Jev model. Jev has no tool calling, so `composio.tools.get()` compiles tools into typed questions and `decide` returns a `call`, a `partial` call, or an `abstain`, each with a confidence - adds `execute` for a user ID or a session: caller arguments complete a `partial`, and a tool tagged `destructiveHint` routes at a fixed floor of 0.9 and needs `confirm: true` - adds the companion helpers `shortlistTools` and `confidenceGate` (a `beforeExecute` modifier that fails closed) for use with other providers - adds `composio-typesafe`, the Python counterpart with sync and async clients; both test suites compile one shared question corpus, so both SDKs ask Jev the same questions for the same tool - registers the package in the provider-compatibility release gate, adds a `minor` changeset, the `ts/examples/typesafe` example, a Python demo, and a dedicated `py.test.yml` step - exempts only `@typesafe-ai/sdk@0.6.0` from `minimumReleaseAge` (publisher, SLSA provenance, and the absence of install scripts were checked by hand), and sets `engines.node` to `>=24.17.0` for this package because the SDK terminates the process after a handled cancellation on older Node.js releases (typesafe-ai/typesafe-sdk-js#2) ## Usage ```typescript const provider = new TypesafeProvider(); const composio = new Composio({ provider }); const toolSet = await composio.tools.get('user_123', { tools: ['GITHUB_LIST_REPOSITORY_ISSUES'] }); const decision = await provider.decide(toolSet, 'List the closed issues of ComposioHQ/composio'); if (decision.kind !== 'abstain') { // Jev binds closed-set arguments (enums, booleans, arrays of enums). Free text comes from you. await provider.execute('user_123', decision, { arguments: { owner: 'ComposioHQ', repo: 'composio' } }); } ``` ## Behavior notes - `abstain` means only that the model judged so. A failed request throws one `TypesafeApiError` whose `reason` tells rate limits, timeouts, and rejections apart, and a malformed response throws `TypesafeMalformedResponseError`. No error holds state, argument values, response content, or the SDK's own error. - Routing and the action gate see `request` only, so text in `context` cannot change which tool is picked. `contextScope: 'all'` opts out. - State is never truncated: over-budget state, unknown top-level state keys, and non-JSON values throw. - The options are `client`, `apiKey`, `model`, `thresholds`, and `contextScope`. The provider builds its client at log level `warn`, so `TYPESAFE_LOG_LEVEL=debug` cannot print request bodies. - Root-level `allOf`, `anyOf`, and `oneOf` schemas are rejected explicitly in both SDKs, including after `$ref` resolution, so composed requirements cannot silently disappear. Property-level composition remains supported as documented. - Completing a partial decision requires an own, non-`undefined` argument value in TypeScript; inherited names such as `toString` do not satisfy required arguments. Supplied `__proto__` keys are preserved as own data properties. ## Validation - 147 TypeScript provider tests and 141 Python provider tests pass. The 11 new missing-argument regression cases fail on the original implementation and pass with the fixes. - Typecheck, Oxlint, Prettier, the tsdown build with ATTW/publint, Ruff, mypy, type-inference, and release-gate checks passed locally. - All 13 opt-in live tests passed across the TypeSafe-only and Composio-backed suites against real Jev 1.13.0. These tests make decisions without executing external tools. - The actual TypeScript and Python Hacker News examples both ran end to end against production APIs: fetch tools, decide, detect the missing username, supply `pg`, and execute the read-only lookup. Both returned the live profile for `pg`. Not in this PR: the docs page, which needs the first npm publish so its snippets compile. The first npm and PyPI publishes and a `TYPESAFE_API_KEY` CI secret are manual steps. ```mermaid flowchart LR A[composio.tools.get] --> B[compile tools into questions] B --> C[decide: state + questions] C --> D{Jev answers} D -->|none fits, no action, low confidence| E[abstain] D -->|required arguments missing| F[partial] D -->|everything bound| G[call] F -->|caller arguments| H[execute] G --> H H -->|destructive tool| I[needs confirm: true] ```
Composio SDK v3 Documentation
Composio SDK is a powerful toolkit that enables you to integrate third-party tools and services into your applications. This SDK helps you connect to various services (toolkits), execute tools, and manage user connections seamlessly.
Table of Contents
- Overview
- Installation
- Core Concepts
- Getting Started
- API Reference
- Providers
- Examples
- Advanced Topics
- Internal Documentation
Overview
Composio SDK allows you to:
- Execute tools from various services (like GitHub, Gmail, Slack, etc.)
- Manage user connections to external services
- Create session-scoped custom tools
- Implement triggers and event handlers
- Integrate with AI providers like OpenAI
The SDK is designed to be flexible and extensible, allowing you to integrate it into various types of applications.
Installation
npm install @composio/core
Core Concepts
The Composio SDK is built around several key concepts:
- UserIds: Unique identifier for a user in your application (eg. UUID for a user in your database)
- Tools: Individual actions that can be performed (e.g., "Get GitHub Repository", "Send Email")
- Toolkits: Collections of related tools (e.g., GitHub, Gmail)
- Connected Accounts: User connections to external services
- Auth Configs: Authentication configurations for external services
- Providers: Adapters for AI services that can use tools (e.g., OpenAI)
- Custom Tools: Session-scoped local tools created with
experimental_createTool - MCP: Create and manage MCP Servers and clients
Check out the Core Concepts documentation for more detailed information.
Getting Started
Here's a quick example of how to use the Composio SDK:
import { Composio } from '@composio/core';
// Initialize the SDK
const composio = new Composio({
apiKey: 'your-api-key',
});
// Get tools from a specific toolkit
const tools = await composio.tools.get('default', {
toolkits: ['github'],
});
// Execute a tool
const result = await composio.tools.execute('GITHUB_GET_REPO', {
userId: 'default',
arguments: {
owner: 'composio',
repo: 'sdk',
},
});
console.log(result.data);
For more detailed examples and tutorials, check out the Getting Started guide.
API Reference
The complete API reference documentation is available here:
- Composio Class
- Tools
- Toolkits
- Connected Accounts
- Auth Configs
- Providers
- MCP
- ToolRouter
- Tool Router Session Files
Providers
Composio SDK comes with built-in support for different providers:
Non-Agentic Providers
- OpenAI Provider - OpenAI integration with GPT-4, GPT-3.5, etc.
- Anthropic Provider - Anthropic Claude integration
- Google Provider - Google Gemini integration
- Cloudflare Provider - Cloudflare Workers AI integration
- TypeSafe Provider - TypeSafe Jev integration: decides a tool call, a partial call, or an abstention with a confidence
Agentic Providers
- LangChain Provider - LangChain integration with LCEL support
- Mastra Provider - Agentic provider for autonomous behavior
- Vercel Provider - Vercel AI SDK integration
Examples
Check out our examples directory for complete code samples:
Advanced Topics
Internal Documentation
For SDK maintainers and contributors:
- Configuration and Environment Variables - Detailed guide on SDK configuration
- Triggers Implementation - Internal workings of the trigger system