Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
Add readme (#2047)
prateek99d21fc16ca0
diff --git a/python/README.md b/python/README.mdindex d3611150b..0ea819db0 100644--- a/python/README.md+++ b/python/README.md@@ -1,13 +1,490 @@-# Composio SDK+-## Setup+# Composio++The Composio Python SDK allows you to interact with the Composio Platform. It provides a powerful and flexible way to manage and execute tools, handle authentication, and integrate with various AI frameworks and platforms.++[Learn more about the SDK from our docs](https://docs.composio.dev)++## Core Features++- **Tools**: Manage and execute tools within the Composio ecosystem. Includes functionality to list, retrieve, and execute tools.+- **Toolkits**: Organize and manage collections of tools for specific use cases.+- **Triggers**: Create and manage event triggers that can execute tools based on specific conditions.+- **AuthConfigs**: Configure authentication providers and settings.+- **ConnectedAccounts**: Manage third-party service connections.+- **ActionExecution**: Track and manage the execution of actions within the platform.+- **Provider Integrations**: Built-in support for OpenAI, Anthropic, LangChain, CrewAI, AutoGen, and more.++## Installation```bash-make env-source .venv/bin/activate+pip install composio+# or+pip install composio-core+```++### Provider-Specific Installations++For specific AI framework integrations:++```bash+# OpenAI integration+pip install composio-openai++# LangChain integration+pip install composio-langchain++# CrewAI integration+pip install composio-crewai++# Anthropic integration+pip install composio-anthropic++# AutoGen integration+pip install composio-autogen++# And many more...+```++## Getting Started++### Basic Usage with OpenAI++```python+import os+from composio import Composio+from openai import OpenAI++# Initialize OpenAI client+openai_client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))++# Initialize Composio with your API key+composio = Composio(api_key=os.getenv("COMPOSIO_API_KEY"))++def main():+ try:+ # Fetch tools - single tool or multiple tools+ tools = composio.tools.get(user_id="default", slug="HACKERNEWS_GET_USER")+ # Or fetch multiple tools: composio.tools.get(user_id="default", toolkits=["hackernews"])++ query = "Find information about the HackerNews user 'pg'"++ # Create chat completion with tools+ response = openai_client.chat.completions.create(+ model="gpt-4o",+ messages=[+ {+ "role": "system",+ "content": "You are a helpful assistant that can use tools to answer questions."+ },+ {"role": "user", "content": query}+ ],+ tools=tools,+ tool_choice="auto"+ )++ # Handle tool calls if the assistant decides to use them+ if response.choices[0].message.tool_calls:+ print("π§ Assistant is using tool:", response.choices[0].message.tool_calls[0].function.name)++ # Execute the tool call+ tool_result = composio.provider.handle_tool_calls(+ response=response,+ user_id="default"+ )++ print("β Tool execution result:", tool_result)++ # Get final response from assistant with tool result+ final_response = openai_client.chat.completions.create(+ model="gpt-4o",+ messages=[+ {+ "role": "system",+ "content": "You are a helpful assistant that can use tools to answer questions."+ },+ {"role": "user", "content": query},+ response.choices[0].message,+ {+ "role": "tool",+ "tool_call_id": response.choices[0].message.tool_calls[0].id,+ "content": str(tool_result)+ }+ ]+ )++ print("π€ Final response:", final_response.choices[0].message.content)+ else:+ print("π€ Response:", response.choices[0].message.content)++ except Exception as error:+ print("β Error:", error)++if __name__ == "__main__":+ main()+```++### Using with Provider Integrations++#### OpenAI Provider++```python+from composio_openai import OpenAIProvider+from openai import OpenAI+from composio import Composio++# Initialize with OpenAI provider+openai_client = OpenAI()+composio = Composio(provider=OpenAIProvider())++# Define task+task = "Star a repo composiohq/composio on GitHub"++# Get GitHub tools that are pre-configured+tools = composio.tools.get(user_id="default", toolkits=["GITHUB"])++# Get response from the LLM+response = openai_client.chat.completions.create(+ model="gpt-4o-mini",+ tools=tools,+ messages=[+ {"role": "system", "content": "You are a helpful assistant."},+ {"role": "user", "content": task},+ ],+)++# Execute the function calls+result = composio.provider.handle_tool_calls(response=response, user_id="default")+print(result)+```++#### LangChain Integration++```python+from composio_langchain import ComposioToolSet+from langchain_openai import ChatOpenAI++# Initialize the toolset+toolset = ComposioToolSet()++# Get tools for a specific toolkit+tools = toolset.get_tools(toolkits=["GITHUB"])++# Initialize LLM+llm = ChatOpenAI(model="gpt-4o")++# Create agent with tools+from langchain.agents import create_openai_functions_agent, AgentExecutor+from langchain.prompts import ChatPromptTemplate++prompt = ChatPromptTemplate.from_messages([+ ("system", "You are a helpful assistant"),+ ("user", "{input}"),+ ("assistant", "{agent_scratchpad}")+])++agent = create_openai_functions_agent(llm, tools, prompt)+agent_executor = AgentExecutor(agent=agent, tools=tools)++# Execute task+result = agent_executor.invoke({"input": "Star the composiohq/composio repository"})+print(result)+```++## Configuration++The Composio constructor accepts the following configuration options:++```python+from composio import Composio+from composio.core.provider import OpenAIProvider++composio = Composio(+ api_key="your-api-key", # Your Composio API key+ base_url="https://api.composio.dev", # Custom API base URL (optional)+ timeout=60, # Request timeout in seconds+ max_retries=3, # Maximum number of retries+ allow_tracking=True, # Enable/disable telemetry (default: True)+ file_download_dir="./downloads", # Directory for file downloads+ provider=OpenAIProvider(), # Custom provider (default: OpenAIProvider)+ toolkit_versions="latest" # Toolkit versions to use+)+```++## Modifiers++Composio SDK supports powerful modifiers to transform tool schemas and execution behavior.++### Schema Modifiers++Schema modifiers allow you to transform tool schemas before they are used:++```python+from composio import schema_modifier+from composio.types import Tool++@schema_modifier(tools=["HACKERNEWS_GET_USER"])+def modify_schema(tool: str, toolkit: str, schema: Tool) -> Tool:+ # Perform modifications on the schema+ schema["description"] = "Enhanced HackerNews user lookup with additional features"+ schema["parameters"]["properties"]["include_karma"] = {+ "type": "boolean",+ "description": "Include user karma in response",+ "default": True+ }+ return schema++# Use the modifier when getting tools+tools = composio.tools.get(+ user_id="default",+ slug="HACKERNEWS_GET_USER",+ modifiers=[modify_schema]+)+```++### Execution Modifiers++Transform tool execution behavior with before and after execute modifiers:++```python+from composio import before_execute, after_execute+from composio.types import ToolExecuteParams, ToolExecutionResponse++@before_execute(tools=["HACKERNEWS_GET_USER"])+def before_execute_modifier(+ tool: str,+ toolkit: str,+ params: ToolExecuteParams+) -> ToolExecuteParams:+ # Transform input before execution+ print(f"Executing {tool} with params: {params}")+ return params++@after_execute(tools=["HACKERNEWS_GET_USER"])+def after_execute_modifier(+ tool: str,+ toolkit: str,+ response: ToolExecutionResponse+) -> ToolExecutionResponse:+ # Transform output after execution+ return {+ **response,+ "data": {+ **response["data"],+ "processed_at": "2024-01-01T00:00:00Z"+ }+ }++# Execute tool with modifiers+response = composio.tools.execute(+ user_id="default",+ slug="HACKERNEWS_GET_USER",+ arguments={"username": "pg"},+ modifiers=[before_execute_modifier, after_execute_modifier]+)+```++## Connected Accounts++Composio SDK provides a powerful way to manage third-party service connections through Connected Accounts. This feature allows you to authenticate with various services and maintain those connections.++### Creating a Connected Account++```python+from composio import Composio+from composio.types import auth_scheme++composio = Composio(api_key=os.getenv("COMPOSIO_API_KEY"))++# Create a connected account with OAuth+connection_request = composio.connected_accounts.initiate(+ user_id="user123",+ auth_config_id="ac_12343544", # You can create it from the dashboard+ callback_url="https://your-app.com/callback",+ data={+ # Additional data for the connection+ "scope": ["read", "write"]+ }+)++# Wait for the connection to be established+# Default timeout is 60 seconds+connected_account = connection_request.wait_for_connection()+print(connected_account)+```++### API Key Authentication++```python+# Create a connected account with API Key+connection_request = composio.connected_accounts.initiate(+ user_id="user123",+ auth_config_id="ac_12343544",+ config=auth_scheme.api_key(+ options={+ "api_key": "your-api-key-here"+ }+ )+)+```++### Managing Connected Accounts++```python+# List all connected accounts+accounts = composio.connected_accounts.list(user_id="user123")++# Get a specific connected account+account = composio.connected_accounts.get("account_id")++# Enable/Disable a connected account+composio.connected_accounts.enable("account_id")+composio.connected_accounts.disable("account_id")++# Refresh credentials+composio.connected_accounts.refresh("account_id")++# Delete a connected account+composio.connected_accounts.delete("account_id")+```++### Connection Statuses++Connected accounts can have the following statuses:++- `ACTIVE`: Connection is established and working+- `INACTIVE`: Connection is temporarily disabled+- `PENDING`: Connection is being processed+- `INITIATED`: Connection request has started+- `EXPIRED`: Connection credentials have expired+- `FAILED`: Connection attempt failed++## Tools and Toolkits++### Working with Tools++```python+# Get tools by toolkit+tools = composio.tools.get(user_id="default", toolkits=["GITHUB"])++# Get tools by search+tools = composio.tools.get(user_id="default", search="user")++# Get tools by toolkit and search+tools = composio.tools.get(user_id="default", toolkits=["GITHUB"], search="star")++# Execute a tool directly+response = composio.tools.execute(+ user_id="default",+ slug="HACKERNEWS_GET_USER",+ arguments={"username": "pg"}+)+print(response)+```++### Proxy Calls++Make direct API calls through connected accounts:++```python+# Execute proxy call (GitHub API)+proxy_response = composio.tools.proxy(+ endpoint="/repos/composiohq/composio/issues/1",+ method="GET",+ connected_account_id="ac_1234", # Use connected account for GitHub+ parameters=[+ {+ "name": "Accept",+ "value": "application/vnd.github.v3+json",+ "type": "header"+ }+ ]+)+print(proxy_response)+```++## Authentication Schemes++Composio supports various authentication schemes:++- OAuth2+- OAuth1+- OAuth1a+- API Key+- Basic Auth+- Bearer Token+- Google Service Account+- And more...++## Environment Variables++- `COMPOSIO_API_KEY`: Your Composio API key+- `COMPOSIO_BASE_URL`: Custom API base URL+- `COMPOSIO_LOGGING_LEVEL`: Logging level (silent, error, warn, info, debug)+- `DEVELOPMENT`: Development mode flag+- `COMPOSIO_TOOLKIT_VERSION_<TOOLKITNAME>`: Version of the specific toolkit+- `CI`: CI environment flag++## MCP (Model Context Protocol)++Create MCP servers for seamless integration with Claude, Cursor, and other MCP-compatible tools:++```python+from composio import Composio++composio = Composio()++# Create MCP server+mcp_server = composio.mcp.create(+ "my-mcp-server",+ toolkits=["github", "gmail"],+ manually_manage_connections=False+)++# Generate server instance for a user+server_instance = mcp_server.generate("user123")+print(f"MCP Server URL: {server_instance['url']}")```-## Usage+## Supported AI Frameworks++Composio provides dedicated integrations for popular AI frameworks:++- **OpenAI** - Direct integration with OpenAI's API+- **LangChain** - Tools and agents for LangChain workflows+- **LangGraph** - State machine workflows with LangGraph+- **CrewAI** - Multi-agent systems with CrewAI+- **AutoGen** - Microsoft's AutoGen framework+- **Anthropic** - Claude integration+- **Google AI** - Gemini and other Google AI services+- **LlamaIndex** - RAG and data framework integration++## Error Handling++```python+from composio import Composio+from composio.exceptions import ComposioError, ApiKeyNotProvidedError++try:+ composio = Composio() # Will raise ApiKeyNotProvidedError if no API key+ tools = composio.tools.get(user_id="default", toolkits=["GITHUB"])+except ApiKeyNotProvidedError:+ print("Please provide COMPOSIO_API_KEY environment variable")+except ComposioError as e:+ print(f"Composio error: {e}")+except Exception as e:+ print(f"Unexpected error: {e}")+```++## Contributing++We welcome contributions! Please see our [Contributing Guide](../CONTRIBUTING.md) for more details.++## License++Apache License 2.0++## Support-> π **NOTE**-> Ensure you've set the `COMPOSIO_API_KEY` and the `OPENAI_API_KEY` for these examples to work.+For support, please visit our [Documentation](https://docs.composio.dev) or join our [Discord Community](https://discord.gg/composio).