@devries-cameron20 / composio Mirror · read-only / commits / 5ef7cb1e4
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 07:15 UTC

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]]