Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
docs: address review feedback on code example options
- Close Markdown language groups with <!-- end-languages --> so shared prose stays visible for every option in FAQ and KB tabs - Merge oneOf/anyOf alternatives into the parent schema and bound circular unions when generating request samples - Opt into the version check bypass in migration-guide modifier examples - Enable scoped auto-upload in the Gmail attachment examples - Skip lifecycle scripts in the docs Python snippets workflow - Bump filelock to 4.2.4 (virtualenv 21.14.11) for pip-audit advisories
Brendan O'Leary committed
Oct 23, 2026 at 23:57 UTC
5ef7cb1e413d45002467d56c5bc8ad1d392c90f4
24 files changed
+206
-31
.github/workflows/docs-python-snippets.yml
+2
-1
@@ -50,8 +50,9 @@ jobs:
50
restore-keys: |
51
${{ runner.os }}-bun-
52
53
+ # The checker needs no generated files or native install hooks.
54
- name: Install dependencies
54
- run: bun install --frozen-lockfile
55
+ run: bun install --frozen-lockfile --ignore-scripts
56
57
- name: Check real Python helper regressions
58
run: bun scripts/python-snippets/test-helper.ts
docs/agent-guidance/context/code-examples.md
+2
@@ -57,6 +57,8 @@ curl ...
57
58
The FAQ and KB renderers turn these headings into persistent language tabs. Agent Markdown keeps the labels and all variants. For an unavailable SDK endpoint, a `> [!NOTE]` block under that language heading becomes an SDK-gap Callout.
59
60
+The last option runs until the next heading at the same or a higher level. When prose after the group applies to every language, close the group with `<!-- end-languages -->` on its own line before that prose. Without the marker, the renderers hide the shared prose inside the last tab.
61
+
62
## Exceptions and SDK gaps
63
64
Use MDX comments in `.mdx` files and HTML comments in `.md`. A marker must be an actual comment node, not text inside code, an attribute, a string, or inline code. Local markers attach only across whitespace.
docs/app/llms.mdx/[[...slug]]/route.ts
+10
-1
@@ -260,7 +260,16 @@ function generateSampleValue(schema: OpenAPISchema, depth = 0): unknown {
260
if (schema.default !== undefined) return schema.default;
261
if (schema.enum && schema.enum.length > 0) return schema.enum[0];
262
const alternatives = schema.oneOf ?? schema.anyOf;
263
- if (alternatives?.length) return generateSampleValue(alternatives[0], depth);
263
+ if (alternatives?.length) {
264
+ // An alternative applies alongside its parent, so merge it instead of
265
+ // discarding the parent's type and properties. Unions can be circular.
266
+ const { oneOf: _oneOf, anyOf: _anyOf, ...parent } = schema;
267
+ const alternative = alternatives[0];
268
+ const properties = parent.properties || alternative.properties
269
+ ? { ...parent.properties, ...alternative.properties }
270
+ : undefined;
271
+ return generateSampleValue({ ...parent, ...alternative, properties }, depth + 1);
272
+ }
273
274
switch (schema.type) {
275
case 'string':
docs/content/docs/migration-guide/new-sdk.mdx
+4
@@ -515,6 +515,7 @@ result_1 = composio.tools.execute(
515
"HACKERNEWS_GET_LATEST_POSTS",
516
arguments={"size": 10},
517
version="latest",
518
+ dangerously_skip_version_check=True, # required when running "latest"
519
user_id=user_id,
520
modifiers=[before_execute_modifier],
521
)
@@ -532,6 +533,7 @@ const result_1 = await composio.tools.execute(
533
userId,
534
arguments: { size: 10 },
535
version: 'latest',
536
+ dangerouslySkipVersionCheck: true, // required when running "latest"
537
},
538
{
539
beforeExecute: ({ toolSlug, toolkitSlug, params }) => {
@@ -579,6 +581,7 @@ result_2 = composio.tools.execute(
581
"HACKERNEWS_GET_USER",
582
arguments={"username": "pg"},
583
version="latest",
584
+ dangerously_skip_version_check=True, # required when running "latest"
585
user_id=user_id,
586
modifiers=[after_execute_modifier],
587
)
@@ -598,6 +601,7 @@ const result_2 = await composio.tools.execute(
601
userId,
602
arguments: { username: 'pg' },
603
version: 'latest',
604
+ dangerouslySkipVersionCheck: true, // required when running "latest"
605
},
606
{
607
afterExecute: ({ toolSlug, toolkitSlug, result }) => {
docs/content/kb/guide/mcp-tool-router-sessions.mdx
+4
-2
@@ -47,12 +47,14 @@ await composio.sessions.delete("trs_1a2b3c4d5e6f");
47
curl -X DELETE https://backend.composio.dev/api/v3.1/tool_router/session/trs_1a2b3c4d5e6f \
48
-H "x-api-key: $COMPOSIO_API_KEY"
49
```
50
-
51
-Deletion takes effect immediately. A deleted, missing, or inaccessible session returns 404 when retrieved; deleting a session does not delete its users, auth configs, or connected accounts.
50
</Tab>
51
52
</Tabs>
53
54
+
55
+
56
+Deletion takes effect immediately. A deleted, missing, or inaccessible session returns 404 when retrieved; deleting a session does not delete its users, auth configs, or connected accounts.
57
+
58
## Select among multiple accounts with an alias or account ID
59
60
When a toolkit has multiple connected accounts, assign clear aliases such as `work`, `personal`, or `primary`, then pass the alias as the execution `account`. Without an alias, use the generated account ID returned by connection discovery.
docs/content/kb/guide/platform-session-tool-policies.mdx
+15
-9
@@ -50,14 +50,16 @@ curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
50
-H "Content-Type: application/json" \
51
-d '{"user_id":"user_123","tags":{"enable":["readOnlyHint"],"disable":["destructiveHint"]}}'
52
```
53
+</Tab>
54
+
55
+</Tabs>
56
+
57
+
58
59
Behavior tags describe tool behavior. Inspect the tools the session exposes
60
before rollout, especially when a workflow handles sensitive data.
61
62
- [Filter tools by tags](https://docs.composio.dev/docs/configuring-sessions#filtering-tools-by-tags)
58
-</Tab>
59
-
60
-</Tabs>
63
64
## Use exact tool allowlists for the narrowest policy
65
@@ -100,12 +102,14 @@ curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
102
-H "Content-Type: application/json" \
103
-d '{"user_id":"user_123","tools":{"gmail":{"enable":["GMAIL_FETCH_EMAILS"]},"github":{"enable":["GITHUB_GET_AN_ISSUE"]}}}'
104
```
103
-
104
-- [Enable and disable specific tools](https://docs.composio.dev/docs/configuring-sessions#enabling-or-disabling-specific-tools)
105
</Tab>
106
107
</Tabs>
108
109
+
110
+
111
+- [Enable and disable specific tools](https://docs.composio.dev/docs/configuring-sessions#enabling-or-disabling-specific-tools)
112
+
113
## Combine provider scopes with session tool restrictions
114
115
OAuth scopes control what the provider grants to a connected account. Session
@@ -162,12 +166,14 @@ curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
166
-H "Content-Type: application/json" \
167
-d '{"user_id":"user_123","tags":["readOnlyHint"],"tools":{"github":{"tags":{"disable":["destructiveHint"]}},"gmail":{"tags":["readOnlyHint"]}}}'
168
```
165
-
166
-- [Toolkit-specific tag filters](https://docs.composio.dev/docs/configuring-sessions#filtering-tools-by-tags)
169
</Tab>
170
171
</Tabs>
172
173
+
174
+
175
+- [Toolkit-specific tag filters](https://docs.composio.dev/docs/configuring-sessions#filtering-tools-by-tags)
176
+
177
## Disable the session sandbox when the workflow does not need code execution
178
179
Session tool filters govern app tools. Sessions also include remote sandbox
@@ -205,10 +211,10 @@ curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
211
-H "Content-Type: application/json" \
212
-d '{"user_id":"user_123","tags":["readOnlyHint"],"workbench":{"enable":false}}'
213
```
208
-
209
-- [Disable the session sandbox](https://docs.composio.dev/docs/configuring-sessions#disabling-the-sandbox)
214
</Tab>
215
216
</Tabs>
217
218
219
+
220
+- [Disable the session sandbox](https://docs.composio.dev/docs/configuring-sessions#disabling-the-sandbox)
docs/content/kb/guide/toolkits-microsoft-teams.mdx
+8
-4
@@ -67,12 +67,14 @@ The TypeScript SDK does not select the legacy `/api/v3` metadata route. Use the
67
curl --globoff 'https://backend.composio.dev/api/v3/tools/MICROSOFT_TEAMS_TEAMS_GET_MESSAGE' \
68
-H "x-api-key: $COMPOSIO_API_KEY"
69
```
70
-
71
-Expected stale response includes `version: "00000000_00"` and `scopes: ["ChannelMessage.Read.Group"]`.
70
</Tab>
71
72
</Tabs>
73
74
+
75
+
76
+Expected stale response includes `version: "00000000_00"` and `scopes: ["ChannelMessage.Read.Group"]`.
77
+
78
### Fetch current tool metadata
79
80
<Tabs groupId="language" items={["Python","TypeScript","API"]} persist>
@@ -102,12 +104,14 @@ console.log(tool.scopes);
104
curl --globoff 'https://backend.composio.dev/api/v3.1/tools/MICROSOFT_TEAMS_GET_CHANNEL_MESSAGE?toolkit_versions%5Bmicrosoft_teams%5D=latest' \
105
-H "x-api-key: $COMPOSIO_API_KEY"
106
```
105
-
106
-Expected clean response includes `ChannelMessage.Read.All`, not `ChannelMessage.Read.Group`.
107
</Tab>
108
109
</Tabs>
110
111
+
112
+
113
+Expected clean response includes `ChannelMessage.Read.All`, not `ChannelMessage.Read.Group`.
114
+
115
## Connect Teams through MCP and Tool Router
116
117
**Match the MCP URL user ID to the connected account.** For Microsoft Teams MCP, the user ID in the MCP server URL/query params must match the user ID attached to the connected account. If the connection is bound to an email/GUID, use that value in the MCP URL or create a new server/connection with the desired user ID.
docs/content/kb/guide/toolkits-sharepoint.mdx
+10
-6
@@ -49,6 +49,11 @@ curl --fail-with-body \
49
'https://backend.composio.dev/api/v3.1/toolkits/sharepoint_graph' \
50
-H "x-api-key: $COMPOSIO_API_KEY"
51
```
52
+</Tab>
53
+
54
+</Tabs>
55
+
56
+
57
58
Find the `OAUTH2` auth scheme and inspect `fields.auth_config_creation` and
59
`fields.connected_account_initiation`. The `issuer` field appears under
@@ -57,9 +62,6 @@ Find the `OAUTH2` auth scheme and inspect `fields.auth_config_creation` and
62
To apply the same tenant ID to new connections, [update your custom auth
63
config](/reference/api-reference/auth-configs/patchAuthConfigsByNanoid) with
64
`shared_credentials.issuer`:
60
-</Tab>
61
-
62
-</Tabs>
65
66
### Update the auth config
67
@@ -107,15 +109,17 @@ curl --fail-with-body -X PATCH \
109
}
110
}'
111
```
112
+</Tab>
113
+
114
+</Tabs>
115
+
116
+
117
118
Replace `<AUTH_CONFIG_ID>` with your SharePoint Graph custom auth config ID.
119
Every new connection created through this auth config inherits the tenant ID.
120
Create a new connection using that config and complete Microsoft sign-in to use
121
the tenant-specific endpoint. This recipe configures new connections; it does
122
not migrate existing connected accounts.
116
-</Tab>
117
-
118
-</Tabs>
123
124
## SharePoint REST APIs and SharePoint Graph are separate API families
125
docs/content/toolkits/faq/gmail.md
+19
-1
@@ -34,12 +34,21 @@ Google enforces per-minute and daily request quotas. If you're using Composio's
34
35
## How do I send an email with an attachment?
36
37
-Save the attachment as `report.pdf` beside your script. The SDKs upload the local file automatically; the API option shows the same staging requests explicitly. The `user-123` identity must already have an active Gmail connection.
37
+Save the attachment as `report.pdf` in the directory you run the example from. Automatic file upload is off by default, so the SDK examples enable it and allow uploads only from that directory; the API option shows the same staging requests explicitly. The `user-123` identity must already have an active Gmail connection.
38
39
These examples deliberately use `latest` and opt out of the SDK version guard. Pin a tested [toolkit version](/docs/tools-direct/toolkit-versioning) in production.
40
41
### Python
42
```python
43
+import os
44
+
45
+from composio import Composio
46
+
47
+composio = Composio(
48
+ dangerously_allow_auto_upload_download_files=True,
49
+ file_upload_dirs=[os.getcwd()],
50
+)
51
+
52
result = composio.tools.execute(
53
slug="GMAIL_SEND_EMAIL",
54
user_id="user-123",
@@ -56,6 +65,13 @@ result = composio.tools.execute(
65
66
### TypeScript
67
```typescript
68
+import { Composio } from "@composio/core";
69
+
70
+const composio = new Composio({
71
+ dangerouslyAllowAutoUploadDownloadFiles: true,
72
+ fileUploadDirs: [process.cwd()],
73
+});
74
+
75
const result = await composio.tools.execute("GMAIL_SEND_EMAIL", {
76
userId: "user-123",
77
version: "latest",
@@ -102,6 +118,8 @@ curl --fail-with-body -X POST https://backend.composio.dev/api/v3.1/tools/execut
118
}'
119
```
120
121
+<!-- end-languages -->
122
+
123
This approach works for any tool whose parameters accept file uploads. See [Automatic File Handling](/docs/tools-direct/executing-tools#automatic-file-handling) for more details.
124
125
## Why can Gmail filter setup show an app-blocked error?
docs/content/toolkits/faq/notion.md
+2
@@ -99,6 +99,8 @@ curl -s https://backend.composio.dev/api/v3.1/webhook_endpoints/we_123 \
99
-H "x-api-key: $COMPOSIO_API_KEY" | jq -er '.data.webhook_signing_secret // error("Notion has not sent a verification token yet")'
100
```
101
102
+<!-- end-languages -->
103
+
104
Paste the token back into Notion's verify field to complete setup. Continue with [Creating triggers](/docs/setting-up-triggers/creating-triggers#create-the-trigger).
105
106
## Notion database trigger fires for new pages, not updates
docs/kb/articles/mcp-tool-router-sessions.md
+2
@@ -36,6 +36,8 @@ curl -X DELETE https://backend.composio.dev/api/v3.1/tool_router/session/trs_1a2
36
-H "x-api-key: $COMPOSIO_API_KEY"
37
```
38
39
+<!-- end-languages -->
40
+
41
Deletion takes effect immediately. A deleted, missing, or inaccessible session returns 404 when retrieved; deleting a session does not delete its users, auth configs, or connected accounts.
42
43
## Select among multiple accounts with an alias or account ID
docs/kb/articles/platform-health-endpoints.md
+6
@@ -38,6 +38,8 @@ Success:
38
}
39
```
40
41
+<!-- end-languages -->
42
+
43
This only confirms that Apollo can serve the request. It does not check downstream dependencies.
44
45
### Deep dependency health
@@ -62,6 +64,8 @@ curl -sS "$COMPOSIO_BASE_URL/api/deep_healthz" \
64
-H "x-composio-admin-token: $COMPOSIO_ADMIN_TOKEN" | jq
65
```
66
67
+<!-- end-languages -->
68
+
69
Example:
70
71
Apollo deep health checks:
@@ -131,6 +135,8 @@ curl -sS "$THERMOS_BASE_URL/api/health/deep" \
135
-H "x-composio-admin-token: $COMPOSIO_ADMIN_TOKEN" | jq
136
```
137
138
+<!-- end-languages -->
139
+
140
Example:
141
142
Required services are `database`, `toolkit_registry_database`, and `temporal`.
docs/kb/articles/platform-session-tool-policies.md
+8
@@ -39,6 +39,8 @@ curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
39
-d '{"user_id":"user_123","tags":{"enable":["readOnlyHint"],"disable":["destructiveHint"]}}'
40
```
41
42
+<!-- end-languages -->
43
+
44
Behavior tags describe tool behavior. Inspect the tools the session exposes
45
before rollout, especially when a workflow handles sensitive data.
46
@@ -85,6 +87,8 @@ curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
87
-d '{"user_id":"user_123","tools":{"gmail":{"enable":["GMAIL_FETCH_EMAILS"]},"github":{"enable":["GITHUB_GET_AN_ISSUE"]}}}'
88
```
89
90
+<!-- end-languages -->
91
+
92
- [Enable and disable specific tools](https://docs.composio.dev/docs/configuring-sessions#enabling-or-disabling-specific-tools)
93
94
## Combine provider scopes with session tool restrictions
@@ -143,6 +147,8 @@ curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
147
-d '{"user_id":"user_123","tags":["readOnlyHint"],"tools":{"github":{"tags":{"disable":["destructiveHint"]}},"gmail":{"tags":["readOnlyHint"]}}}'
148
```
149
150
+<!-- end-languages -->
151
+
152
- [Toolkit-specific tag filters](https://docs.composio.dev/docs/configuring-sessions#filtering-tools-by-tags)
153
154
## Disable the session sandbox when the workflow does not need code execution
@@ -182,4 +188,6 @@ curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
188
-d '{"user_id":"user_123","tags":["readOnlyHint"],"workbench":{"enable":false}}'
189
```
190
191
+<!-- end-languages -->
192
+
193
- [Disable the session sandbox](https://docs.composio.dev/docs/configuring-sessions#disabling-the-sandbox)
docs/kb/articles/toolkits-microsoft-teams.md
+4
@@ -51,6 +51,8 @@ curl --globoff 'https://backend.composio.dev/api/v3/tools/MICROSOFT_TEAMS_TEAMS_
51
-H "x-api-key: $COMPOSIO_API_KEY"
52
```
53
54
+<!-- end-languages -->
55
+
56
Expected stale response includes `version: "00000000_00"` and `scopes: ["ChannelMessage.Read.Group"]`.
57
58
### Fetch current tool metadata
@@ -82,6 +84,8 @@ curl --globoff 'https://backend.composio.dev/api/v3.1/tools/MICROSOFT_TEAMS_GET_
84
-H "x-api-key: $COMPOSIO_API_KEY"
85
```
86
87
+<!-- end-languages -->
88
+
89
Expected clean response includes `ChannelMessage.Read.All`, not `ChannelMessage.Read.Group`.
90
91
## Connect Teams through MCP and Tool Router
docs/kb/articles/toolkits-sharepoint.md
+4
@@ -37,6 +37,8 @@ curl --fail-with-body \
37
-H "x-api-key: $COMPOSIO_API_KEY"
38
```
39
40
+<!-- end-languages -->
41
+
42
Find the `OAUTH2` auth scheme and inspect `fields.auth_config_creation` and
43
`fields.connected_account_initiation`. The `issuer` field appears under
44
`connected_account_initiation`.
@@ -91,6 +93,8 @@ curl --fail-with-body -X PATCH \
93
}'
94
```
95
96
+<!-- end-languages -->
97
+
98
Replace `<AUTH_CONFIG_ID>` with your SharePoint Graph custom auth config ID.
99
Every new connection created through this auth config inherits the tenant ID.
100
Create a new connection using that config and complete Microsoft sign-in to use
docs/kb/source/mcp/tool-router-sessions/public.md
+2
@@ -50,6 +50,8 @@ curl -X DELETE https://backend.composio.dev/api/v3.1/tool_router/session/trs_1a2
50
-H "x-api-key: $COMPOSIO_API_KEY"
51
```
52
53
+<!-- end-languages -->
54
+
55
Deletion takes effect immediately. A deleted, missing, or inaccessible session returns 404 when retrieved; deleting a session does not delete its users, auth configs, or connected accounts.
56
57
## Select among multiple accounts with an alias or account ID
docs/kb/source/platform/health-endpoints/public.md
+6
@@ -50,6 +50,8 @@ Success:
50
}
51
```
52
53
+<!-- end-languages -->
54
+
55
This only confirms that Apollo can serve the request. It does not check downstream dependencies.
56
57
### Deep dependency health
@@ -74,6 +76,8 @@ curl -sS "$COMPOSIO_BASE_URL/api/deep_healthz" \
76
-H "x-composio-admin-token: $COMPOSIO_ADMIN_TOKEN" | jq
77
```
78
79
+<!-- end-languages -->
80
+
81
Example:
82
83
Apollo deep health checks:
@@ -143,6 +147,8 @@ curl -sS "$THERMOS_BASE_URL/api/health/deep" \
147
-H "x-composio-admin-token: $COMPOSIO_ADMIN_TOKEN" | jq
148
```
149
150
+<!-- end-languages -->
151
+
152
Example:
153
154
Required services are `database`, `toolkit_registry_database`, and `temporal`.
docs/kb/source/platform/session-tool-policies/public.md
+8
@@ -55,6 +55,8 @@ curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
55
-d '{"user_id":"user_123","tags":{"enable":["readOnlyHint"],"disable":["destructiveHint"]}}'
56
```
57
58
+<!-- end-languages -->
59
+
60
Behavior tags describe tool behavior. Inspect the tools the session exposes
61
before rollout, especially when a workflow handles sensitive data.
62
@@ -101,6 +103,8 @@ curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
103
-d '{"user_id":"user_123","tools":{"gmail":{"enable":["GMAIL_FETCH_EMAILS"]},"github":{"enable":["GITHUB_GET_AN_ISSUE"]}}}'
104
```
105
106
+<!-- end-languages -->
107
+
108
- [Enable and disable specific tools](https://docs.composio.dev/docs/configuring-sessions#enabling-or-disabling-specific-tools)
109
110
An Auth Config's tool access allowlist applies when tools are listed through
@@ -165,6 +169,8 @@ curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
169
-d '{"user_id":"user_123","tags":["readOnlyHint"],"tools":{"github":{"tags":{"disable":["destructiveHint"]}},"gmail":{"tags":["readOnlyHint"]}}}'
170
```
171
172
+<!-- end-languages -->
173
+
174
- [Toolkit-specific tag filters](https://docs.composio.dev/docs/configuring-sessions#filtering-tools-by-tags)
175
176
## Disable the session sandbox when the workflow does not need code execution
@@ -204,4 +210,6 @@ curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
210
-d '{"user_id":"user_123","tags":["readOnlyHint"],"workbench":{"enable":false}}'
211
```
212
213
+<!-- end-languages -->
214
+
215
- [Disable the session sandbox](https://docs.composio.dev/docs/configuring-sessions#disabling-the-sandbox)
docs/kb/source/toolkits/microsoft_teams/public.md
+4
@@ -58,6 +58,8 @@ curl --globoff 'https://backend.composio.dev/api/v3/tools/MICROSOFT_TEAMS_TEAMS_
58
-H "x-api-key: $COMPOSIO_API_KEY"
59
```
60
61
+<!-- end-languages -->
62
+
63
Expected stale response includes `version: "00000000_00"` and `scopes: ["ChannelMessage.Read.Group"]`.
64
65
### Fetch current tool metadata
@@ -89,6 +91,8 @@ curl --globoff 'https://backend.composio.dev/api/v3.1/tools/MICROSOFT_TEAMS_GET_
91
-H "x-api-key: $COMPOSIO_API_KEY"
92
```
93
94
+<!-- end-languages -->
95
+
96
Expected clean response includes `ChannelMessage.Read.All`, not `ChannelMessage.Read.Group`.
97
98
## `MICROSOFT_TEAMS_CHATS_GET_ALL_CHATS` and `MICROSOFT_TEAMS_CREATE_MEETING` can work with delegated user scopes
docs/lib/example-document.ts
+14
-1
@@ -42,7 +42,14 @@ export type MarkdownLanguageGroup = {
42
tabs: { value: string; source: string; line: number }[];
43
};
44
45
-/** Plain Markdown uses consecutive Python / TypeScript / API headings. */
45
+const isEndLanguages = (node: RootContent | undefined) =>
46
+ node?.type === 'html' && /^<!--\s*end-languages\s*-->$/.test(node.value.trim());
47
+
48
+/**
49
+ * Plain Markdown uses consecutive Python / TypeScript / API headings. The last
50
+ * option runs to the next heading unless `<!-- end-languages -->` closes the
51
+ * group first; the marker belongs to neither the options nor the shared prose.
52
+ */
53
export function markdownLanguageGroups(source: string): MarkdownLanguageGroup[] {
54
const nodes = parseExampleDocument(source, 'example.md').children;
55
const groups: MarkdownLanguageGroup[] = [];
@@ -64,6 +71,7 @@ export function markdownLanguageGroups(source: string): MarkdownLanguageGroup[]
71
while (end < nodes.length) {
72
const next = nodes[end];
73
if (next.type === 'heading' && next.depth <= first.depth) break;
74
+ if (isEndLanguages(next)) break;
75
end++;
76
}
77
const contentStart = heading.position?.end.offset ?? 0;
@@ -71,6 +79,11 @@ export function markdownLanguageGroups(source: string): MarkdownLanguageGroup[]
79
group.tabs.push({ value: toString(heading), source: source.slice(contentStart, contentEnd), line: heading.position?.start.line ?? 1 });
80
group.end = contentEnd;
81
cursor = end;
82
+ if (isEndLanguages(nodes[end])) {
83
+ group.end = nodes[end].position?.end.offset ?? contentEnd;
84
+ cursor = end + 1;
85
+ break;
86
+ }
87
}
88
groups.push(group);
89
index = cursor - 1;
docs/tests/static/code-examples.test.ts
+8
@@ -100,6 +100,14 @@ describe('Markdown options and agent output', () => {
100
expect(faq[1].question).toBe('Next question');
101
});
102
103
+ test('end-languages keeps shared prose after the group visible for every option', () => {
104
+ const shared = source.replace('\n\n## Next question', '\n\n<!-- end-languages -->\n\nShared follow-up.\n\n## Next question');
105
+ expect(violations(shared, 'faq.md')).toEqual([]);
106
+ const [options, after] = parseToolkitFaq(shared)[0].answer.slice(1);
107
+ expect(options.type === 'languages' && options.tabs.some((item) => item.html.includes('Shared follow-up'))).toBe(false);
108
+ expect(after).toEqual({ type: 'html', html: '<p>Shared follow-up.</p>' });
109
+ });
110
+
111
test('a Markdown group exception cannot exempt the following operation', () => {
112
const pair = `### Python\n\n${python}\n\n### TypeScript\n\n${typescript}\n`;
113
const local = `<!-- code-example: no-api reason="local schema transformation" -->\n${pair}\n## Remote operation\n\n${pair}`;
docs/tests/static/kb-generation.test.ts
+23
@@ -142,6 +142,29 @@ describe('public KB content generation', () => {
142
expect(mdx).not.toContain('```text');
143
});
144
145
+ test('end-languages moves shared prose after the generated Tabs', () => {
146
+ const mdx = markdownForMdx([
147
+ '### Python',
148
+ '```python',
149
+ 'print("python option")',
150
+ '```',
151
+ '### TypeScript',
152
+ '```typescript',
153
+ 'console.log("typescript option");',
154
+ '```',
155
+ '### API',
156
+ '```bash',
157
+ 'curl https://backend.composio.dev/api/v3.1/toolkits',
158
+ '```',
159
+ '',
160
+ '<!-- end-languages -->',
161
+ '',
162
+ 'Shared follow-up.',
163
+ ].join('\n'));
164
+ expect(mdx).toMatch(/<\/Tabs>\s+Shared follow-up\.$/);
165
+ expect(mdx).not.toContain('end-languages');
166
+ });
167
+
168
test('turns Markdown SDK-gap notes into Callouts without leaking validation metadata into rendered prose', () => {
169
const source = [
170
'#### Python',
docs/tests/static/llms-openapi.test.ts
+34
@@ -214,6 +214,40 @@ describe("LLM OpenAPI markdown", () => {
214
"- `tree` (array<array<array<array<array<...>>>>>):",
215
);
216
});
217
+
218
+ test("union request samples keep the parent schema and bound circular unions", async () => {
219
+ const renderBody = async (schema: Record<string, unknown>, schemas: Record<string, unknown> = {}) => {
220
+ const markdown = await openapiPageToMarkdown({
221
+ url: "/reference/api-reference/test/postTest",
222
+ data: {
223
+ title: "Post test",
224
+ getOpenAPIPageProps: () => ({
225
+ payload: { bundled: {
226
+ paths: { "/v3.1/test": { post: {
227
+ requestBody: { content: { "application/json": { schema } } },
228
+ responses: { 200: { description: "Success" } },
229
+ } } },
230
+ components: { schemas },
231
+ } },
232
+ operations: [{ path: "/v3.1/test", method: "POST" }],
233
+ }),
234
+ },
235
+ });
236
+ const curl = [...markdown.matchAll(/```bash\n([\s\S]*?)```/g)][0][1];
237
+ return JSON.parse(wordText(parseCurlCommands(curl)[0].data[0].value));
238
+ };
239
+
240
+ expect(await renderBody({
241
+ type: "object",
242
+ properties: { name: { type: "string" }, id: { type: "integer" } },
243
+ oneOf: [{ required: ["name"] }, { required: ["id"] }],
244
+ })).toEqual({ name: "string", id: 1 });
245
+
246
+ expect(await renderBody(
247
+ { $ref: "#/components/schemas/Node" },
248
+ { Node: { oneOf: [{ $ref: "#/components/schemas/Node" }, { type: "string" }] } },
249
+ )).toBe("...");
250
+ });
251
});
252
253
/**
uv.lock
+7
-6
@@ -1286,11 +1286,11 @@ wheels = [
1286
1287
[[package]]
1288
name = "filelock"
1289
-version = "3.32.7"
1289
+version = "4.2.4"
1290
source = { registry = "https://pypi.org/simple" }
1291
-sdist = { url = "https://files.pythonhosted.org/packages/0f/59/e19834834cb01a32febfbb0f8a23a9088088f5d45991824ff2bc3b5e8acb/filelock-3.32.7.tar.gz", hash = "sha256:37b8a3d9811b0f9aef7e5ec5c71bb320de52df51e6ca9bcd6f5ad81187660da7", size = 225154, upload-time = "2026-09-16T00:24:20.907Z" }
1291
+sdist = { url = "https://files.pythonhosted.org/packages/d8/28/3893324bcadf8f89b1616637468d766af3f625008c0735bf704fdfa86617/filelock-4.2.4.tar.gz", hash = "sha256:c6d8663535e1650ee430507b4ffbac7b464dd64b7647ea0112a9f406499d163d", size = 652444, upload-time = "2026-10-19T01:57:51.001Z" }
1292
wheels = [
1293
- { url = "https://files.pythonhosted.org/packages/15/df/31098c5aeb4d966b553641472bd55fcf5fdfac953549894b8a765ba44e91/filelock-3.32.7-py3-none-any.whl", hash = "sha256:65ff0d0190ea42038b32bda4b77834fb05be2cad4c5b9b01aa4dfb3614536e52", size = 100157, upload-time = "2026-09-16T00:24:19.543Z" },
1293
+ { url = "https://files.pythonhosted.org/packages/e0/1b/5e74289a1878e666bb4b65fe5805a04cafcac2aa5f519ef1ead67ef91c56/filelock-4.2.4-py3-none-any.whl", hash = "sha256:301241438c57936ef93f4243a94f2559022268bfcf9b375a9a72eb0f8db8358e", size = 162475, upload-time = "2026-10-19T01:57:49.419Z" },
1294
]
1295
1296
[[package]]
@@ -5678,17 +5678,18 @@ wheels = [
5678
5679
[[package]]
5680
name = "virtualenv"
5681
-version = "21.7.14"
5681
+version = "21.14.11"
5682
source = { registry = "https://pypi.org/simple" }
5683
dependencies = [
5684
{ name = "distlib" },
5685
{ name = "filelock" },
5686
+ { name = "packaging" },
5687
{ name = "platformdirs" },
5688
{ name = "python-discovery" },
5689
]
5689
-sdist = { url = "https://files.pythonhosted.org/packages/ba/37/e4f918e5a6547ab868aede62babdd696514bf1f282e71439db91597d7d9c/virtualenv-21.7.14.tar.gz", hash = "sha256:6f14bcaeb6c3438cd8c8cf3ab1805973592fb900e9b724427d1102aaa3db7fbb", size = 5360773, upload-time = "2026-09-18T05:24:20.684Z" }
5690
+sdist = { url = "https://files.pythonhosted.org/packages/7f/be/4d1d59d309db76b5808fcfd78bd5996f4e7241366691c38fc331a3136398/virtualenv-21.14.11.tar.gz", hash = "sha256:593052d8477ea8c55a842387ce111bd08c72618f0c1133c302cafe335e570a57", size = 5503091, upload-time = "2026-10-18T07:06:34.716Z" }
5691
wheels = [
5691
- { url = "https://files.pythonhosted.org/packages/47/77/2218525414fc4be6c0cdcbc7918196e46cd0885ad3253ef51035c17a375d/virtualenv-21.7.14-py3-none-any.whl", hash = "sha256:ac2b2b3755da16aed6302de00ecd0cc43ecc0f295c3f84c064969cd70869ba05", size = 5328845, upload-time = "2026-09-18T05:24:18.393Z" },
5692
+ { url = "https://files.pythonhosted.org/packages/ce/6b/d85da8982b41190eafcb9df91dff9d83fc6989e98af4b5be4c8f85510c95/virtualenv-21.14.11-py3-none-any.whl", hash = "sha256:b319f8590a84e5de5f8f2c803ecd2237e9bc0ffa7c1e875e3169c107cecb7454", size = 5495268, upload-time = "2026-10-18T07:06:32.719Z" },
5693
]
5694
5695
[[package]]