Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
md 69 lines 2.48 KB
Rendered Raw
1 # AGENTS.md
2
3 Python SDK guidance for AI agents.
4
5 ## Scope
6
7 `python/` contains the Python SDK, provider packages, tests, nox sessions, release scripts, and Python docs.
8
9 ## Skill Routing
10
11 - Use `python-sdk` for core SDK code under `python/composio/`.
12 - Use `python-providers` for `python/providers/*`.
13 - Use `python-testing` for Ruff, mypy, pytest, nox, and Makefile verification.
14 - Use `python-release` for build, bump, and publishing workflow changes.
15 - Use `cross-sdk-parity` when matching TypeScript SDK behavior.
16
17 ## Setup
18
19 Run from `python/`:
20
21 ```bash
22 make env
23 source .venv/bin/activate
24 ```
25
26 ## Commands
27
28 ```bash
29 make fmt
30 make chk
31 make tst
32 make snt
33 make type_inference
34 make build
35 ```
36
37 ## Rules
38
39 - Public Python SDK/provider behavior changes need a Changesets note targeting the private `@composio/python-sdk` marker. Stable core and providers release together through the unified SDK request workflow.
40
41 - Use Ruff for formatting/linting and mypy for type checks.
42 - Add pytest coverage for behavior changes.
43 - Keep provider-specific changes under the relevant `python/providers/<provider>/` package.
44 - When bumping `composio-client`, update `python/pyproject.toml`, `python/setup.py`, and root `uv.lock` together.
45
46 ## Trust boundary
47
48 **Every field of an API response is untrusted input** — including slugs, IDs, and
49 filenames. The SDK's threat model assumes the backend may be compromised or the
50 connection MITM'd, and that a third-party toolkit can return anything.
51
52 When untrusted directory components such as slugs or IDs become part of a
53 filesystem path, use
54 `composio.utils.safe_path.secure_join(root, *components)`. For an untrusted
55 filename, use `secure_basename_join(base, filename, root=root)` so ordinary
56 extensions remain valid while the write stays anchored to the trusted root.
57 Both helpers enforce two rules:
58
59 1. **Anchor containment on a constant.** Checking a derived path against a
60 directory that untrusted input helped build compares tainted against tainted
61 and always passes. A directory built as `root / untrusted_a / untrusted_b`
62 and then validated against that same built directory is checked against a
63 reference the input was free to move.
64 2. **Validate before touching the filesystem.** No `mkdir` or `open` until the
65 final path is known to be inside the root, so a rejected write leaves no
66 attacker-chosen directories behind.
67
68 `tests/test_path_join_guardrail.py` enforces this: any path join whose right-hand
69 side is not a literal or module constant must be listed there with a reason.