robotrace-dev 0.1.0a2__tar.gz

robotrace_dev-0.1.0a2/.gitignore

@@ -0,0 +1,50 @@
+# dependencies
+node_modules/
+.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# python
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.tox/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# next
+.next/
+out/
+*.tsbuildinfo
+next-env.d.ts
+
+# env
+.env
+.env.local
+.env.*.local
+
+# misc
+.DS_Store
+*.pem
+.vercel
+.npm-cache/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# editor
+.vscode/
+.idea/
+.cursor/.ai/

robotrace_dev-0.1.0a2/CHANGELOG.md

@@ -0,0 +1,120 @@
+# Changelog
+
+All notable changes to the `robotrace-dev` Python SDK
+(import name: `robotrace`).
+
+The SDK follows [Semantic Versioning](https://semver.org/). Pre-1.0
+releases (`0.x`) may make breaking changes between minor versions.
+Once we cut `1.0.0`, the [`log_episode`](./README.md#log_episode-the-sacred-call)
+signature is **locked** per AGENTS.md — breakages require a major
+bump and at least one minor of `DeprecationWarning` first.
+
+## [Unreleased]
+
+## [0.1.0a2] — 2026-05-09
+
+### Changed
+
+- **PyPI distribution name is `robotrace-dev`**, matching our
+  `robotrace.dev` domain. The un-hyphenated `robotrace` namespace on
+  PyPI was claimed in March 2026 by an unrelated robotics
+  observability project, and PyPI's typo-squat protector blocks any
+  single-edit-distance variant — including `robo-trace`, which we
+  tried first and PyPI rejected with `400 Bad Request`.
+  `robotrace-dev` clears the similarity threshold (Damerau-Levenshtein
+  ≥ 3 from both `robotrace` and `robotrace-sdk`) and reads as the
+  obvious match for our domain. The *import* name is still
+  `robotrace` (no hyphen, no `-dev`) — same convention as
+  `pip install python-dateutil` → `import dateutil`. **No code
+  changes required** in your application; the install command is
+  `pip install robotrace-dev`.
+- Earlier `0.1.0a*` releases were never published to PyPI, so
+  there's no in-the-wild upgrade path to worry about — `0.1.0a2` is
+  the first published release.
+
+### Added
+
+- **`robotrace-dev[otel]`** extra — opt-in OpenTelemetry trace
+  correlation. Pulls only `opentelemetry-api>=1.20` (~30 KB), not
+  the heavy `opentelemetry-sdk`. When `start_episode` is called
+  inside an active OTel span, the SDK reads the ambient context via
+  `opentelemetry.trace.get_current_span()` and attaches:
+  - `trace_id` (32-char lowercase hex)
+  - `span_id` (16-char lowercase hex)
+  - `traceparent` (W3C `00-<trace>-<span>-01` format)
+  to the create-episode payload. The server stores them under
+  `episodes.metadata.otel`; the portal renders a Tracing card on
+  the episode detail page with copy buttons and an optional
+  one-click "Open trace" deep-link via the
+  `NEXT_PUBLIC_TRACE_URL_TEMPLATE` env var (Datadog, Honeycomb,
+  Grafana Tempo, Jaeger).
+- New `robotrace._otel` module with `capture_trace_context()`. Soft
+  imports — never raises if `opentelemetry` is missing or the active
+  span is invalid / unsampled.
+- 7 new unit tests (`tests/test_otel.py`) covering: not-installed,
+  no-active-span, active-span happy path, unsampled flag, OTel
+  module misbehavior, public API exposure, and the `log_episode`
+  round-trip.
+- The "sacred" `log_episode` / `start_episode` signature is
+  **unchanged** — OTel context is read implicitly. No new kwargs to
+  learn, no opt-in flag, no deprecation warnings on existing callers.
+
+## [0.1.0a1] — 2026-05-08
+
+### Added
+
+- **`robotrace.adapters.ros2`** — read rosbag2 directories (sqlite3 +
+  mcap backends) and turn them into RoboTrace episodes without
+  needing an `rclpy` install. Three public verbs:
+  - `ros2.scan_bag(path) → BagSummary` — read-only introspection
+    with topic catalog, auto-classifier decisions, and bag duration.
+  - `ros2.encode_bag(path, output_dir) → EncodedBag` — writes
+    `video.mp4`, `sensors.npz`, `actions.npz` and returns the file
+    paths plus inferred `duration_s` / `fps`. No network.
+  - `ros2.upload_bag(path, **episode_kwargs) → Episode` — one-shot
+    scan + encode-to-tempdir + `start_episode` + `upload_*` +
+    `finalize`. The headline call.
+- Auto-classification routes `sensor_msgs/Image` /
+  `CompressedImage` to `video`, `geometry_msgs/Twist*`,
+  `Wrench*`, `trajectory_msgs/JointTrajectory*`,
+  `control_msgs/JointJog`, and topics ending in `/cmd_*` /
+  `/command` to `actions`. Everything else lands in `sensors`.
+  Override per-slot via `video_topics=` / `sensor_topics=` /
+  `action_topics=` (empty list = exclude the slot).
+- Multi-camera bags get tiled horizontally into a single
+  `video.mp4`; pass `canonical_video_topic=...` to pick one camera
+  instead. Frame rate inferred from the camera with the most
+  frames; falls back to 10 fps when timestamps are unusable.
+- Built-in flatteners for `sensor_msgs/JointState`, `Imu`,
+  `geometry_msgs/Twist[Stamped]`, `Wrench[Stamped]`, `PoseStamped`,
+  `nav_msgs/Odometry`. Unknown message types fall through to a
+  generic dataclass walker that pulls every numeric leaf.
+
+### Changed
+
+- Bumped `[project.optional-dependencies].ros2` from `[]` to
+  `["rosbags>=0.11,<0.12", "numpy>=1.26"]`. Pure Python — no real
+  ROS 2 install required to ingest bags.
+- Image-topic encoding lives behind the existing `[video]` extra
+  (opencv-python). Install combo for camera bags is
+  `pip install 'robotrace-dev[ros2,video]'`; sensor-only bags can stick
+  with `[ros2]` and skip opencv entirely.
+
+## [0.1.0a0] — 2026-05-02
+
+First public alpha. Contract under iteration.
+
+### Added
+
+- `robotrace.init(...)`, `robotrace.start_episode(...)`,
+  `robotrace.log_episode(...)` top-level convenience.
+- `robotrace.Client(...)` for explicit, multi-deployment use.
+- `robotrace.Episode` handle with `upload_video` / `upload_sensors` /
+  `upload_actions` / `finalize` and context-manager auto-finalize
+  (clean exit → `ready`, exception → `failed`).
+- Streaming PUT to Cloudflare R2 via signed URLs (no body buffering).
+- Typed exception hierarchy (`RobotraceError` → `AuthError`,
+  `NotFoundError`, `ConflictError`, `ValidationError`, `ServerError`,
+  `TransportError`, `ConfigurationError`).
+- `pytest`-based smoke tests pinning the wire format to
+  `/api/ingest/episode` and `/api/ingest/episode/{id}/finalize`.

robotrace_dev-0.1.0a2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RoboTrace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

robotrace_dev-0.1.0a2/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.4
+Name: robotrace-dev
+Version: 0.1.0a2
+Summary: RoboTrace — observability and evals for AI robots.
+Project-URL: Homepage, https://robotrace.dev
+Project-URL: Documentation, https://robotrace.dev/docs
+Project-URL: Issues, https://github.com/robotrace/robotrace/issues
+Author-email: RoboTrace <hello@robotrace.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: evals,lerobot,observability,robotics,ros2,vla
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: lerobot
+Requires-Dist: lerobot; extra == 'lerobot'
+Provides-Extra: numpy
+Requires-Dist: numpy>=1.26; extra == 'numpy'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
+Provides-Extra: ros2
+Requires-Dist: numpy>=1.26; extra == 'ros2'
+Requires-Dist: rosbags<0.12,>=0.11; extra == 'ros2'
+Provides-Extra: video
+Requires-Dist: opencv-python>=4.10; extra == 'video'
+Description-Content-Type: text/markdown
+
+# robotrace-dev (Python SDK)
+
+> The official Python SDK for [RoboTrace](https://robotrace.dev) —
+> observability and evals for AI-powered robots.
+
+```bash
+pip install robotrace-dev==0.1.0a2
+```
+
+> **Distribution name vs. import name.** PyPI distributes us as
+> `robotrace-dev` (matching our `robotrace.dev` domain). The
+> un-hyphenated `robotrace` PyPI namespace is held by an unrelated
+> robotics project, and PyPI's typo-squat protector blocks any
+> single-edit-distance variant (so `robo-trace` was rejected too).
+> The *import* name stays `import robotrace` — same pattern as
+> `pip install python-dateutil` → `import dateutil`.
+
+> **Status:** alpha (`0.1.0a2`). The public API in this README is the
+> shape we're iterating against; once we cut `1.0.0`, the
+> [`log_episode`](#log_episode-the-sacred-call) signature is locked
+> and breakages require a major bump (per `AGENTS.md` in the
+> RoboTrace monorepo).
+
+## Quickstart
+
+Mint an API key in your RoboTrace admin console
+(**Admin → Clients → \<client\> → API access**), then:
+
+```python
+import robotrace as rt
+
+rt.init(
+    api_key="rt_…",
+    base_url="https://app.robotrace.dev",   # or http://localhost:3000 in dev
+)
+
+rt.log_episode(
+    name="pick_and_place v3 morning warmup",
+    source="real",
+    robot="halcyon-bimanual-01",
+    policy_version="pap-v3.2.1",
+    env_version="halcyon-cell-rev4",
+    git_sha="abc1234",
+    seed=8124,
+    video="/tmp/run.mp4",
+    sensors="/tmp/sensors.bin",
+    actions="/tmp/actions.parquet",
+    duration_s=47.2,
+    fps=30,
+    metadata={"task": "pick_and_place", "scene": "tabletop"},
+)
+```
+
+The episode appears in `/admin/episodes` immediately, with the four
+reproducibility fields (policy / env / git / seed) front-and-center
+on the detail page.
+
+### From environment variables
+
+Same call without hardcoding the key:
+
+```bash
+export ROBOTRACE_API_KEY=rt_…
+export ROBOTRACE_BASE_URL=https://app.robotrace.dev
+```
+
+```python
+import robotrace as rt
+
+# init() is optional when both env vars are set — the default
+# client is constructed lazily on first use.
+rt.log_episode(
+    name="…",
+    policy_version="…",
+    video="/tmp/run.mp4",
+)
+```
+
+## API
+
+### `log_episode` — the sacred call
+
+The one-shot entrypoint. Equivalent to `start_episode` → upload all
+artifacts → `finalize`. Use this for the 95% case of "I have files
+on disk, log them and move on."
+
+```python
+rt.log_episode(
+    *,
+    # Identification
+    name: str | None = None,
+    source: Literal["real", "sim", "replay"] = "real",
+    robot: str | None = None,
+
+    # Reproducibility — load-bearing per AGENTS.md
+    policy_version: str | None = None,
+    env_version: str | None = None,
+    git_sha: str | None = None,
+    seed: int | None = None,
+
+    # Artifact paths (uploaded to object storage via signed PUT URLs)
+    video: str | Path | None = None,
+    sensors: str | Path | None = None,
+    actions: str | Path | None = None,
+
+    # Run details
+    duration_s: float | None = None,
+    fps: float | None = None,
+    metadata: Mapping[str, Any] | None = None,
+
+    # Final state
+    status: Literal["ready", "failed"] = "ready",
+) -> Episode
+```
+
+Returns the finalized `Episode`. On failure during upload the SDK
+flips the run to `status="failed"` and re-raises so your program
+sees what went wrong.
+
+### `start_episode` — explicit lifecycle
+
+When you want fine-grained control (stream uploads, defer finalize,
+react to upload errors per-artifact), use `start_episode` and the
+returned `Episode` handle:
+
+```python
+with rt.start_episode(
+    name="pick_and_place v3 morning warmup",
+    policy_version="pap-v3.2.1",
+    artifacts=["video", "sensors"],     # only request the slots you'll fill
+) as ep:
+    ep.upload_video("/tmp/run.mp4")
+    ep.upload_sensors("/tmp/sensors.bin")
+    # No explicit finalize — context manager handles it:
+    #   • clean exit → status="ready"
+    #   • exception  → status="failed", with metadata.failure_reason set
+```
+
+Or explicit:
+
+```python
+ep = rt.start_episode(name="…", policy_version="…", artifacts=["video"])
+ep.upload_video("/tmp/run.mp4")
+ep.finalize(status="ready", duration_s=47.2, fps=30)
+```
+
+### `Client` — explicit instance
+
+Skip the module-level default when you need multiple deployments at
+once (e.g. shipping the same run to staging + production), or for
+clean dependency injection in tests:
+
+```python
+with rt.Client(api_key="rt_…", base_url="https://…") as client:
+    client.log_episode(name="…", policy_version="…", video="…")
+```
+
+`Client` holds a connection pool — construct it once at process
+startup, reuse across many episodes, and `close()` (or use as a
+context manager) on shutdown.
+
+## Errors
+
+Every SDK error inherits from `robotrace.RobotraceError`. Catch by
+type rather than parsing message strings:
+
+| Exception            | When                                                   |
+| -------------------- | ------------------------------------------------------ |
+| `ConfigurationError` | Missing `api_key` / `base_url`, file path doesn't exist |
+| `TransportError`     | Network / DNS / TLS / timeout                          |
+| `AuthError`          | 401 — bad / missing / revoked key                      |
+| `NotFoundError`      | 404 — episode id doesn't exist (or cross-tenant)       |
+| `ConflictError`      | 409 — episode is archived, etc.                        |
+| `ValidationError`    | 400 — payload didn't pass server-side validation       |
+| `ServerError`        | 5xx — flag for retries                                 |
+
+```python
+from robotrace import RobotraceError, AuthError
+
+try:
+    rt.log_episode(...)
+except AuthError:
+    # mint a fresh key and reload
+    raise
+except RobotraceError:
+    # generic recovery / alert
+    raise
+```
+
+## Storage
+
+Artifact uploads go to Cloudflare R2 via short-lived signed PUT URLs
+the server mints for each call. The SDK streams from disk so memory
+stays flat regardless of file size.
+
+When the deployment hasn't wired R2 yet (`R2_ACCOUNT_ID` etc. are
+blank), the create response has `storage="unconfigured"` and any
+`upload_*` call raises `ConfigurationError` with a pointer to the
+production setup checklist. Metadata-only runs still work — useful
+for testing the SDK contract end-to-end before R2 is provisioned.
+
+## Layout (current)
+
+```
+src/robotrace/
+├── __init__.py          # public API + module-level default client
+├── _version.py
+├── client.py            # Client class
+├── episode.py           # Episode handle + UploadUrl + ArtifactKind
+├── errors.py            # RobotraceError + typed subclasses
+└── _http.py             # internal httpx wrapper
+```
+
+ROS 2 / LeRobot adapters land later under `src/robotrace/adapters/`.
+
+## Contributing
+
+The SDK lives in the [RoboTrace monorepo](https://github.com/robotrace/robotrace).
+The web app at `apps/web` exposes the ingest API the SDK talks to —
+coordinate breaking changes across both, and treat the
+[`/api/ingest/episode`](https://robotrace.dev/docs/api/ingest)
+contract as the boundary.
+
+## License
+
+MIT.

robotrace_dev-0.1.0a2/README.md

@@ -0,0 +1,226 @@
+# robotrace-dev (Python SDK)
+
+> The official Python SDK for [RoboTrace](https://robotrace.dev) —
+> observability and evals for AI-powered robots.
+
+```bash
+pip install robotrace-dev==0.1.0a2
+```
+
+> **Distribution name vs. import name.** PyPI distributes us as
+> `robotrace-dev` (matching our `robotrace.dev` domain). The
+> un-hyphenated `robotrace` PyPI namespace is held by an unrelated
+> robotics project, and PyPI's typo-squat protector blocks any
+> single-edit-distance variant (so `robo-trace` was rejected too).
+> The *import* name stays `import robotrace` — same pattern as
+> `pip install python-dateutil` → `import dateutil`.
+
+> **Status:** alpha (`0.1.0a2`). The public API in this README is the
+> shape we're iterating against; once we cut `1.0.0`, the
+> [`log_episode`](#log_episode-the-sacred-call) signature is locked
+> and breakages require a major bump (per `AGENTS.md` in the
+> RoboTrace monorepo).
+
+## Quickstart
+
+Mint an API key in your RoboTrace admin console
+(**Admin → Clients → \<client\> → API access**), then:
+
+```python
+import robotrace as rt
+
+rt.init(
+    api_key="rt_…",
+    base_url="https://app.robotrace.dev",   # or http://localhost:3000 in dev
+)
+
+rt.log_episode(
+    name="pick_and_place v3 morning warmup",
+    source="real",
+    robot="halcyon-bimanual-01",
+    policy_version="pap-v3.2.1",
+    env_version="halcyon-cell-rev4",
+    git_sha="abc1234",
+    seed=8124,
+    video="/tmp/run.mp4",
+    sensors="/tmp/sensors.bin",
+    actions="/tmp/actions.parquet",
+    duration_s=47.2,
+    fps=30,
+    metadata={"task": "pick_and_place", "scene": "tabletop"},
+)
+```
+
+The episode appears in `/admin/episodes` immediately, with the four
+reproducibility fields (policy / env / git / seed) front-and-center
+on the detail page.
+
+### From environment variables
+
+Same call without hardcoding the key:
+
+```bash
+export ROBOTRACE_API_KEY=rt_…
+export ROBOTRACE_BASE_URL=https://app.robotrace.dev
+```
+
+```python
+import robotrace as rt
+
+# init() is optional when both env vars are set — the default
+# client is constructed lazily on first use.
+rt.log_episode(
+    name="…",
+    policy_version="…",
+    video="/tmp/run.mp4",
+)
+```
+
+## API
+
+### `log_episode` — the sacred call
+
+The one-shot entrypoint. Equivalent to `start_episode` → upload all
+artifacts → `finalize`. Use this for the 95% case of "I have files
+on disk, log them and move on."
+
+```python
+rt.log_episode(
+    *,
+    # Identification
+    name: str | None = None,
+    source: Literal["real", "sim", "replay"] = "real",
+    robot: str | None = None,
+
+    # Reproducibility — load-bearing per AGENTS.md
+    policy_version: str | None = None,
+    env_version: str | None = None,
+    git_sha: str | None = None,
+    seed: int | None = None,
+
+    # Artifact paths (uploaded to object storage via signed PUT URLs)
+    video: str | Path | None = None,
+    sensors: str | Path | None = None,
+    actions: str | Path | None = None,
+
+    # Run details
+    duration_s: float | None = None,
+    fps: float | None = None,
+    metadata: Mapping[str, Any] | None = None,
+
+    # Final state
+    status: Literal["ready", "failed"] = "ready",
+) -> Episode
+```
+
+Returns the finalized `Episode`. On failure during upload the SDK
+flips the run to `status="failed"` and re-raises so your program
+sees what went wrong.
+
+### `start_episode` — explicit lifecycle
+
+When you want fine-grained control (stream uploads, defer finalize,
+react to upload errors per-artifact), use `start_episode` and the
+returned `Episode` handle:
+
+```python
+with rt.start_episode(
+    name="pick_and_place v3 morning warmup",
+    policy_version="pap-v3.2.1",
+    artifacts=["video", "sensors"],     # only request the slots you'll fill
+) as ep:
+    ep.upload_video("/tmp/run.mp4")
+    ep.upload_sensors("/tmp/sensors.bin")
+    # No explicit finalize — context manager handles it:
+    #   • clean exit → status="ready"
+    #   • exception  → status="failed", with metadata.failure_reason set
+```
+
+Or explicit:
+
+```python
+ep = rt.start_episode(name="…", policy_version="…", artifacts=["video"])
+ep.upload_video("/tmp/run.mp4")
+ep.finalize(status="ready", duration_s=47.2, fps=30)
+```
+
+### `Client` — explicit instance
+
+Skip the module-level default when you need multiple deployments at
+once (e.g. shipping the same run to staging + production), or for
+clean dependency injection in tests:
+
+```python
+with rt.Client(api_key="rt_…", base_url="https://…") as client:
+    client.log_episode(name="…", policy_version="…", video="…")
+```
+
+`Client` holds a connection pool — construct it once at process
+startup, reuse across many episodes, and `close()` (or use as a
+context manager) on shutdown.
+
+## Errors
+
+Every SDK error inherits from `robotrace.RobotraceError`. Catch by
+type rather than parsing message strings:
+
+| Exception            | When                                                   |
+| -------------------- | ------------------------------------------------------ |
+| `ConfigurationError` | Missing `api_key` / `base_url`, file path doesn't exist |
+| `TransportError`     | Network / DNS / TLS / timeout                          |
+| `AuthError`          | 401 — bad / missing / revoked key                      |
+| `NotFoundError`      | 404 — episode id doesn't exist (or cross-tenant)       |
+| `ConflictError`      | 409 — episode is archived, etc.                        |
+| `ValidationError`    | 400 — payload didn't pass server-side validation       |
+| `ServerError`        | 5xx — flag for retries                                 |
+
+```python
+from robotrace import RobotraceError, AuthError
+
+try:
+    rt.log_episode(...)
+except AuthError:
+    # mint a fresh key and reload
+    raise
+except RobotraceError:
+    # generic recovery / alert
+    raise
+```
+
+## Storage
+
+Artifact uploads go to Cloudflare R2 via short-lived signed PUT URLs
+the server mints for each call. The SDK streams from disk so memory
+stays flat regardless of file size.
+
+When the deployment hasn't wired R2 yet (`R2_ACCOUNT_ID` etc. are
+blank), the create response has `storage="unconfigured"` and any
+`upload_*` call raises `ConfigurationError` with a pointer to the
+production setup checklist. Metadata-only runs still work — useful
+for testing the SDK contract end-to-end before R2 is provisioned.
+
+## Layout (current)
+
+```
+src/robotrace/
+├── __init__.py          # public API + module-level default client
+├── _version.py
+├── client.py            # Client class
+├── episode.py           # Episode handle + UploadUrl + ArtifactKind
+├── errors.py            # RobotraceError + typed subclasses
+└── _http.py             # internal httpx wrapper
+```
+
+ROS 2 / LeRobot adapters land later under `src/robotrace/adapters/`.
+
+## Contributing
+
+The SDK lives in the [RoboTrace monorepo](https://github.com/robotrace/robotrace).
+The web app at `apps/web` exposes the ingest API the SDK talks to —
+coordinate breaking changes across both, and treat the
+[`/api/ingest/episode`](https://robotrace.dev/docs/api/ingest)
+contract as the boundary.
+
+## License
+
+MIT.