thrustlab 0.1.1__tar.gz → 0.3.0__tar.gz

thrustlab-0.3.0/.impeccable/hook.cache.json

@@ -0,0 +1 @@
+{"version":1,"sessions":{"4a041e4d-8a20-42d5-a6e0-f38606baf43c":{"updatedAt":1784225683709,"files":{"C:\\dev\\thrustlab\\frontend\\src\\lib\\help\\registry\\new-simulation.ts":{"editCount":1,"findings":[]},"C:\\dev\\thrustlab\\frontend\\src\\components\\submissions\\SubmissionForm.tsx":{"editCount":2,"findings":[]}}}}}

thrustlab-0.3.0/CHANGELOG.md

@@ -0,0 +1,231 @@
+# Changelog
+
+All notable changes to the `thrustlab` Python SDK are documented here. The
+project follows [semantic versioning](https://semver.org/) independent of the
+ThrustLab API version (which is permanently `/v1/`).
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-07-15
+
+The ThrustLab public API was refocused to a **product-only** surface: account,
+billing, subscription, API-key and geometry-calibration management are no
+longer part of the public `/v1/` contract. This SDK release realigns the
+client to that surface.
+
+> **0.2.0 was built but never published to PyPI.** 0.3.0 is the first release
+> after 0.1.2, and it **consolidates the unpublished 0.2.0 changes** (canonical
+> `snake_case` result keys, the `dynamic_simulations` resource, the sims/sweeps
+> `cursor` fix) together with the API-refocus breaking changes below. If you are
+> upgrading from `0.1.x`, read this whole entry — it is the full delta.
+
+### Removed
+
+- **BREAKING — `client.subscriptions` and `client.api_keys` resources are gone.**
+  Subscription/billing-portal and API-key management are not part of the public
+  product SDK. `client.subscriptions` / `client.api_keys` now raise
+  `AttributeError`. (Create and manage API keys from the ThrustLab dashboard.)
+
+### Changed
+
+- **BREAKING — `client.credits` renamed to `client.compute_units`.** The public
+  credits surface was renamed to *compute units*:
+  - accessor `client.credits` → `client.compute_units`;
+  - method `usage(...)` → `transactions(...)`;
+  - endpoints `/v1/credits/balance` → `/v1/compute-units/balance` and
+    `/v1/credits/usage` → `/v1/compute-units/transactions`;
+  - the pager keyword `starting_after=` → `cursor=` (the endpoint reads `cursor`;
+    this matches the 0.2.0 sims/sweeps fix — a `starting_after=` kwarg was
+    silently ignored). The `credit_type=` filter keyword is unchanged.
+- **BREAKING (from the unpublished 0.2.0) — result payloads are canonical
+  `snake_case` across single-point, sweep, AND dynamic endpoints**, each with a
+  sibling `display_labels` map (`{snake_key: "Human Label"}`). Consumers that
+  parsed the old display-label result keys on sweep points (`"Thrust (N)"`,
+  `"RPM"`, …) must read the snake keys (`thrust_n`, `rpm`, …) and use
+  `display_labels` to recover a human string.
+- **BREAKING — simulation / sweep / dynamic create bodies drop the first-party
+  fields `solver`, `input_snapshot`, and `design_cl`.** These were never part of
+  the public product contract; passing them is no longer accepted. (They remain
+  present in *response* payloads where the server legitimately echoes them.)
+- **BREAKING — rotor-group count is capped at 16 total rotors (Σ ≤ 16)** across
+  all groups on a create request; larger configurations are rejected by the API.
+
+### Added
+
+- **`client.components.create(...)`** — create a private custom component
+  (`POST /v1/components`) without dropping to the raw transport. Takes
+  `type`, `name`, `spec_json`, and an optional `idempotency_key`.
+- Component create/update responses may carry a non-blocking `warnings` list
+  (`code` / `param` / `message`) when a spec value looks physically
+  implausible — e.g. a motor `R` far outside the expected range for its `kv`
+  and `weight` (milliohm/ohm mix-up, or a per-phase value where phase-to-phase
+  is expected). The write always succeeds.
+- **`client.compute_units.summary()`** — usage-meter read for the current
+  metering window (`GET /v1/compute-units/summary`).
+- **`client.dynamic_simulations` resource** (`create` / `retrieve` / `wait` /
+  `list` / `cancel` / `estimate`) mirroring `client.sweeps`, plus a runnable
+  dynamic example (`examples/dynamic/run_and_poll.py`).
+- Runnable end-to-end examples for all three simulation types
+  (single-point / sweep / dynamic) reading canonical `snake_case` result keys,
+  and a corrected README quickstart using the real create body
+  (`rotor_groups=[…]` + `battery_component_id`).
+
+### Fixed
+
+- **`cursor` pagination** — an explicit `starting_after=` kwarg on
+  `simulations.list`, `sweeps.list`, and `sweeps.list_points` was silently
+  ignored (the backend reads `cursor`). The keyword argument is now `cursor=`.
+  Automatic multi-page iteration was unaffected.
+
+### Migration from 0.1.x / 0.2.0
+
+```python
+# --- credits -> compute_units ---------------------------------------------
+# before (<= 0.2.0)
+balance = client.credits.balance()
+for ev in client.credits.usage(credit_type="simulation", starting_after=cur):
+    ...
+
+# after (0.3.0)
+balance = client.compute_units.balance()
+for ev in client.compute_units.transactions(credit_type="simulation", cursor=cur):
+    ...
+
+# --- removed resources ----------------------------------------------------
+# client.subscriptions.* and client.api_keys.* no longer exist — manage
+# subscriptions and API keys from the ThrustLab dashboard.
+
+# --- sweep result keys are snake_case (from 0.2.0) ------------------------
+# before: point["rotors"]["1"]["Thrust (N)"]
+# after:  point["rotors"]["1"]["thrust_n"]   # display_labels["thrust_n"] -> "Thrust (N)"
+```
+
+## [0.2.0] - 2026-07-09
+
+### Changed
+
+- **BREAKING — result payloads are now canonical `snake_case` across
+  single-point, sweep, AND dynamic endpoints, each with a sibling
+  `display_labels` map (`{snake_key: "Human Label"}`).** Single-point results
+  were already snake_case; this release aligns **sweep points** and **dynamic
+  samples** to the same contract. Consumers that parsed the old display-label
+  result keys on sweep points (`"Thrust (N)"`, `"RPM"`, `"Current (A)"`, …)
+  must now read the snake keys (`thrust_n`, `rpm`, `current_a`, …). Use the
+  sibling `display_labels` map to recover a human string for any key.
+
+  Migration:
+
+  ```python
+  # before (0.1.x) — sweep point rotor keys were display labels
+  thrust = point["rotors"]["1"]["Thrust (N)"]
+
+  # after (0.2.0) — canonical snake_case, with display_labels for UI
+  thrust = point["rotors"]["1"]["thrust_n"]
+  label  = sweep["display_labels"]["thrust_n"]   # -> "Thrust (N)"
+  ```
+
+### Added
+
+- **`client.dynamic_simulations` resource** (`create` / `retrieve` / `wait` /
+  `list` / `cancel` / `estimate`) mirroring `client.sweeps`, plus a runnable
+  dynamic example (`examples/dynamic/run_and_poll.py`).
+- Runnable end-to-end examples for all three simulation types
+  (single-point / sweep / dynamic) reading canonical snake_case result keys,
+  and a corrected README quickstart that uses the real create body
+  (`rotor_groups=[…]` + `battery_component_id`, not the phantom
+  `motor=/propeller=/battery=/throttle=` kwargs).
+
+### Fixed
+
+- **`cursor` pagination** — an explicit `starting_after=` kwarg on
+  `simulations.list`, `sweeps.list`, and `sweeps.list_points` was silently
+  ignored (the backend reads `cursor`). The keyword argument is now `cursor=`.
+  Automatic multi-page iteration was unaffected.
+
+### Corrected (documentation record)
+
+- The 0.1.0 changelog listed a `geometry` resource module and terminal states
+  `succeeded`/`cancelled` that never matched the shipped library. The SDK has
+  **no** `geometry` resource, and the canonical terminal states are
+  `completed` / `failed` / `canceled` (one-L wire spelling), with a
+  `timed_out` client-side sentinel from `wait()`.
+
+## [0.1.2] - 2026-07-08
+
+### Fixed
+
+- **`wait()` now recognizes the canonical terminal states
+  `completed`/`failed`/`canceled`** (one-L `canceled` wire spelling). The
+  previous set omitted `canceled`, so `wait()` polled forever on a canceled
+  run until it hit the timeout sentinel.
+
+## [0.1.1] - 2026-04-28
+
+### Changed
+
+- **License relicensed from MIT to Apache-2.0.** The Apache-2.0 license
+  includes an explicit patent grant scoped to the SDK plus a defensive
+  termination clause (anyone who sues ThrustLab for patent infringement
+  loses the patent grant). MIT had no explicit patent terms. ThrustLab
+  reserves all rights to the underlying simulation methodology that this
+  SDK calls; the license here applies only to this client library.
+- Added `NOTICE` file alongside `LICENSE` per Apache convention.
+
+### Migration from 0.1.0
+
+If you pinned `thrustlab==0.1.0`, upgrade to `thrustlab==0.1.1`. No code
+changes — only the license text differs. Version 0.1.0 has been yanked
+from PyPI.
+
+## [0.1.0] - 2026-04-27
+
+Initial public beta release of the official ThrustLab Python SDK.
+
+### Added
+
+- Full coverage of the `/v1/` API surface across **12 resource modules**:
+  `api_keys`, `users`, `projects`, `simulations`, `sweeps`, `components`,
+  `submissions`, `starred_components`, `geometry`, `credits`,
+  `subscriptions`, `webhook_endpoints`.
+- Sync transport (`httpx.Client`) with bearer-token authentication.
+- Auto-generated `Idempotency-Key` header on every mutating request (override
+  via `idempotency_key=` keyword argument).
+- Exponential backoff + jitter retry on 429, 5xx, and transient network
+  errors (`max_retries=3` default, configurable per client instance).
+- `CursorPager[T]` lazy iterator for cursor-paginated list endpoints;
+  transparent multi-page iteration.
+- `wait()` helpers on `simulations` and `sweeps` for polling async resources
+  to terminal state (`succeeded` / `failed` / `cancelled` / `timed_out`).
+- `Webhook.verify()` for HMAC SHA256 webhook signature verification with
+  configurable timestamp tolerance (default 300 s).
+- Stripe-style typed exception hierarchy:
+  `ThrustlabError` → `APIError` → `AuthenticationError`, `PermissionError`,
+  `NotFoundError`, `ValidationError`, `ConflictError`, `RateLimitError`,
+  `APIServerError`; plus `NetworkError`, `SignatureVerificationError`,
+  `ConfigurationError`.
+- Pydantic v2 models generated from `openapi.json` via
+  `openapi-python-client`; used internally for request/response shaping.
+- Configuration via constructor kwargs (`api_key`, `base_url`, `timeout`,
+  `max_retries`) or env vars (`THRUSTLAB_API_KEY`, `THRUSTLAB_BASE_URL`).
+- 103 unit + integration tests (pytest).
+
+### Out of scope (deferred)
+
+- Async transport (`httpx.AsyncClient`). Planned for v0.2.
+- Streaming response support.
+- Python 3.9 compatibility.
+- CLI tool (`thrustlab` command).
+- SDKs in other languages.
+
+## Pre-release rehearsal procedure
+
+Before tagging v0.1.0, rehearse with:
+
+1. Create a short-lived release-rehearsal branch from master.
+2. Tag `sdk-py-v0.0.1-rc1` and push it.
+3. The CI workflow runs build + TestPyPI publish only (gate step enforces
+   ancestry before either publish step fires).
+4. Delete the rehearsal tag + branch after validation.
+5. Tag `sdk-py-v0.1.0` from the actual master-merge commit for production publish.

{thrustlab-0.1.1 → thrustlab-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thrustlab
-Version: 0.1.1
+Version: 0.3.0
 Summary: Official Python SDK for the ThrustLab API
 Project-URL: Homepage, https://thrustlab.com
 Project-URL: Documentation, https://thrustlab.com/docs
@@ -34,7 +34,7 @@ Description-Content-Type: text/markdown
 
 [![PyPI](https://img.shields.io/pypi/v/thrustlab.svg)](https://pypi.org/project/thrustlab/)
 [![Python](https://img.shields.io/pypi/pyversions/thrustlab.svg)](https://pypi.org/project/thrustlab/)
-[![License](https://img.shields.io/pypi/l/thrustlab.svg)](https://github.com/kylebedrich/thrustlab/blob/master/backend/sdks/python/LICENSE)
+[![License](https://img.shields.io/pypi/l/thrustlab.svg)](https://github.com/kylebedrich/thrustlab-sdk/blob/main/LICENSE)
 
 ## Install
 
@@ -49,23 +49,58 @@ Requires Python 3.10+.
 ```python
 from thrustlab import Client
 
-client = Client(api_key="key_...")  # or set $THRUSTLAB_API_KEY
+client = Client()  # reads $THRUSTLAB_API_KEY (never hard-code the key)
 
 # Create a project
 project = client.projects.create(name="my project")
 
-# Run a simulation and wait for the result
+# Run a single-point simulation and wait for the result.
+# A rotor group carries the motor + propeller + throttle (0–100); the battery
+# and flight condition are top-level. Resolve component IDs from the catalog
+# (client.components.find(name=...)) or paste them directly.
 sim = client.simulations.create(
     project_id=project["id"],
-    motor="comp_motor_xxx",
-    propeller="comp_prop_xxx",
-    battery="comp_batt_xxx",
-    throttle=0.7,
+    battery_component_id="comp_batt_xxx",
+    airspeed_m_s=0.0,
+    density_kg_m3=1.225,
+    battery_charge_pct=100,
+    rotor_groups=[
+        {
+            "label": "main",
+            "count": 4,
+            "motor_component_id": "comp_motor_xxx",
+            "propeller_component_id": "comp_prop_xxx",
+            "throttle_pct": 70,
+        }
+    ],
 )
 result = client.simulations.wait(sim["id"], timeout=300)
-print(result)
+
+# Canonical snake_case result: per-rotor group under "1"/"2"/…, roll-ups
+# under "All" (a sibling `display_labels` map carries the human labels).
+print(result["result"]["1"]["thrust_n"], result["result"]["All"]["total_thrust_n"])
 ```
 
+Runnable end-to-end examples for every simulation type live in
+[`examples/`](./examples): [`simulations/run_sync.py`](./examples/simulations/run_sync.py),
+[`sweeps/run_and_poll.py`](./examples/sweeps/run_and_poll.py), and
+[`dynamic/run_and_poll.py`](./examples/dynamic/run_and_poll.py).
+
+## Why the SDK (and not `urllib` / `wget`)?
+
+Use this SDK — or, if you hand-roll a client, an HTTP library that is **not**
+stdlib `urllib`. Requests from Python's `urllib.request` (and `wget`) are
+**blocked at the Cloudflare edge** by a managed WAF rule matching the literal
+`Python-urllib/*` User-Agent. The block is terminated at the edge: the request
+**never reaches the ThrustLab API**, so you get an opaque HTML *error 1010*
+challenge page — **not** a JSON error envelope. The API cannot return a
+structured error for a request it never sees.
+
+This SDK is built on [`httpx`](https://www.python-httpx.org/) and sends its own
+`thrustlab-python/<version>` User-Agent, so it is **unaffected**. If you must
+hand-roll a client, set an explicit non-`urllib` `User-Agent` header (e.g.
+`requests`, `httpx`, or `curl`) and you will reach the API normally.
+
 ## Configuration
 
 | Setting      | Constructor arg  | Env var               | Default                  |
@@ -80,17 +115,15 @@ print(result)
 Every `/v1/` route family is exposed as an attribute on the client:
 
 ```python
-client.api_keys
 client.users
 client.projects
 client.simulations
 client.sweeps
+client.dynamic_simulations
 client.components
 client.submissions
 client.starred_components
-client.geometry
-client.credits
-client.subscriptions
+client.compute_units
 client.webhook_endpoints
 ```
 
@@ -107,7 +140,7 @@ from thrustlab.exceptions import (
 
 client = Client()
 try:
-    client.simulations.create(project_id="proj_xxx", motor="comp_xxx", ...)
+    client.simulations.create(project_id="proj_xxx", rotor_groups=[...], ...)
 except ValidationError as exc:
     print(f"bad request: {exc.code} ({exc.param}): {exc.message}")
 except RateLimitError as exc:
@@ -139,14 +172,17 @@ first_page = list(client.projects.list(limit=20))
 
 ## Async polling
 
-`simulations.wait()` and `sweeps.wait()` block until the resource reaches a
-terminal state (`succeeded`, `failed`, or `cancelled`) or the timeout fires:
+`simulations.wait()`, `sweeps.wait()`, and `dynamic_simulations.wait()` block
+until the resource reaches a terminal state (`completed`, `failed`, or
+`canceled` — one 'l' on the wire) or the timeout fires. On timeout the returned
+dict carries the SDK-side sentinel `status="timed_out"` (never a server state):
 
 ```python
 sweep = client.sweeps.create(...)
 result = client.sweeps.wait(sweep["id"], timeout=600, poll_interval=2.0)
-if result["status"] == "succeeded":
-    print(result["outputs"])
+if result["status"] == "completed":
+    for point in client.sweeps.list_points(sweep["id"]):
+        print(point["rotors"]["1"]["thrust_n"])
 ```
 
 ## Webhooks
@@ -184,8 +220,8 @@ client = Client(max_retries=0)
 - API reference: https://thrustlab.com/docs/reference
 - SDK guide: https://thrustlab.com/docs/sdk/python
 - Changelog: https://thrustlab.com/docs/changelog
-- Issue tracker: https://github.com/kylebedrich/thrustlab/issues
+- Issue tracker: https://github.com/kylebedrich/thrustlab-sdk/issues
 
 ## License
 
-MIT
+Apache-2.0. See [`LICENSE`](./LICENSE) and [`NOTICE`](./NOTICE).

{thrustlab-0.1.1 → thrustlab-0.3.0}/README.md

@@ -2,7 +2,7 @@
 
 [![PyPI](https://img.shields.io/pypi/v/thrustlab.svg)](https://pypi.org/project/thrustlab/)
 [![Python](https://img.shields.io/pypi/pyversions/thrustlab.svg)](https://pypi.org/project/thrustlab/)
-[![License](https://img.shields.io/pypi/l/thrustlab.svg)](https://github.com/kylebedrich/thrustlab/blob/master/backend/sdks/python/LICENSE)
+[![License](https://img.shields.io/pypi/l/thrustlab.svg)](https://github.com/kylebedrich/thrustlab-sdk/blob/main/LICENSE)
 
 ## Install
 
@@ -17,23 +17,58 @@ Requires Python 3.10+.
 ```python
 from thrustlab import Client
 
-client = Client(api_key="key_...")  # or set $THRUSTLAB_API_KEY
+client = Client()  # reads $THRUSTLAB_API_KEY (never hard-code the key)
 
 # Create a project
 project = client.projects.create(name="my project")
 
-# Run a simulation and wait for the result
+# Run a single-point simulation and wait for the result.
+# A rotor group carries the motor + propeller + throttle (0–100); the battery
+# and flight condition are top-level. Resolve component IDs from the catalog
+# (client.components.find(name=...)) or paste them directly.
 sim = client.simulations.create(
     project_id=project["id"],
-    motor="comp_motor_xxx",
-    propeller="comp_prop_xxx",
-    battery="comp_batt_xxx",
-    throttle=0.7,
+    battery_component_id="comp_batt_xxx",
+    airspeed_m_s=0.0,
+    density_kg_m3=1.225,
+    battery_charge_pct=100,
+    rotor_groups=[
+        {
+            "label": "main",
+            "count": 4,
+            "motor_component_id": "comp_motor_xxx",
+            "propeller_component_id": "comp_prop_xxx",
+            "throttle_pct": 70,
+        }
+    ],
 )
 result = client.simulations.wait(sim["id"], timeout=300)
-print(result)
+
+# Canonical snake_case result: per-rotor group under "1"/"2"/…, roll-ups
+# under "All" (a sibling `display_labels` map carries the human labels).
+print(result["result"]["1"]["thrust_n"], result["result"]["All"]["total_thrust_n"])
 ```
 
+Runnable end-to-end examples for every simulation type live in
+[`examples/`](./examples): [`simulations/run_sync.py`](./examples/simulations/run_sync.py),
+[`sweeps/run_and_poll.py`](./examples/sweeps/run_and_poll.py), and
+[`dynamic/run_and_poll.py`](./examples/dynamic/run_and_poll.py).
+
+## Why the SDK (and not `urllib` / `wget`)?
+
+Use this SDK — or, if you hand-roll a client, an HTTP library that is **not**
+stdlib `urllib`. Requests from Python's `urllib.request` (and `wget`) are
+**blocked at the Cloudflare edge** by a managed WAF rule matching the literal
+`Python-urllib/*` User-Agent. The block is terminated at the edge: the request
+**never reaches the ThrustLab API**, so you get an opaque HTML *error 1010*
+challenge page — **not** a JSON error envelope. The API cannot return a
+structured error for a request it never sees.
+
+This SDK is built on [`httpx`](https://www.python-httpx.org/) and sends its own
+`thrustlab-python/<version>` User-Agent, so it is **unaffected**. If you must
+hand-roll a client, set an explicit non-`urllib` `User-Agent` header (e.g.
+`requests`, `httpx`, or `curl`) and you will reach the API normally.
+
 ## Configuration
 
 | Setting      | Constructor arg  | Env var               | Default                  |
@@ -48,17 +83,15 @@ print(result)
 Every `/v1/` route family is exposed as an attribute on the client:
 
 ```python
-client.api_keys
 client.users
 client.projects
 client.simulations
 client.sweeps
+client.dynamic_simulations
 client.components
 client.submissions
 client.starred_components
-client.geometry
-client.credits
-client.subscriptions
+client.compute_units
 client.webhook_endpoints
 ```
 
@@ -75,7 +108,7 @@ from thrustlab.exceptions import (
 
 client = Client()
 try:
-    client.simulations.create(project_id="proj_xxx", motor="comp_xxx", ...)
+    client.simulations.create(project_id="proj_xxx", rotor_groups=[...], ...)
 except ValidationError as exc:
     print(f"bad request: {exc.code} ({exc.param}): {exc.message}")
 except RateLimitError as exc:
@@ -107,14 +140,17 @@ first_page = list(client.projects.list(limit=20))
 
 ## Async polling
 
-`simulations.wait()` and `sweeps.wait()` block until the resource reaches a
-terminal state (`succeeded`, `failed`, or `cancelled`) or the timeout fires:
+`simulations.wait()`, `sweeps.wait()`, and `dynamic_simulations.wait()` block
+until the resource reaches a terminal state (`completed`, `failed`, or
+`canceled` — one 'l' on the wire) or the timeout fires. On timeout the returned
+dict carries the SDK-side sentinel `status="timed_out"` (never a server state):
 
 ```python
 sweep = client.sweeps.create(...)
 result = client.sweeps.wait(sweep["id"], timeout=600, poll_interval=2.0)
-if result["status"] == "succeeded":
-    print(result["outputs"])
+if result["status"] == "completed":
+    for point in client.sweeps.list_points(sweep["id"]):
+        print(point["rotors"]["1"]["thrust_n"])
 ```
 
 ## Webhooks
@@ -152,8 +188,8 @@ client = Client(max_retries=0)
 - API reference: https://thrustlab.com/docs/reference
 - SDK guide: https://thrustlab.com/docs/sdk/python
 - Changelog: https://thrustlab.com/docs/changelog
-- Issue tracker: https://github.com/kylebedrich/thrustlab/issues
+- Issue tracker: https://github.com/kylebedrich/thrustlab-sdk/issues
 
 ## License
 
-MIT
+Apache-2.0. See [`LICENSE`](./LICENSE) and [`NOTICE`](./NOTICE).

thrustlab-0.3.0/ci/public-ci.yml

@@ -0,0 +1,35 @@
+# Public CI for the standalone thrustlab-sdk repository.
+#
+# This file is the SOURCE template kept in the monorepo. The extraction script
+# (scripts/publish_public_repo.sh) copies it into the public mirror as
+# .github/workflows/ci.yml. It installs the package and runs the unit test
+# suite (integration tests, which require a live API key, are excluded).
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package + test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run unit tests
+        run: pytest -m "not integration" -ra --tb=short

thrustlab-0.3.0/examples/components/create_component.py

@@ -0,0 +1,106 @@
+"""Create your own custom motor, battery, and propeller from spec_json.
+
+Run it:
+    export THRUSTLAB_API_KEY=key_...        # never hard-code the key
+    python examples/components/create_component.py
+
+A custom component is `POST /v1/components` with three fields: `type`
+(motor | battery | propeller), `name`, and a type-specific `spec_json` map. The
+create is scoped to your account (source="user", visibility="private"); the
+returned resource echoes back an `id` (comp_...) you pass to a simulation.
+
+Each create below is `client.components.create(...)`. Field names, units, and
+accepted ranges come from the server-side validators — see the reference page
+for the full tables.
+
+Notes on validation:
+  * Battery: a physical pack needs chemistry, cell layout, capacity, weight_g,
+    one resistance figure (c_rating or pack_resistance_mOhm), and bounding-box
+    dims; form_factor is derived from chemistry when omitted.
+  * Propeller: per-station radius/chord/twist and rotation are required, and
+    persisting a propeller needs the hobbyist tier or higher — the create below
+    reports the tier gate cleanly on a free account.
+"""
+
+from thrustlab import Client
+from thrustlab.exceptions import APIError
+
+client = Client()  # reads $THRUSTLAB_API_KEY from the environment
+
+# ---- motor ---------------------------------------------------------------
+# Required: kv, n (pole count), R (phase-to-phase winding resistance, ohms),
+# weight, diameter, length, u_nominal, iq_nominal, and one of iq_max /
+# power_max. Inductance L and rotor inertia are auto-estimated from
+# kv/n/diameter/length/weight — inertia is required for dynamic (time-domain)
+# runs, so give real dimensions and mass.
+motor = client.components.create(
+    type="motor",
+    name="My Custom 4260 800Kv",
+    spec_json={
+        "brand": "Custom",
+        "kv": 800.0,            # rpm per volt
+        "n": 14,                # magnet pole count
+        "R": 0.042,             # phase-to-phase winding resistance (ohm)
+        "weight": 120.0,        # g
+        "diameter": 42.0,       # mm (drives L / inertia estimation)
+        "length": 25.0,         # mm
+        "u_nominal": 14.8,      # nominal voltage (V)
+        "iq_nominal": 1.1,      # no-load / idle current (A)
+        "iq_max": 65.0,         # max quadrature current (A)
+        "power_max": 960.0,     # max electrical power (W)
+        "topology": "outrunner",
+    },
+)
+print(f"created motor {motor['id']}")
+
+# ---- battery -------------------------------------------------------------
+# chemistry in {lipo, lihv, nmc, nca, lfp, nimh, source}. A physical pack needs
+# its cell layout, capacity, weight_g, one resistance figure (c_rating or
+# pack_resistance_mOhm), and length/width/height_mm (1..2000 mm). form_factor
+# is derived (lipo -> pouch) when omitted. Pack cap: series <= 24, S*P <= 256.
+battery = client.components.create(
+    type="battery",
+    name="My Custom 4S 5000mAh",
+    spec_json={
+        "brand": "Custom",
+        "chemistry": "lipo",
+        "series_cells": 4,
+        "parallel_cells": 1,
+        "total_capacity_mAh": 5000.0,
+        "c_rating": 75.0,
+        "weight_g": 480.0,
+        "length_mm": 145.0,     # required for a physical chemistry
+        "width_mm": 49.0,
+        "height_mm": 33.0,
+    },
+)
+print(f"created battery {battery['id']}")
+
+# ---- propeller (hobbyist tier or higher) ---------------------------------
+# Required: diameter, pitch, rotation, weight, and the per-station blade
+# geometry — parallel radius/chord/twist arrays, hub -> tip (<= 50 stations;
+# radius and chord in METERS, twist in degrees). inertia is required for
+# dynamic (time-domain) runs and is estimated from weight + diameter when
+# omitted.
+try:
+    prop = client.components.create(
+        type="propeller",
+        name="My Custom 10.5x4.5",
+        spec_json={
+            "brand": "Custom",
+            "diameter": 10.5,   # inch
+            "pitch": 4.5,       # inch
+            "num_blades": 2,
+            "rotation": "ccw",  # top view; "cw" | "ccw" | "both"
+            "weight": 14.0,     # g
+            "inertia": 8.3e-5,  # kg*m^2 — required for dynamic runs
+            # per-station geometry, hub -> tip (r/R = 0.20 .. 1.00)
+            "radius": [0.0267, 0.0400, 0.0600, 0.0800, 0.1000, 0.1200, 0.1334],  # m
+            "chord": [0.016, 0.019, 0.022, 0.021, 0.018, 0.014, 0.008],          # m
+            "twist": [30.0, 24.0, 17.0, 12.8, 10.3, 8.6, 7.8],                   # deg
+        },
+    )
+    print(f"created propeller {prop['id']}")
+except APIError as exc:
+    # A free account 402s here (propeller persistence is a creator_edit gate).
+    print(f"propeller create skipped: {exc}")