|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +Agent guide for the **CreateOS Python SDK**. Contributor conventions live in |
| 4 | +[`CONTRIBUTING.md`](CONTRIBUTING.md); this file covers what an agent needs that |
| 5 | +the contributor guide does not. |
| 6 | + |
| 7 | +## This repository |
| 8 | + |
| 9 | +- Package: `createos-sandbox` on PyPI, imported as `createos`. |
| 10 | +- Source: `src/createos/`. Public surface is everything re-exported from |
| 11 | + `src/createos/__init__.py`. |
| 12 | +- Python 3.10–3.14. Keep the 3.10 floor: `from __future__ import annotations` |
| 13 | + in every module, and the local `StrEnum` shim in `models.py` instead of the |
| 14 | + stdlib 3.11 one. |
| 15 | +- Local checks: `.venv/bin/ruff format --check src tests examples`, |
| 16 | + `.venv/bin/ruff check src tests examples`, |
| 17 | + `.venv/bin/mypy src/createos --ignore-missing-imports`, |
| 18 | + `.venv/bin/pytest --cov=createos --cov-fail-under=70`. |
| 19 | +- Release: `./scripts/publish.sh` (see CONTRIBUTING.md → Releasing). |
| 20 | + |
| 21 | +## The CreateOS SDK family |
| 22 | + |
| 23 | +This is one of three clients for the **same** CreateOS Sandbox API. They are |
| 24 | +separate repositories that are expected to stay behaviourally in sync. A change |
| 25 | +worth making here is usually worth making in the siblings. |
| 26 | + |
| 27 | +| Language | Repository | Package | Agent guide | Local sibling | |
| 28 | +| --- | --- | --- | --- | --- | |
| 29 | +| TypeScript | [createos-sandbox-sdk](https://github.com/NodeOps-app/createos-sandbox-sdk) | `@nodeops-createos/sandbox` | [`CLAUDE.md`](https://github.com/NodeOps-app/createos-sandbox-sdk/blob/main/CLAUDE.md) → [`AGENTS.md`](https://github.com/NodeOps-app/createos-sandbox-sdk/blob/main/AGENTS.md) | `../fc-sdk` | |
| 30 | +| Go | [createos-go-sdk](https://github.com/NodeOps-app/createos-go-sdk) | `github.com/NodeOps-app/createos-go-sdk` | [`CLAUDE.md`](https://github.com/NodeOps-app/createos-go-sdk/blob/main/CLAUDE.md) | `../createos-go-sdk` | |
| 31 | +| Python | this repo | `createos-sandbox` | this file | — | |
| 32 | + |
| 33 | +Upstream of all three: |
| 34 | + |
| 35 | +- **Service** — `../fc` (`nodeops-app/fc`). Source of truth for the wire |
| 36 | + contract: `openapi.yaml`, plus `CLAUDE.md` / `AGENT.md` for its own rules. |
| 37 | + If the SDKs disagree about what the API does, the service wins. |
| 38 | +- **Public docs** — `../website-04/content/docs/Sandbox/`, published at |
| 39 | + <https://createos.sh/docs/Sandbox>. Language snippets are **not** written in |
| 40 | + Markdown: they live in `lib/docs/sdk-code-examples.ts` and render through |
| 41 | + `<SdkCodeTabs example="..." />`, one entry per language. A new SDK capability |
| 42 | + that users should see is not shipped until that file has it. |
| 43 | + |
| 44 | +## Cross-SDK parity protocol |
| 45 | + |
| 46 | +Run this before you call any change to this repo done. It is a read-and-report |
| 47 | +protocol — **do not edit a sibling repository unless the user asks you to.** |
| 48 | + |
| 49 | +1. **Classify the change.** |
| 50 | + - *Wire contract* (new endpoint, changed field, new request/response shape) |
| 51 | + → affects all three SDKs and usually the docs. |
| 52 | + - *Behaviour* (retry policy, timeout default, stream framing, error |
| 53 | + mapping) → affects all three SDKs. |
| 54 | + - *Bug fix* → check whether the siblings have the same bug. They were |
| 55 | + written from the same spec, so they usually do. |
| 56 | + - *Ergonomics* (a Pythonic helper, a context manager) → often has a natural |
| 57 | + equivalent in the siblings; propose it, don't assume it. |
| 58 | + - *Repo-local* (packaging, lint config, CI) → no parity obligation. |
| 59 | +2. **Check the siblings.** Read the matching file under `../fc-sdk/src/` and |
| 60 | + `../createos-go-sdk/sandbox/`. If a sibling checkout is missing, say so |
| 61 | + rather than guessing. |
| 62 | +3. **Report.** End the task with a short parity note: what ports to which SDK, |
| 63 | + what does not, and why. Name the file the sibling change would land in. |
| 64 | +4. **Docs.** If the change adds or alters a user-visible capability, say |
| 65 | + whether `sdk-code-examples.ts` and the affected page under |
| 66 | + `content/docs/Sandbox/` need updating. |
| 67 | + |
| 68 | +The same protocol runs in reverse: when the TypeScript or Go SDK gains a |
| 69 | +feature or fix, check whether it belongs here. |
| 70 | + |
| 71 | +### Current parity baseline |
| 72 | + |
| 73 | +The Python and Go SDKs expose the same surface and ship the same nine examples |
| 74 | +(`hello_world`, `command_streaming`, `files_and_snapshots`, `ingress_preview`, |
| 75 | +`managed_process`, `network`, `custom_template`, `desktop`, |
| 76 | +`execution_server`). The TypeScript SDK has the same core surface plus a much |
| 77 | +larger integration-example corpus. Treat a gap against Go as a real gap; treat |
| 78 | +a gap against a TypeScript *integration example* as optional. |
0 commit comments