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

docs: offer Python, TypeScript, and API options for code examples (#5100)

## Summary Maintained docs code examples now offer Python, TypeScript, and API (direct REST `curl`) options. Where a language genuinely cannot express an operation, the example carries a scoped, reasoned exception marker. Deterministic checks keep this consistent: example structure, `curl` requests against the committed OpenAPI specs, Python SDK usage, and TypeScript outside build-time Twoslash. Designated PR reviewer: [@jkomyno](mailto:alberto@composio.dev). ## Prior to Changes | Kind of snippet | Count | |---|---:| | Python + TypeScript tab groups (already paired) | 255 | | Python + TypeScript + curl tab groups | 3 | | Language tab groups with only one SDK | 5 | | Python snippets with no TypeScript version | 24 | | TypeScript/JS snippets with no Python version | 36 | | curl calls to the Composio API, not in tabs | 58 | | Other shell (install, CLI, env vars) | 103 | | JSON, text and diagrams | 117 | What stood out: - Labels and order are already inconsistent. 229 groups put Python first, 15 put TypeScript first. Migration guides use labels like "Python (current)", and 3 groups already have a tab called curl. - The existing curl snippets have drifted. They use three API versions in the URL (/api/v3.1 ×52, /api/v3 ×15, /api/v1 ×5) and five different ways of writing the API key. - Some gaps are real SDK gaps, not docs gaps. For example, session-configs.mdx is TypeScript-only because composio.sessionConfigs exists in ts/packages/core/src/composio.ts:387 and Python has no session_configs at all. An agent must not invent a Python version. - Many single-language snippets are correct as they are. Framework pages like CrewAI, AutoGen, Mastra, Vercel, eve and pi are single-language by nature, as are the custom-providers/{python,typescript} pages and one-language example projects. - Only TypeScript is checked today. Twoslash type-checks TypeScript snippets at build time. Python and curl snippets are never checked. ## Changes - Adds Python, TypeScript, and API counterparts across guides, examples, API overviews, toolkit FAQs, and KB sources/articles. The CSV report and email-triggered tutorials gain TypeScript implementations, and the email tutorial's setup gains an API version. - Adds `bun run inventory:code-examples` and `check:code-examples`. The inventory records every rendered fence, including generated, historical, and component-backed sources. - Adds `check:api-snippets`, which parses `curl` and validates route, method, auth, API version, and JSON body against `public/openapi*.json`. Exceptions are scoped to one rule and one operation, and an exception that no longer matches a diagnostic fails. - Adds `check:python-snippets` and `test:python-snippets`: syntax plus SDK-attributed mypy errors against the local SDK and providers, using a locked `docs-snippets` dependency group. Adds a `Docs - Python Snippets` workflow. - Adds `check:typescript-snippets` for API overviews, authored reference, and Markdown FAQ/KB inputs, which build-time Twoslash does not cover. - Toolkit FAQs and KB pages render language headings as persistent tabs. Agent Markdown keeps every label and variant. Generated API reference samples gain Python and TypeScript options. - Fixes from review: - The translated TypeScript tutorials now run as ES modules (`npm pkg set type=module`). Before this, `npx tsx` rejected their top-level `await`. - Cards are converted to agent Markdown from the parsed MDX tree. The old regex let a `<Card>` without `description` swallow later examples; it hid one full language group in `authenticating-tools` and the end of `custom-auth-params`. - The Python gate now attributes four more error kinds to the SDK: - indexing an SDK model (`response["status"]` on `ToolProxyResponse` raises `TypeError` at runtime) - missing keys on SDK TypedDicts - assigning an SDK result to an incompatible annotation - misspelled names of SDK-valued bindings - `# type: ignore` must now name its error codes, carry an explanation, and still suppress a real error. mypy's column-less diagnostics were previously dropped; they are now parsed. - Corrected the proxy, `proxy_execute`, and webhook payload examples the stricter gate flagged. After rebasing onto `composio-client` rc.22, the consumer-project examples use raw client requests, because those routes are now internal. ## Type of change - [x] Bug fix - [ ] New feature - [ ] Refactor/Chore - [x] Documentation - [ ] Breaking change ## How Has This Been Tested? From `docs/`, all passing after rebasing onto current `next`: - `bun run check:code-examples` - `bun run check:api-snippets` - `bun run check:python-snippets` (350 snippets) - `bun run test:python-snippets` (42 real-helper fixtures) - `bun run check:typescript-snippets` - `bun run test` (787 pass) - `bun run lint` - `bun run types:check` - `bun run lint:links` - `GITHUB_ACTIONS=true bun run build` From the repo root: `node ts/scripts/validate-agent-skills.mjs` and `node ts/scripts/test-skill-routing.mjs`. Smoke checks, none touching live Composio APIs: - **tsx:** `npx tsx` fails on top-level `await` in an `npm install`-created project and succeeds after `npm pkg set type=module`, including the tutorial's imports. - **Served agent Markdown:** compared fence and label counts against the source on 271 pages. The Card truncations are gone; `/toolkits/managed-auth.md` is the only remaining mismatch (see below). - **Browser:** checked nested-tab sync and API persistence and fallback, FAQ and KB tabs, the SDK-gap Callout, both tutorials, and the API reference code tabs. - **Python raw requests:** the new consumer-route calls were run against an `httpx.MockTransport` and send the user key, the `x-org-id` header, and the query string. ## Checklist - [ ] I have read the Code of Conduct and this PR adheres to it - [ ] I have read and understand every line of this diff, including any LLM-generated code - [x] Any third-party docs links or promotional content follow the [third-party links policy](https://github.com/ComposioHQ/composio/blob/next/CONTRIBUTING.md#third-party-links-in-docs) - [x] I ran linters/tests locally and they passed - [x] I updated documentation as needed - [x] I added tests or explain why not applicable - [ ] I added a changeset if this change affects published packages (not applicable: docs, docs tooling, and a Python dev dependency group only) ## Additional context Known follow-ups, not addressed here: - **API tab enforcement:** an API tab accepts any `bash` fence. The `curl` checker also skips URLs held in variables and `curl` after shell keywords such as `do`/`if`/`then`, and does not validate query parameters. No current page hits these gaps. - **Python/TypeScript tabs:** a tab containing only `json`/`text` fences, a table, or any Callout passes. - **Generated request samples:** samples on 12 API reference operation pages produce bodies that fail validation against their own schema. - **`/toolkits/managed-auth.md`:** its agent Markdown is hard-coded in the `llms.mdx` route and shows a single `curl`. - **Exemption review:** some `no-api` exemptions (`restrict-gmail-domain`, file staging in `executing-tools`) and the Python session-config gap Callouts need review. - **Unchecked TypeScript:** 83 build-covered TypeScript fences still carry `@noErrors`.

Brendan O'Leary committed Oct 23, 2026 at 21:03 UTC d8f820480664727e8e3ce9f26a6db0bd45445869

No changes.