@devries-cameron20 / composio-1 / commits / 5f38a486e
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.

feat: add Python SDK reference docs with auto-generation

- Add generate-docs.py script using griffe for doc extraction - Generate MDX docs for Composio, Tools, Toolkits, Triggers, ConnectedAccounts, and AuthConfigs classes - Include decorators section (before_execute, after_execute, schema_modifier) on index page - Add CI workflow job for auto-generating on python/composio/** changes - Update CLAUDE.md with Python SDK docs instructions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Sushmithamallesh committed Jan 6, 2026 at 17:06 UTC 5f38a486e2d39cda86718759eddd31573bef74d3
12 files changed +1360 -7
.github/workflows/generate-sdk-docs.yml
+51 -4
@@ -5,10 +5,11 @@ on:
5 branches: [next]
6 paths:
7 - 'ts/packages/core/src/**'
8 + - 'python/composio/**'
9 workflow_dispatch: # Allow manual trigger
10
11 jobs:
11 - generate-docs:
12 + generate-ts-docs:
13 runs-on: ubuntu-latest
14 permissions:
15 contents: write
@@ -37,7 +38,7 @@ jobs:
38 id: changes
39 run: |
40 # Check for both modified and untracked files
40 - if [[ -n $(git status --porcelain fumadocs/content/reference/typescript/) ]]; then
41 + if [[ -n $(git status --porcelain fumadocs/content/reference/sdk-reference/typescript/) ]]; then
42 echo "has_changes=true" >> $GITHUB_OUTPUT
43 fi
44
@@ -53,10 +54,56 @@ jobs:
54
55 ---
56 *Generated by [generate-sdk-docs.yml](../blob/next/.github/workflows/generate-sdk-docs.yml)*
56 - branch: docs/auto-update-sdk-reference
57 + branch: docs/auto-update-ts-sdk-reference
58 base: next
59 add-paths: |
59 - fumadocs/content/reference/typescript/
60 + fumadocs/content/reference/sdk-reference/typescript/
61 + labels: |
62 + documentation
63 + automated
64 +
65 + generate-python-docs:
66 + runs-on: ubuntu-latest
67 + permissions:
68 + contents: write
69 + pull-requests: write
70 +
71 + steps:
72 + - name: Checkout
73 + uses: actions/checkout@v4
74 +
75 + - name: Setup uv
76 + uses: astral-sh/setup-uv@v4
77 +
78 + - name: Generate Python SDK docs
79 + run: |
80 + cd python
81 + uv run --with griffe python scripts/generate-docs.py
82 +
83 + - name: Check for changes
84 + id: changes
85 + run: |
86 + # Check for both modified and untracked files
87 + if [[ -n $(git status --porcelain fumadocs/content/reference/sdk-reference/python/) ]]; then
88 + echo "has_changes=true" >> $GITHUB_OUTPUT
89 + fi
90 +
91 + - name: Create Pull Request
92 + if: steps.changes.outputs.has_changes == 'true'
93 + uses: peter-evans/create-pull-request@v6
94 + with:
95 + token: ${{ secrets.GITHUB_TOKEN }}
96 + commit-message: 'docs: auto-generate Python SDK reference'
97 + title: 'docs: Update Python SDK reference'
98 + body: |
99 + Auto-generated because Python SDK source files changed.
100 +
101 + ---
102 + *Generated by [generate-sdk-docs.yml](../blob/next/.github/workflows/generate-sdk-docs.yml)*
103 + branch: docs/auto-update-python-sdk-reference
104 + base: next
105 + add-paths: |
106 + fumadocs/content/reference/sdk-reference/python/
107 labels: |
108 documentation
109 automated
fumadocs/CLAUDE.md
+9 -2
@@ -17,14 +17,21 @@ This is the Composio documentation site built with Fumadocs (Next.js-based docs
17 - `--font-mono: 'IBM Plex Mono'` - Code blocks
18
19 ## SDK Reference Docs
20 -Auto-generated TypeScript SDK documentation from `@composio/core` source code.
20 +Auto-generated SDK documentation from source code.
21
22 +### TypeScript SDK
23 - **Source**: `ts/packages/core/src/models/*.ts` (JSDoc comments)
24 - **Generator**: `ts/packages/core/scripts/generate-docs.ts`
25 - **Output**: `content/reference/sdk-reference/typescript/`
26 - **Regenerate**: `pnpm --filter @composio/core generate:docs`
27
27 -CI auto-generates on changes to `ts/packages/core/src/**` via `.github/workflows/generate-sdk-docs.yml`.
28 +### Python SDK
29 +- **Source**: `python/composio/**/*.py` (docstrings)
30 +- **Generator**: `python/scripts/generate-docs.py` (uses griffe)
31 +- **Output**: `content/reference/sdk-reference/python/`
32 +- **Regenerate**: `cd python && uv run --with griffe python scripts/generate-docs.py`
33 +
34 +CI auto-generates on changes to `ts/packages/core/src/**` or `python/composio/**` via `.github/workflows/generate-sdk-docs.yml`.
35
36 ## Common Gotchas
37 1. **CSS variables**: Use `var(--composio-orange)` not `var(--orange)`. Check `global.css` for defined variables.
fumadocs/content/reference/sdk-reference/meta.json
+1 -1
@@ -1,4 +1,4 @@
1 {
2 "title": "SDK Reference",
3 - "pages": ["typescript"]
3 + "pages": ["typescript", "python"]
4 }
fumadocs/content/reference/sdk-reference/python/auth-configs.mdx new
+150
@@ -0,0 +1,150 @@
1 +---
2 +title: AuthConfigs
3 +description: Manage authentication configurations.
4 +---
5 +
6 +## Methods
7 +
8 +### list()
9 +
10 +Lists authentication configurations based on provided filter criteria.
11 +
12 +```python
13 +def list(query: auth_config_list_params.AuthConfigListParams = ...) -> auth_config_list_response.AuthConfigListResponse
14 +```
15 +
16 +**Parameters**
17 +
18 +| Name | Type |
19 +|------|------|
20 +| `query?` | `auth_config_list_params.AuthConfigListParams` |
21 +
22 +**Returns**
23 +
24 +`auth_config_list_response.AuthConfigListResponse`
25 +
26 +---
27 +
28 +### create()
29 +
30 +Create a new auth config
31 +
32 +```python
33 +def create(toolkit: str, options: auth_config_create_params.AuthConfig) -> auth_config_create_response.AuthConfig
34 +```
35 +
36 +**Parameters**
37 +
38 +| Name | Type |
39 +|------|------|
40 +| `toolkit` | `str` |
41 +| `options` | `auth_config_create_params.AuthConfig` |
42 +
43 +**Returns**
44 +
45 +`auth_config_create_response.AuthConfig` — The created auth config.
46 +
47 +---
48 +
49 +### get()
50 +
51 +Retrieves a specific authentication configuration by its ID
52 +
53 +```python
54 +def get(nanoid: str) -> auth_config_retrieve_response.AuthConfigRetrieveResponse
55 +```
56 +
57 +**Parameters**
58 +
59 +| Name | Type |
60 +|------|------|
61 +| `nanoid` | `str` |
62 +
63 +**Returns**
64 +
65 +`auth_config_retrieve_response.AuthConfigRetrieveResponse` — The retrieved auth config.
66 +
67 +---
68 +
69 +### update()
70 +
71 +Updates an existing authentication configuration. This method allows you to modify properties of an auth config such as credentials, scopes, or tool restrictions. The update type (custom or default) determines which fields can be updated.
72 +
73 +```python
74 +def update(nanoid: str, options: auth_config_update_params.AuthConfigUpdateParams) -> Dict
75 +```
76 +
77 +**Parameters**
78 +
79 +| Name | Type |
80 +|------|------|
81 +| `nanoid` | `str` |
82 +| `options` | `auth_config_update_params.AuthConfigUpdateParams` |
83 +
84 +**Returns**
85 +
86 +`Dict` — The updated auth config.
87 +
88 +---
89 +
90 +### delete()
91 +
92 +Deletes an existing authentication configuration.
93 +
94 +```python
95 +def delete(nanoid: str) -> Dict
96 +```
97 +
98 +**Parameters**
99 +
100 +| Name | Type |
101 +|------|------|
102 +| `nanoid` | `str` |
103 +
104 +**Returns**
105 +
106 +`Dict` — The deleted auth config.
107 +
108 +---
109 +
110 +### enable()
111 +
112 +Enables an existing authentication configuration.
113 +
114 +```python
115 +def enable(nanoid: str) -> Dict
116 +```
117 +
118 +**Parameters**
119 +
120 +| Name | Type |
121 +|------|------|
122 +| `nanoid` | `str` |
123 +
124 +**Returns**
125 +
126 +`Dict` — The enabled auth config.
127 +
128 +---
129 +
130 +### disable()
131 +
132 +Disables an existing authentication configuration.
133 +
134 +```python
135 +def disable(nanoid: str) -> Dict
136 +```
137 +
138 +**Parameters**
139 +
140 +| Name | Type |
141 +|------|------|
142 +| `nanoid` | `str` |
143 +
144 +**Returns**
145 +
146 +`Dict` — The disabled auth config.
147 +
148 +---
149 +
150 +[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/auth_configs.py#L18)
fumadocs/content/reference/sdk-reference/python/composio.mdx new
+16
@@ -0,0 +1,16 @@
1 +---
2 +title: Composio
3 +description: Composio SDK for Python.
4 +---
5 +
6 +## Properties
7 +
8 +| Name | Type |
9 +|------|------|
10 +| [`tools`](/reference/sdk-reference/python/tools) | `Tools` |
11 +| [`toolkits`](/reference/sdk-reference/python/toolkits) | `Toolkits` |
12 +| [`triggers`](/reference/sdk-reference/python/triggers) | `Triggers` |
13 +| [`auth_configs`](/reference/sdk-reference/python/auth-configs) | `AuthConfigs` |
14 +| [`connected_accounts`](/reference/sdk-reference/python/connected-accounts) | `ConnectedAccounts` |
15 +
16 +[View source](https://github.com/composiohq/composio/blob/next/python/composio/sdk.py#L52)
fumadocs/content/reference/sdk-reference/python/connected-accounts.mdx new
+99
@@ -0,0 +1,99 @@
1 +---
2 +title: ConnectedAccounts
3 +description: Manage connected accounts. This class is used to manage connected accounts in the Composio SDK. These are used to authenticate with third-party se...
4 +---
5 +
6 +## Methods
7 +
8 +### initiate()
9 +
10 +Compound function to create a new connected account. This function creates a new connected account and returns a connection request. Users can then wait for the connection to be established using the `wait_for_connection` method.
11 +
12 +```python
13 +def initiate(user_id: str, auth_config_id: str, callback_url: str | None = ..., allow_multiple: bool = ..., config: connected_account_create_params.ConnectionState | None = ...) -> ConnectionRequest
14 +```
15 +
16 +**Parameters**
17 +
18 +| Name | Type |
19 +|------|------|
20 +| `user_id` | `str` |
21 +| `auth_config_id` | `str` |
22 +| `callback_url?` | `str \| None` |
23 +| `allow_multiple?` | `bool` |
24 +| `config?` | `connected_account_create_params.ConnectionState \| None` |
25 +
26 +**Returns**
27 +
28 +`ConnectionRequest` — The connection request.
29 +
30 +---
31 +
32 +### link()
33 +
34 +Create a Composio Connect Link for a user to connect their account to a given auth config. This method will return an external link which you can use for the user to connect their account.
35 +
36 +```python
37 +def link(user_id: str, auth_config_id: str, callback_url: str | None = ...) -> ConnectionRequest
38 +```
39 +
40 +**Parameters**
41 +
42 +| Name | Type |
43 +|------|------|
44 +| `user_id` | `str` |
45 +| `auth_config_id` | `str` |
46 +| `callback_url?` | `str \| None` |
47 +
48 +**Returns**
49 +
50 +`ConnectionRequest` — Connection request object.
51 +
52 +**Example**
53 +
54 +```python
55 +# Create a connection request and redirect the user to the redirect url
56 + connection_request = composio.connected_accounts.link('user_123', 'auth_config_123')
57 + redirect_url = connection_request.redirect_url
58 + print(f"Visit: {redirect_url} to authenticate your account")
59 +
60 + # Wait for the connection to be established
61 + connected_account = connection_request.wait_for_connection()
62 +
63 + # Create a connection request with callback URL
64 + connection_request = composio.connected_accounts.link(
65 + 'user_123',
66 + 'auth_config_123',
67 + callback_url='https://your-app.com/callback'
68 + )
69 + redirect_url = connection_request.redirect_url
70 + print(f"Visit: {redirect_url} to authenticate your account")
71 +
72 + # Wait for the connection to be established
73 + connected_account = composio.connected_accounts.wait_for_connection(connection_request.id)
74 +```
75 +
76 +---
77 +
78 +### wait_for_connection()
79 +
80 +Wait for connected account with given ID to be active
81 +
82 +```python
83 +def wait_for_connection(id: str, timeout: float | None = ...) -> connected_account_retrieve_response.ConnectedAccountRetri...
84 +```
85 +
86 +**Parameters**
87 +
88 +| Name | Type |
89 +|------|------|
90 +| `id` | `str` |
91 +| `timeout?` | `float \| None` |
92 +
93 +**Returns**
94 +
95 +`connected_account_retrieve_response.ConnectedAccountRetri...`
96 +
97 +---
98 +
99 +[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/connected_accounts.py#L300)
fumadocs/content/reference/sdk-reference/python/index.mdx new
+82
@@ -0,0 +1,82 @@
1 +---
2 +title: Python SDK Reference
3 +description: API reference for the Composio Python SDK
4 +---
5 +
6 +# Python SDK Reference
7 +
8 +Complete API reference for the `composio` Python package.
9 +
10 +## Installation
11 +
12 +```bash
13 +pip install composio
14 +```
15 +
16 +Or with uv:
17 +
18 +```bash
19 +uv add composio
20 +```
21 +
22 +## Classes
23 +
24 +| Class | Description |
25 +|-------|-------------|
26 +| [`Composio`](/reference/sdk-reference/python/composio) | Composio SDK for Python. |
27 +| [`Tools`](/reference/sdk-reference/python/tools) | Tools class definition This class is used to manage tools in the Composio SDK. ... |
28 +| [`Toolkits`](/reference/sdk-reference/python/toolkits) | Toolkits are a collectiono of tools that can be used to perform various tasks. T... |
29 +| [`Triggers`](/reference/sdk-reference/python/triggers) | Triggers (instance) class |
30 +| [`ConnectedAccounts`](/reference/sdk-reference/python/connected-accounts) | Manage connected accounts. This class is used to manage connected accounts in t... |
31 +| [`AuthConfigs`](/reference/sdk-reference/python/auth-configs) | Manage authentication configurations. |
32 +
33 +## Quick Start
34 +
35 +```python
36 +from composio import Composio
37 +
38 +composio = Composio(api_key="your-api-key")
39 +
40 +# Get tools for a user
41 +tools = composio.tools.get("user-123", toolkits=["github"])
42 +
43 +# Execute a tool
44 +result = composio.tools.execute(
45 + "GITHUB_GET_REPOS",
46 + arguments={"owner": "composio"},
47 + user_id="user-123"
48 +)
49 +```
50 +
51 +## Decorators
52 +
53 +### before_execute
54 +
55 +[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/_modifiers.py#L171)
56 +
57 +```python
58 +@before_execute(modifier: BeforeExecute | None = ..., tools: List[str | None] = ..., toolkits: List[str | None] = ...)
59 +def my_modifier(...):
60 + ...
61 +```
62 +
63 +### after_execute
64 +
65 +[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/_modifiers.py#L132)
66 +
67 +```python
68 +@after_execute(modifier: AfterExecute | None = ..., tools: List[str | None] = ..., toolkits: List[str | None] = ...)
69 +def my_modifier(...):
70 + ...
71 +```
72 +
73 +### schema_modifier
74 +
75 +[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/_modifiers.py#L210)
76 +
77 +```python
78 +@schema_modifier(modifier: SchemaModifier | None = ..., tools: List[str | None] = ..., toolkits: List[str | None] = ...)
79 +def my_modifier(...):
80 + ...
81 +```
82 +
fumadocs/content/reference/sdk-reference/python/meta.json new
+11
@@ -0,0 +1,11 @@
1 +{
2 + "title": "Python SDK",
3 + "pages": [
4 + "composio",
5 + "tools",
6 + "toolkits",
7 + "triggers",
8 + "connected-accounts",
9 + "auth-configs"
10 + ]
11 +}
\ No newline at end of file
fumadocs/content/reference/sdk-reference/python/toolkits.mdx new
+122
@@ -0,0 +1,122 @@
1 +---
2 +title: Toolkits
3 +description: "Toolkits are a collectiono of tools that can be used to perform various tasks. They're conceptualized as a set of tools. Ex: Github toolkit can per..."
4 +---
5 +
6 +## Methods
7 +
8 +### list()
9 +
10 +List all toolkits.
11 +
12 +```python
13 +def list(category: str | None = ..., cursor: str | None = ..., limit: float | None = ..., sort_by: Literal['usage', 'alphabetically' | None] = ..., managed_by: Literal['composio', 'all', 'project' | None] = ...) -> toolkit_list_response.ToolkitListResponse
14 +```
15 +
16 +**Parameters**
17 +
18 +| Name | Type |
19 +|------|------|
20 +| `category?` | `str \| None` |
21 +| `cursor?` | `str \| None` |
22 +| `limit?` | `float \| None` |
23 +| `sort_by?` | `Literal['usage', 'alphabetically' \| None]` |
24 +| `managed_by?` | `Literal['composio', 'all', 'project' \| None]` |
25 +
26 +**Returns**
27 +
28 +`toolkit_list_response.ToolkitListResponse`
29 +
30 +---
31 +
32 +### get()
33 +
34 +```python
35 +def get(slug: str | None = ..., query: toolkit_list_params.ToolkitListParams | None = ...) -> Union[toolkit_retrieve_response.ToolkitRetrieveResponse, ...
36 +```
37 +
38 +**Parameters**
39 +
40 +| Name | Type |
41 +|------|------|
42 +| `slug?` | `str \| None` |
43 +| `query?` | `toolkit_list_params.ToolkitListParams \| None` |
44 +
45 +**Returns**
46 +
47 +`Union[toolkit_retrieve_response.ToolkitRetrieveResponse, ...`
48 +
49 +---
50 +
51 +### list_categories()
52 +
53 +List all categories of toolkits.
54 +
55 +```python
56 +def list_categories()
57 +```
58 +
59 +---
60 +
61 +### authorize()
62 +
63 +Authorize a user to a toolkit If auth config is not found, it will be created using composio managed auth.
64 +
65 +```python
66 +def authorize(user_id: str, toolkit: str)
67 +```
68 +
69 +**Parameters**
70 +
71 +| Name | Type |
72 +|------|------|
73 +| `user_id` | `str` |
74 +| `toolkit` | `str` |
75 +
76 +---
77 +
78 +### get_connected_account_initiation_fields()
79 +
80 +Get the required property for a given toolkit and auth scheme.
81 +
82 +```python
83 +def get_connected_account_initiation_fields(toolkit: str, auth_scheme: AuthSchemeL, required_only: bool = ...) -> AuthFieldsT
84 +```
85 +
86 +**Parameters**
87 +
88 +| Name | Type |
89 +|------|------|
90 +| `toolkit` | `str` |
91 +| `auth_scheme` | `AuthSchemeL` |
92 +| `required_only?` | `bool` |
93 +
94 +**Returns**
95 +
96 +`AuthFieldsT`
97 +
98 +---
99 +
100 +### get_auth_config_creation_fields()
101 +
102 +Get the required property for a given toolkit and auth scheme.
103 +
104 +```python
105 +def get_auth_config_creation_fields(toolkit: str, auth_scheme: AuthSchemeL, required_only: bool = ...) -> AuthFieldsT
106 +```
107 +
108 +**Parameters**
109 +
110 +| Name | Type |
111 +|------|------|
112 +| `toolkit` | `str` |
113 +| `auth_scheme` | `AuthSchemeL` |
114 +| `required_only?` | `bool` |
115 +
116 +**Returns**
117 +
118 +`AuthFieldsT`
119 +
120 +---
121 +
122 +[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/toolkits.py#L26)
fumadocs/content/reference/sdk-reference/python/tools.mdx new
+129
@@ -0,0 +1,129 @@
1 +---
2 +title: Tools
3 +description: Tools class definition This class is used to manage tools in the Composio SDK. It provides methods to list, get, and execute tools.
4 +---
5 +
6 +## Methods
7 +
8 +### get_raw_composio_tool_by_slug()
9 +
10 +Returns schema for the given tool slug.
11 +
12 +```python
13 +def get_raw_composio_tool_by_slug(slug: str) -> Tool
14 +```
15 +
16 +**Parameters**
17 +
18 +| Name | Type |
19 +|------|------|
20 +| `slug` | `str` |
21 +
22 +**Returns**
23 +
24 +`Tool`
25 +
26 +---
27 +
28 +### get_raw_composio_tools()
29 +
30 +Get a list of tool schemas based on the provided filters.
31 +
32 +```python
33 +def get_raw_composio_tools(tools: list[str | None] = ..., search: str | None = ..., toolkits: list[str | None] = ..., scopes: List[str | None] = ..., limit: int | None = ...) -> list[Tool]
34 +```
35 +
36 +**Parameters**
37 +
38 +| Name | Type |
39 +|------|------|
40 +| `tools?` | `list[str \| None]` |
41 +| `search?` | `str \| None` |
42 +| `toolkits?` | `list[str \| None]` |
43 +| `scopes?` | `List[str \| None]` |
44 +| `limit?` | `int \| None` |
45 +
46 +**Returns**
47 +
48 +`list[Tool]`
49 +
50 +---
51 +
52 +### get()
53 +
54 +Get a tool or list of tools based on the provided arguments.
55 +
56 +```python
57 +def get(user_id: str, slug: str | None = ..., tools: list[str | None] = ..., search: str | None = ..., toolkits: list[str | None] = ..., scopes: List[str | None] = ..., modifiers: Modifiers | None = ..., limit: int | None = ...)
58 +```
59 +
60 +**Parameters**
61 +
62 +| Name | Type |
63 +|------|------|
64 +| `user_id` | `str` |
65 +| `slug?` | `str \| None` |
66 +| `tools?` | `list[str \| None]` |
67 +| `search?` | `str \| None` |
68 +| `toolkits?` | `list[str \| None]` |
69 +| `scopes?` | `List[str \| None]` |
70 +| `modifiers?` | `Modifiers \| None` |
71 +| `limit?` | `int \| None` |
72 +
73 +---
74 +
75 +### execute()
76 +
77 +Execute a tool with the provided parameters. This method calls the Composio API or a custom tool handler to execute the tool and returns the response. It automatically determines whether to use a custom tool or a Composio API tool based on the slug.
78 +
79 +```python
80 +def execute(slug: str, arguments: Dict, connected_account_id: str | None = ..., custom_auth_params: tool_execute_params.CustomAuthParams | None = ..., custom_connection_data: tool_execute_params.CustomConnectionData | None = ..., user_id: str | None = ..., text: str | None = ..., version: str | None = ..., dangerously_skip_version_check: bool | None = ..., modifiers: Modifiers | None = ...) -> ToolExecutionResponse
81 +```
82 +
83 +**Parameters**
84 +
85 +| Name | Type |
86 +|------|------|
87 +| `slug` | `str` |
88 +| `arguments` | `Dict` |
89 +| `connected_account_id?` | `str \| None` |
90 +| `custom_auth_params?` | `tool_execute_params.CustomAuthParams \| None` |
91 +| `custom_connection_data?` | `tool_execute_params.CustomConnectionData \| None` |
92 +| `user_id?` | `str \| None` |
93 +| `text?` | `str \| None` |
94 +| `version?` | `str \| None` |
95 +| `dangerously_skip_version_check?` | `bool \| None` |
96 +| `modifiers?` | `Modifiers \| None` |
97 +
98 +**Returns**
99 +
100 +`ToolExecutionResponse` — The response from the tool.
101 +
102 +---
103 +
104 +### proxy()
105 +
106 +Proxy a tool call to the Composio API
107 +
108 +```python
109 +def proxy(endpoint: str, method: Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD'], body: object | None = ..., connected_account_id: str | None = ..., parameters: List[tool_proxy_params.Parameter | None] = ..., custom_connection_data: tool_proxy_params.CustomConnectionData | None = ...) -> tool_proxy_response.ToolProxyResponse
110 +```
111 +
112 +**Parameters**
113 +
114 +| Name | Type |
115 +|------|------|
116 +| `endpoint` | `str` |
117 +| `method` | `Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD']` |
118 +| `body?` | `object \| None` |
119 +| `connected_account_id?` | `str \| None` |
120 +| `parameters?` | `List[tool_proxy_params.Parameter \| None]` |
121 +| `custom_connection_data?` | `tool_proxy_params.CustomConnectionData \| None` |
122 +
123 +**Returns**
124 +
125 +`tool_proxy_response.ToolProxyResponse`
126 +
127 +---
128 +
129 +[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/tools.py#L48)
fumadocs/content/reference/sdk-reference/python/triggers.mdx new
+154
@@ -0,0 +1,154 @@
1 +---
2 +title: Triggers
3 +description: Triggers (instance) class
4 +---
5 +
6 +## Methods
7 +
8 +### get_type()
9 +
10 +Get a trigger type by its slug Uses the global toolkit version provided when initializing composio instance to fetch trigger for specific toolkit version
11 +
12 +```python
13 +def get_type(slug: str) -> TriggersTypeRetrieveResponse
14 +```
15 +
16 +**Parameters**
17 +
18 +| Name | Type |
19 +|------|------|
20 +| `slug` | `str` |
21 +
22 +**Returns**
23 +
24 +`TriggersTypeRetrieveResponse` — The trigger type
25 +
26 +---
27 +
28 +### list_active()
29 +
30 +List all active triggers
31 +
32 +```python
33 +def list_active(trigger_ids: list[str | None] = ..., trigger_names: list[str | None] = ..., auth_config_ids: list[str | None] = ..., connected_account_ids: list[str | None] = ..., show_disabled: bool | None = ..., limit: int | None = ..., page: int | None = ...)
34 +```
35 +
36 +**Parameters**
37 +
38 +| Name | Type |
39 +|------|------|
40 +| `trigger_ids?` | `list[str \| None]` |
41 +| `trigger_names?` | `list[str \| None]` |
42 +| `auth_config_ids?` | `list[str \| None]` |
43 +| `connected_account_ids?` | `list[str \| None]` |
44 +| `show_disabled?` | `bool \| None` |
45 +| `limit?` | `int \| None` |
46 +| `page?` | `int \| None` |
47 +
48 +---
49 +
50 +### list()
51 +
52 +List all the trigger types.
53 +
54 +```python
55 +def list(cursor: str | None = ..., limit: int | None = ..., toolkit_slugs: list[str | None] = ...)
56 +```
57 +
58 +**Parameters**
59 +
60 +| Name | Type |
61 +|------|------|
62 +| `cursor?` | `str \| None` |
63 +| `limit?` | `int \| None` |
64 +| `toolkit_slugs?` | `list[str \| None]` |
65 +
66 +---
67 +
68 +### create()
69 +
70 +Create a trigger instance
71 +
72 +```python
73 +def create(slug: str, user_id: str | None = ..., connected_account_id: str | None = ..., trigger_config: Dict[str, Any | None] = ...) -> trigger_instance_upsert_response.TriggerInstanceUpsertRes...
74 +```
75 +
76 +**Parameters**
77 +
78 +| Name | Type |
79 +|------|------|
80 +| `slug` | `str` |
81 +| `user_id?` | `str \| None` |
82 +| `connected_account_id?` | `str \| None` |
83 +| `trigger_config?` | `Dict[str, Any \| None]` |
84 +
85 +**Returns**
86 +
87 +`trigger_instance_upsert_response.TriggerInstanceUpsertRes...` — The trigger instance
88 +
89 +---
90 +
91 +### subscribe()
92 +
93 +Subscribe to a trigger and receive trigger events.
94 +
95 +```python
96 +def subscribe(timeout: float = ...) -> TriggerSubscription
97 +```
98 +
99 +**Parameters**
100 +
101 +| Name | Type |
102 +|------|------|
103 +| `timeout?` | `float` |
104 +
105 +**Returns**
106 +
107 +`TriggerSubscription` — The trigger subscription handler.
108 +
109 +---
110 +
111 +### verify_webhook()
112 +
113 +Verify an incoming webhook payload and signature. This method validates that the webhook request is authentic by: 1. Verifying the HMAC-SHA256 signature matches the payload 2. Optionally checking that the webhook timestamp is within the tolerance window
114 +
115 +```python
116 +def verify_webhook(payload: str, signature: str, secret: str, tolerance: int = ...) -> TriggerEvent
117 +```
118 +
119 +**Parameters**
120 +
121 +| Name | Type |
122 +|------|------|
123 +| `payload` | `str` |
124 +| `signature` | `str` |
125 +| `secret` | `str` |
126 +| `tolerance?` | `int` |
127 +
128 +**Returns**
129 +
130 +`TriggerEvent` — The verified and parsed webhook payload as a TriggerEvent :raises WebhookSignatureVerificationError: If the signature verification fails :raises WebhookPayloadError: If the payload cannot be parsed or is invalid
131 +
132 +**Example**
133 +
134 +```python
135 +# In a Flask webhook handler
136 + @app.route('/webhook', methods=['POST'])
137 + def webhook():
138 + try:
139 + event = composio.triggers.verify_webhook(
140 + payload=request.get_data(as_text=True),
141 + signature=request.headers.get('x-composio-signature', ''),
142 + secret=os.environ['COMPOSIO_WEBHOOK_SECRET'],
143 + )
144 +
145 + # Process the verified payload
146 + print(f"Received trigger: {event['trigger_slug']}")
147 + return 'OK', 200
148 + except WebhookSignatureVerificationError:
149 + return 'Unauthorized', 401
150 +```
151 +
152 +---
153 +
154 +[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/triggers.py#L629)
python/scripts/generate-docs.py new
+536
@@ -0,0 +1,536 @@
1 +#!/usr/bin/env python3
2 +"""
3 +Python SDK Documentation Generator
4 +
5 +Generates MDX documentation from Python source code using griffe.
6 +Output is written to the fumadocs content directory.
7 +
8 +Run: cd python && uv run --with griffe python scripts/generate-docs.py
9 +"""
10 +
11 +from __future__ import annotations
12 +
13 +import json
14 +import re
15 +import shutil
16 +from pathlib import Path
17 +from typing import Any
18 +
19 +try:
20 + import griffe
21 +except ImportError:
22 + print("Error: griffe not installed. Run: pip install griffe")
23 + raise SystemExit(1)
24 +
25 +# Paths
26 +SCRIPT_DIR = Path(__file__).parent
27 +PACKAGE_DIR = SCRIPT_DIR.parent
28 +OUTPUT_DIR = PACKAGE_DIR.parent / "fumadocs" / "content" / "reference" / "sdk-reference" / "python"
29 +
30 +# GitHub base URL for source links
31 +GITHUB_BASE = "https://github.com/composiohq/composio/blob/next/python"
32 +
33 +# Decorators to document
34 +DECORATORS_TO_DOCUMENT = [
35 + ("before_execute", "composio.core.models._modifiers"),
36 + ("after_execute", "composio.core.models._modifiers"),
37 + ("schema_modifier", "composio.core.models._modifiers"),
38 +]
39 +
40 +# Classes to skip (internal/helper classes)
41 +SKIP_CLASSES = {"WithLogger", "SDKConfig", "TProvider"}
42 +
43 +# Expected classes to document (maps class name -> property name on Composio)
44 +EXPECTED_CLASSES = {
45 + "Tools": "tools",
46 + "Toolkits": "toolkits",
47 + "Triggers": "triggers",
48 + "ConnectedAccounts": "connected_accounts",
49 + "AuthConfigs": "auth_configs",
50 +}
51 +
52 +# Modules to search for classes
53 +CLASS_MODULES = [
54 + "core.models.tools",
55 + "core.models.toolkits",
56 + "core.models.triggers",
57 + "core.models.connected_accounts",
58 + "core.models.auth_configs",
59 +]
60 +
61 +
62 +def to_kebab_case(name: str) -> str:
63 + """Convert PascalCase to kebab-case."""
64 + s1 = re.sub("(.)([A-Z][a-z]+)", r"\1-\2", name)
65 + return re.sub("([a-z0-9])([A-Z])", r"\1-\2", s1).lower()
66 +
67 +
68 +def escape_yaml_string(s: str) -> str:
69 + """Escape a string for YAML frontmatter."""
70 + if any(c in s for c in [':', '"', "'", '\n', '#', '{', '}']):
71 + return f'"{s.replace(chr(34), chr(92)+chr(34))}"'
72 + return s
73 +
74 +
75 +def get_source_link(obj: griffe.Object) -> str | None:
76 + """Get GitHub source link for an object."""
77 + if not hasattr(obj, "filepath") or not obj.filepath:
78 + return None
79 + try:
80 + rel_path = Path(obj.filepath).relative_to(PACKAGE_DIR)
81 + except ValueError:
82 + return None
83 + line = obj.lineno if hasattr(obj, "lineno") and obj.lineno else 1
84 + return f"{GITHUB_BASE}/{rel_path}#L{line}"
85 +
86 +
87 +def format_type(annotation: Any) -> str:
88 + """Format a type annotation to readable string."""
89 + if annotation is None:
90 + return "Any"
91 +
92 + type_str = str(annotation)
93 + # Clean up common prefixes
94 + type_str = type_str.replace("typing.", "").replace("typing_extensions.", "")
95 + type_str = type_str.replace("composio.client.types.", "")
96 + type_str = re.sub(r'\bt\.', '', type_str)
97 + type_str = re.sub(r'\bte\.', '', type_str) # typing_extensions alias
98 + type_str = re.sub(r'Optional\[([^\]]+)\]', r'\1 | None', type_str)
99 + # Clean up Unpack to just show the type
100 + type_str = re.sub(r'Unpack\[([^\]]+)\]', r'\1', type_str)
101 +
102 + # Truncate very long types
103 + if len(type_str) > 60:
104 + return type_str[:57] + "..."
105 + return type_str
106 +
107 +
108 +def parse_docstring(docstring: str | None) -> dict[str, Any]:
109 + """Parse docstring into components."""
110 + if not docstring:
111 + return {"description": "", "params": {}, "returns": None, "examples": []}
112 +
113 + lines = docstring.strip().split("\n")
114 + description_lines = []
115 + params: dict[str, str] = {}
116 + returns = None
117 + examples: list[str] = []
118 +
119 + section = "description"
120 + current_param = None
121 + example_lines: list[str] = []
122 +
123 + for line in lines:
124 + stripped = line.strip()
125 +
126 + # Check for :param name: description
127 + param_match = re.match(r":param\s+(\w+):\s*(.*)", stripped)
128 + if param_match:
129 + section = "params"
130 + current_param = param_match.group(1)
131 + params[current_param] = param_match.group(2)
132 + continue
133 +
134 + # Check for :returns: or :return:
135 + return_match = re.match(r":returns?:\s*(.*)", stripped)
136 + if return_match:
137 + section = "returns"
138 + returns = return_match.group(1)
139 + continue
140 +
141 + # Check for Example section
142 + if stripped.lower().startswith("example"):
143 + section = "examples"
144 + continue
145 +
146 + # Add to appropriate section
147 + if section == "description":
148 + description_lines.append(stripped)
149 + elif section == "params" and current_param and stripped:
150 + params[current_param] += " " + stripped
151 + elif section == "returns" and returns and stripped:
152 + returns += " " + stripped
153 + elif section == "examples":
154 + example_lines.append(line)
155 +
156 + if example_lines:
157 + examples.append("\n".join(example_lines).strip())
158 +
159 + return {
160 + "description": " ".join(description_lines).strip(),
161 + "params": params,
162 + "returns": returns,
163 + "examples": examples,
164 + }
165 +
166 +
167 +def extract_class_info(cls: griffe.Class, class_name: str, config: dict) -> dict[str, Any]:
168 + """Extract documentation from a class."""
169 + doc = parse_docstring(cls.docstring.value if cls.docstring else None)
170 +
171 + info = {
172 + "name": class_name,
173 + "access": config.get("access"),
174 + "source_link": get_source_link(cls),
175 + "description": doc["description"],
176 + "properties": [],
177 + "methods": [],
178 + }
179 +
180 + # Extract properties/attributes
181 + for name, member in cls.members.items():
182 + if name.startswith("_"):
183 + continue
184 + if isinstance(member, griffe.Attribute):
185 + attr_doc = member.docstring.value if member.docstring else ""
186 + info["properties"].append({
187 + "name": name,
188 + "type": format_type(member.annotation),
189 + "description": attr_doc.strip() if attr_doc else "",
190 + })
191 +
192 + # Extract methods
193 + for name, member in cls.members.items():
194 + if name.startswith("_"):
195 + continue
196 + if isinstance(member, griffe.Function):
197 + method_doc = parse_docstring(member.docstring.value if member.docstring else None)
198 +
199 + params = []
200 + for p in member.parameters:
201 + if p.name in ("self", "cls"):
202 + continue
203 + params.append({
204 + "name": p.name,
205 + "type": format_type(p.annotation),
206 + "optional": p.default is not None,
207 + "description": method_doc["params"].get(p.name, ""),
208 + })
209 +
210 + info["methods"].append({
211 + "name": name,
212 + "source_link": get_source_link(member),
213 + "description": method_doc["description"],
214 + "parameters": params,
215 + "return_type": format_type(member.returns),
216 + "return_description": method_doc["returns"],
217 + "examples": method_doc["examples"],
218 + })
219 +
220 + return info
221 +
222 +
223 +def generate_class_mdx(info: dict[str, Any], prop_to_class: dict[str, str] = None) -> str:
224 + """Generate MDX for a class."""
225 + lines = []
226 +
227 + # Frontmatter
228 + desc = info["description"].split("\n")[0] if info["description"] else f"{info['name']} class"
229 + if len(desc) > 150:
230 + desc = desc[:147] + "..."
231 +
232 + lines.append("---")
233 + lines.append(f"title: {info['name']}")
234 + lines.append(f"description: {escape_yaml_string(desc)}")
235 + lines.append("---")
236 + lines.append("")
237 +
238 + source_link = info.get("source_link", "")
239 +
240 + # Properties - as table for Composio class
241 + if prop_to_class:
242 + prop_rows = []
243 + for prop in info["properties"]:
244 + prop_name = prop["name"]
245 + if prop_name in prop_to_class:
246 + class_name = prop_to_class[prop_name]
247 + link = f"/reference/sdk-reference/python/{to_kebab_case(class_name)}"
248 + prop_rows.append(f"| [`{prop_name}`]({link}) | `{class_name}` |")
249 +
250 + if prop_rows:
251 + lines.append("## Properties")
252 + lines.append("")
253 + lines.append("| Name | Type |")
254 + lines.append("|------|------|")
255 + lines.extend(prop_rows)
256 + lines.append("")
257 +
258 + # Methods
259 + if info["methods"]:
260 + lines.append("## Methods")
261 + lines.append("")
262 +
263 + for method in info["methods"]:
264 + lines.append(f"### {method['name']}()")
265 + lines.append("")
266 +
267 + if method["description"]:
268 + lines.append(method["description"])
269 + lines.append("")
270 +
271 + # Signature
272 + params_str = ", ".join(
273 + f"{p['name']}: {p['type']}" + (" = ..." if p["optional"] else "")
274 + for p in method["parameters"]
275 + )
276 + ret_type = method["return_type"] if method["return_type"] != "Any" else ""
277 + sig = f"def {method['name']}({params_str})"
278 + if ret_type:
279 + sig += f" -> {ret_type}"
280 +
281 + lines.append("```python")
282 + lines.append(sig)
283 + lines.append("```")
284 + lines.append("")
285 +
286 + # Parameters
287 + if method["parameters"]:
288 + lines.append("**Parameters**")
289 + lines.append("")
290 + lines.append("| Name | Type |")
291 + lines.append("|------|------|")
292 + for p in method["parameters"]:
293 + opt = "?" if p["optional"] else ""
294 + safe_type = p["type"].replace("|", "\\|")
295 + lines.append(f"| `{p['name']}{opt}` | `{safe_type}` |")
296 + lines.append("")
297 +
298 + # Returns
299 + if method["return_type"] and method["return_type"] not in ("None", "Any"):
300 + ret_desc = method["return_description"] or ""
301 + lines.append("**Returns**")
302 + lines.append("")
303 + if ret_desc:
304 + lines.append(f"`{method['return_type']}` — {ret_desc}")
305 + else:
306 + lines.append(f"`{method['return_type']}`")
307 + lines.append("")
308 +
309 + # Examples
310 + if method["examples"]:
311 + lines.append("**Example**")
312 + lines.append("")
313 + for ex in method["examples"]:
314 + lines.append("```python")
315 + lines.append(ex)
316 + lines.append("```")
317 + lines.append("")
318 +
319 + lines.append("---")
320 + lines.append("")
321 +
322 + # Source link at bottom
323 + if source_link:
324 + lines.append(f"[View source]({source_link})")
325 + lines.append("")
326 +
327 + return "\n".join(lines)
328 +
329 +
330 +def generate_index_mdx(classes: list[dict], decorators: list[dict]) -> str:
331 + """Generate index page."""
332 +
333 + # Classes table
334 + class_rows = []
335 + for c in classes:
336 + link = f"/reference/sdk-reference/python/{to_kebab_case(c['name'])}"
337 + desc = c["description"][:80] + "..." if len(c["description"]) > 80 else c["description"]
338 + class_rows.append(f"| [`{c['name']}`]({link}) | {desc} |")
339 +
340 + # Decorators section
341 + dec_section = ""
342 + if decorators:
343 + dec_lines = ["## Decorators", ""]
344 + for d in decorators:
345 + dec_lines.append(f"### {d['name']}")
346 + dec_lines.append("")
347 + if d["description"]:
348 + dec_lines.append(d["description"])
349 + dec_lines.append("")
350 + if d["source_link"]:
351 + dec_lines.append(f"[View source]({d['source_link']})")
352 + dec_lines.append("")
353 + # Signature
354 + params = ", ".join(
355 + f"{p['name']}: {p['type']}" + (" = ..." if p["optional"] else "")
356 + for p in d["parameters"]
357 + )
358 + dec_lines.append("```python")
359 + dec_lines.append(f"@{d['name']}({params})")
360 + dec_lines.append("def my_modifier(...):")
361 + dec_lines.append(" ...")
362 + dec_lines.append("```")
363 + dec_lines.append("")
364 + dec_section = "\n".join(dec_lines)
365 +
366 + return f'''---
367 +title: Python SDK Reference
368 +description: API reference for the Composio Python SDK
369 +---
370 +
371 +# Python SDK Reference
372 +
373 +Complete API reference for the `composio` Python package.
374 +
375 +## Installation
376 +
377 +```bash
378 +pip install composio
379 +```
380 +
381 +Or with uv:
382 +
383 +```bash
384 +uv add composio
385 +```
386 +
387 +## Classes
388 +
389 +| Class | Description |
390 +|-------|-------------|
391 +{chr(10).join(class_rows)}
392 +
393 +## Quick Start
394 +
395 +```python
396 +from composio import Composio
397 +
398 +composio = Composio(api_key="your-api-key")
399 +
400 +# Get tools for a user
401 +tools = composio.tools.get("user-123", toolkits=["github"])
402 +
403 +# Execute a tool
404 +result = composio.tools.execute(
405 + "GITHUB_GET_REPOS",
406 + arguments={{"owner": "composio"}},
407 + user_id="user-123"
408 +)
409 +```
410 +
411 +{dec_section}
412 +'''
413 +
414 +
415 +def main():
416 + print("Starting Python SDK documentation generation...\n")
417 + print(f"Output: {OUTPUT_DIR}\n")
418 +
419 + # Clean output
420 + if OUTPUT_DIR.exists():
421 + shutil.rmtree(OUTPUT_DIR)
422 + OUTPUT_DIR.mkdir(parents=True)
423 +
424 + # Load package
425 + print("Loading composio package...")
426 + try:
427 + package = griffe.load("composio", search_paths=[str(PACKAGE_DIR)])
428 + except Exception as e:
429 + print(f"Error: {e}")
430 + raise SystemExit(1)
431 +
432 + # Find Composio class
433 + composio_cls = package.members["sdk"].members["Composio"]
434 + print(" Found Composio class")
435 +
436 + # Discover classes from EXPECTED_CLASSES
437 + classes_to_doc = {"Composio": {"cls": composio_cls, "access": None, "prop": None}}
438 + prop_to_class = {} # Maps property name -> class name
439 +
440 + for module_name in CLASS_MODULES:
441 + try:
442 + parts = module_name.split(".")
443 + current = package
444 + for part in parts:
445 + current = current.members[part]
446 +
447 + # Find expected classes in this module
448 + for class_name, prop_name in EXPECTED_CLASSES.items():
449 + if class_name in current.members:
450 + cls = current.members[class_name]
451 + if isinstance(cls, griffe.Class):
452 + classes_to_doc[class_name] = {
453 + "cls": cls,
454 + "access": f"composio.{prop_name}",
455 + "prop": prop_name,
456 + }
457 + prop_to_class[prop_name] = class_name
458 + print(f" Found {class_name} (via composio.{prop_name})")
459 + except (KeyError, AttributeError):
460 + continue
461 +
462 + # Generate docs for each class
463 + documented_classes = []
464 +
465 + for class_name, config in classes_to_doc.items():
466 + cls = config["cls"]
467 + print(f" Processing {class_name}...")
468 +
469 + info = extract_class_info(cls, class_name, {"access": config["access"]})
470 +
471 + # Only Composio gets prop_to_class for linking
472 + if class_name == "Composio":
473 + mdx = generate_class_mdx(info, prop_to_class)
474 + else:
475 + mdx = generate_class_mdx(info, None)
476 +
477 + file_path = OUTPUT_DIR / f"{to_kebab_case(class_name)}.mdx"
478 + file_path.write_text(mdx)
479 +
480 + documented_classes.append({
481 + "name": class_name,
482 + "description": info["description"] or f"{class_name} class",
483 + })
484 +
485 + # Process decorators
486 + decorators = []
487 + for dec_name, dec_module in DECORATORS_TO_DOCUMENT:
488 + module_path = dec_module.split(".")
489 + current = package
490 +
491 + for part in module_path[1:]:
492 + if part in current.members:
493 + current = current.members[part]
494 +
495 + if dec_name in current.members:
496 + func = current.members[dec_name]
497 + if isinstance(func, griffe.Function):
498 + print(f" Processing decorator {dec_name}...")
499 + doc = parse_docstring(func.docstring.value if func.docstring else None)
500 +
501 + params = []
502 + for p in func.parameters:
503 + if p.name in ("self", "cls"):
504 + continue
505 + params.append({
506 + "name": p.name,
507 + "type": format_type(p.annotation),
508 + "optional": p.default is not None,
509 + "description": doc["params"].get(p.name, ""),
510 + })
511 +
512 + decorators.append({
513 + "name": dec_name,
514 + "source_link": get_source_link(func),
515 + "description": doc["description"],
516 + "parameters": params,
517 + })
518 +
519 + # Generate index
520 + index_content = generate_index_mdx(documented_classes, decorators)
521 + (OUTPUT_DIR / "index.mdx").write_text(index_content)
522 +
523 + # Generate meta.json
524 + meta = {
525 + "title": "Python SDK",
526 + "pages": [to_kebab_case(c["name"]) for c in documented_classes],
527 + }
528 + (OUTPUT_DIR / "meta.json").write_text(json.dumps(meta, indent=2))
529 +
530 + print(f"\nDone! Generated {len(documented_classes)} class docs + index")
531 + print(f" Classes: {', '.join(c['name'] for c in documented_classes)}")
532 + print(f" Decorators: {', '.join(d['name'] for d in decorators)}")
533 +
534 +
535 +if __name__ == "__main__":
536 + main()