autoassembler 0.3.1__tar.gz

autoassembler-0.3.1/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Fern local artifacts
+**/.preview
+**/.definition
+
+# Fern generator provenance (contains volatile git SHA/dirty flag)
+**/.fern/
+
+# uv lock — not committed for a library SDK
+uv.lock
+
+# IDE
+.idea/
+
+# The API service checkout the spec sync builds from
+.api-service/
+
+# Local credentials and environment overrides (sanitized templates may be committed)
+.env
+.env.*
+!.env.example
+!.env.*.example
+credentials.json
+credentials.json.tmp
+.credentials-*.tmp
+*.pem
+*.key
+.aws/
+
+# Local CAD inputs: use synthetic, reviewed fixtures if a test needs one
+*.step
+*.stp
+*.pvz
+*.STEP
+*.STP
+*.PVZ

autoassembler-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C-Infinity
+
+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.

autoassembler-0.3.1/Makefile

@@ -0,0 +1,23 @@
+# AutoAssembler Python SDK — dev tasks. Regeneration is shared: see the root Makefile.
+
+# Files, not the _custom directory: ruff's extend-exclude on src/autoassembler/** would skip a directory.
+CUSTOM := src/autoassembler/client.py src/autoassembler/operation.py src/autoassembler/_version.py $(wildcard src/autoassembler/_custom/*.py) tests examples
+
+.PHONY: help post-generate lint typecheck test
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "  %-14s %s\n", $$1, $$2}'
+
+post-generate: ## Surface Fern's reference.md and drop its README/CONTRIBUTING (run by the root `make generate`)
+	mv -f src/autoassembler/reference.md reference.md
+	rm -f src/autoassembler/CONTRIBUTING.md src/autoassembler/README.md   # Fern's; ours are python/README.md and the root's
+
+lint: ## Ruff-check the hand-written custom code + tests
+	uv run ruff check $(CUSTOM)
+
+typecheck: ## Pyright type-check the hand-written surface (config in pyproject)
+	uv run pyright
+
+test: ## Run the test suite
+	uv run pytest -q

autoassembler-0.3.1/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.5
+Name: autoassembler
+Version: 0.3.1
+Summary: Autoassembler Python SDK for AI Process Planning
+Project-URL: Homepage, https://autoassembler.com/
+Project-URL: Repository, https://github.com/cinf-org/autoassembler-sdk
+Project-URL: Documentation, https://github.com/cinf-org/autoassembler-sdk/blob/main/python/reference.md
+Project-URL: Issues, https://github.com/cinf-org/autoassembler-sdk/issues
+Project-URL: Changelog, https://github.com/cinf-org/autoassembler-sdk/releases
+Author-email: C-Infinity <info@c-infinity.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: assembly planning,autoassembler,cad,dfa,manufacturing,process planning,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.21.2
+Requires-Dist: pydantic>=2.5
+Requires-Dist: typing-extensions>=4.6.1
+Description-Content-Type: text/markdown
+
+# AutoAssembler Python SDK
+
+[AutoAssembler](https://autoassembler.com) is [C-Infinity](https://c-infinity.ai)'s foundational AI for
+assembly process planning: read a CAD assembly, analyze its geometry, motion and production logic,
+and turn that into manufacturing process plans, diff analysis, DFA analysis, work instructions and more.
+This package is the official Python client for the AutoAssembler API. From a script or a notebook you can:
+
+- **Upload** a CAD assembly (STEP, PVZ) and get a processed `Assembly` back.
+- **Plan** it: create a process plan, assign parts to stations, let the planner work out the
+  assembly sequence, then **validate** that every station is physically buildable.
+- **Diff** two revisions of an assembly and **adapt** an existing plan to the new one.
+
+> **Status: 0.x.** The surface may still change between minor releases; see
+> [Versioning](#versioning). The v4 API is stable, except the operations under `client.alpha`.
+
+## Documentation
+
+- Check the [Quickstart](#quickstart) below, then the runnable scripts in [`examples/`](https://github.com/cinf-org/autoassembler-sdk/tree/main/python/examples).
+- [`reference.md`](https://github.com/cinf-org/autoassembler-sdk/blob/main/python/reference.md): every endpoint of the API as exposed by `client.api`.
+- [Release notes](https://github.com/cinf-org/autoassembler-sdk/releases).
+
+## Installation
+
+```sh
+pip install autoassembler        # or: uv add autoassembler
+```
+
+Requires **Python 3.12+**. The only runtime dependencies are `httpx`, `pydantic>=2.5` and
+`typing-extensions`.
+
+## Authentication
+
+Create an API key in the AutoAssembler app under
+**Settings → API keys → Create API key**, then either pass it explicitly, set
+`AA_TOKEN`, or log in interactively once:
+
+```python
+from autoassembler import AutoAssembler
+
+client = AutoAssembler(token="aa_...")     # explicit (CI, scripts)
+client = AutoAssembler()                   # reads AA_TOKEN, or the token stored by login()
+```
+
+```python
+import autoassembler
+_ = autoassembler.login()   # confirm in your browser; stores the token for 30 days
+```
+
+`login()` stores tokens in `~/.config/autoassembler/credentials.json`; `logout()` forgets them.
+`login()` also returns the token: assign its result as above to avoid displaying it in a
+notebook or interactive shell. Do not commit credentials or include them in reports.
+`logout()` removes the local copy; it does not revoke the token on the server.
+Pass `base_url=` to both `login()` and `AutoAssembler()` for anything but `https://app.autoassembler.com`,
+including your own deployment.
+
+## Quickstart
+
+Use your own CAD files in place of the example filenames below; no CAD data is bundled.
+These calls upload the files to the configured service and create resources in your account.
+
+```python
+from autoassembler import AutoAssembler
+
+client = AutoAssembler()
+
+# Upload two revisions of a design. Processing overlaps on the server; wait for both.
+v1, v2 = (op.result() for op in (client.assemblies.upload("gearbox_v1.step"),
+                                  client.assemblies.upload("gearbox_v2.step")))
+
+# Plan v1 from scratch: one station with every part, plan it, check it is buildable.
+mpp = client.planning.create_mpp(v1, name="Gearbox v1")   # a manufacturing process plan
+station = mpp.add_station("Final assembly")
+outcome = mpp.plan(station).result()           # complete | partial | failed
+verdict = mpp.validate(station).result()       # feasible | infeasible
+print(outcome[station].status, verdict[station].status, mpp.viewer_url)
+
+# What changed in v2, and v1's plan carried over to it.
+diff = client.assemblies.diff(v1, v2).result()
+mpp_v2 = client.planning.adapt(mpp, v2, diff=diff).result()
+```
+
+Runnable versions of each step, with flags and error handling, live in
+[`examples/`](https://github.com/cinf-org/autoassembler-sdk/tree/main/python/examples).
+
+## How the SDK is organized
+
+- **Concepts.** `Assembly` (a CAD file the service knows) and `ProcessPlan` (a manufacturing
+  process plan for one assembly, made of `Station`s).
+- **Actions.** `upload`, `diff`, `plan`, `validate`, `evaluate_dfa`, `adapt`. An action that creates
+  a resource lives on a namespace (`client.assemblies.upload`, `client.planning.adapt`); an action
+  that acts on an existing resource lives on that resource's handle (`mpp.plan(station)`).
+- **Waiting.** Anything that outlives its HTTP request returns an `Operation[T]`.
+  `op.result(timeout=None)` polls with backoff and returns `T`, or raises `OperationFailed` /
+  `OperationTimeout`; `op.done()` checks without blocking. Start several, then collect:
+
+  ```python
+  ops = [client.assemblies.upload(p) for p in cad_files]
+  assemblies = [op.result() for op in ops]
+  ```
+
+Outcomes use the document's own words: a station's planning status is `pending`, `complete`,
+`partial` (a usable partial plan) or `failed`; its validation verdict is `feasible` or
+`infeasible`, with the issues behind it; an assembly is `processing`, `ready` or `failed`.
+
+### The full API: `client.api`
+
+The curated layer above is built on a client generated from the v4 OpenAPI spec, available
+as `client.api` (`client.api.assemblies.get_status(...)`, `client.api.planning.get_mpp(...)`).
+Use it when the vocabulary above does not cover what you need, and
+[tell us](https://github.com/cinf-org/autoassembler-sdk/issues) what was missing.
+Every endpoint is documented in
+[`reference.md`](https://github.com/cinf-org/autoassembler-sdk/blob/main/python/reference.md).
+
+An operation can be resumed by name from any process:
+`client.operations.handle("operations/…").result()`.
+
+### Errors
+
+| Failure | Raised as |
+|---|---|
+| The server answered with an error status | `ApiError` (`status_code`, `body`, `headers`), or a typed subclass: `BadRequestError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `UnprocessableEntityError` |
+| The response did not match the expected schema | `ParsingError` (not an `ApiError`) |
+| No response at all (DNS, connection, timeout) | `httpx.HTTPError` subclasses |
+| A long-running operation failed or was cancelled | `OperationFailed` (`code`, `message`, `operation`) |
+| A long-running operation did not finish in time | `OperationTimeout` (a `TimeoutError`) |
+
+### Async
+
+`AsyncAutoAssembler` currently exposes the generated client (`client.api`) and
+`client.operations`; the curated `assemblies` / `planning` namespaces arrive on the async
+client in a later release under the same names, with `asyncio.gather` as the natural way to
+run work in parallel.
+
+### Advanced
+
+- **Timeouts.** 60 s per request by default: `AutoAssembler(timeout=20.0)` or
+  `request_options={"timeout": 5}` per call.
+- **Retries.** Requests that fail with 408, 409, 429 or 5xx are retried twice with backoff;
+  `request_options={"max_retries": 0}` turns it off per call.
+- **Your own `httpx` client**, for proxies or transports:
+  `AutoAssembler(httpx_client=httpx.Client(proxy="http://..."))`.
+- **Raw responses.** `client.api.<namespace>.with_raw_response.<method>()` returns headers and
+  status alongside the parsed data.
+- **Context managers.** `with AutoAssembler() as client:` closes the connection pool.
+
+## Compatibility
+
+| | |
+|---|---|
+| API | AutoAssembler **v4** (`autoassembler.API_VERSION == "v4"`). The client is generated from the published v4 OpenAPI spec; `fern/openapi/source.json` records which revision. |
+| Servers | `https://app.autoassembler.com` by default; any AutoAssembler deployment that serves the v4 API via `base_url=`. |
+
+## Versioning
+
+The package follows [semantic versioning](https://semver.org/), independently of the API
+version. While 0.x, a minor release may change the surface and a patch release only fixes;
+from 1.0, breaking changes need a major release and removals are deprecated for one minor
+release first. Each release's notes are on
+[GitHub Releases](https://github.com/cinf-org/autoassembler-sdk/releases).
+
+### Alpha
+
+Operations the API offers before they are stable sit under `client.alpha` (also
+`client.api.alpha`): today `client.alpha.jobs` and `client.alpha.planning.apply_ops`. They are
+outside these guarantees: any release may change or remove them. An operation that becomes
+stable moves out of `alpha`, to its namespace's usual place.
+
+## Contributing
+
+Bug reports and feature requests: [issues](https://github.com/cinf-org/autoassembler-sdk/issues).
+Most of `python/src/autoassembler/` is generated from the OpenAPI spec and regenerated on every API
+change, so changes there cannot be merged directly; the hand-written layer (`client.py`,
+`operation.py`, `_custom/`), the examples and the docs welcome pull requests. See
+[`CONTRIBUTING.md`](https://github.com/cinf-org/autoassembler-sdk/blob/main/CONTRIBUTING.md)
+and, for maintainers, [`DEVELOPMENT.md`](https://github.com/cinf-org/autoassembler-sdk/blob/main/DEVELOPMENT.md).
+
+## License
+
+[MIT](https://github.com/cinf-org/autoassembler-sdk/blob/main/LICENSE) © C-Infinity.

autoassembler-0.3.1/README.md

@@ -0,0 +1,179 @@
+# AutoAssembler Python SDK
+
+[AutoAssembler](https://autoassembler.com) is [C-Infinity](https://c-infinity.ai)'s foundational AI for
+assembly process planning: read a CAD assembly, analyze its geometry, motion and production logic,
+and turn that into manufacturing process plans, diff analysis, DFA analysis, work instructions and more.
+This package is the official Python client for the AutoAssembler API. From a script or a notebook you can:
+
+- **Upload** a CAD assembly (STEP, PVZ) and get a processed `Assembly` back.
+- **Plan** it: create a process plan, assign parts to stations, let the planner work out the
+  assembly sequence, then **validate** that every station is physically buildable.
+- **Diff** two revisions of an assembly and **adapt** an existing plan to the new one.
+
+> **Status: 0.x.** The surface may still change between minor releases; see
+> [Versioning](#versioning). The v4 API is stable, except the operations under `client.alpha`.
+
+## Documentation
+
+- Check the [Quickstart](#quickstart) below, then the runnable scripts in [`examples/`](https://github.com/cinf-org/autoassembler-sdk/tree/main/python/examples).
+- [`reference.md`](https://github.com/cinf-org/autoassembler-sdk/blob/main/python/reference.md): every endpoint of the API as exposed by `client.api`.
+- [Release notes](https://github.com/cinf-org/autoassembler-sdk/releases).
+
+## Installation
+
+```sh
+pip install autoassembler        # or: uv add autoassembler
+```
+
+Requires **Python 3.12+**. The only runtime dependencies are `httpx`, `pydantic>=2.5` and
+`typing-extensions`.
+
+## Authentication
+
+Create an API key in the AutoAssembler app under
+**Settings → API keys → Create API key**, then either pass it explicitly, set
+`AA_TOKEN`, or log in interactively once:
+
+```python
+from autoassembler import AutoAssembler
+
+client = AutoAssembler(token="aa_...")     # explicit (CI, scripts)
+client = AutoAssembler()                   # reads AA_TOKEN, or the token stored by login()
+```
+
+```python
+import autoassembler
+_ = autoassembler.login()   # confirm in your browser; stores the token for 30 days
+```
+
+`login()` stores tokens in `~/.config/autoassembler/credentials.json`; `logout()` forgets them.
+`login()` also returns the token: assign its result as above to avoid displaying it in a
+notebook or interactive shell. Do not commit credentials or include them in reports.
+`logout()` removes the local copy; it does not revoke the token on the server.
+Pass `base_url=` to both `login()` and `AutoAssembler()` for anything but `https://app.autoassembler.com`,
+including your own deployment.
+
+## Quickstart
+
+Use your own CAD files in place of the example filenames below; no CAD data is bundled.
+These calls upload the files to the configured service and create resources in your account.
+
+```python
+from autoassembler import AutoAssembler
+
+client = AutoAssembler()
+
+# Upload two revisions of a design. Processing overlaps on the server; wait for both.
+v1, v2 = (op.result() for op in (client.assemblies.upload("gearbox_v1.step"),
+                                  client.assemblies.upload("gearbox_v2.step")))
+
+# Plan v1 from scratch: one station with every part, plan it, check it is buildable.
+mpp = client.planning.create_mpp(v1, name="Gearbox v1")   # a manufacturing process plan
+station = mpp.add_station("Final assembly")
+outcome = mpp.plan(station).result()           # complete | partial | failed
+verdict = mpp.validate(station).result()       # feasible | infeasible
+print(outcome[station].status, verdict[station].status, mpp.viewer_url)
+
+# What changed in v2, and v1's plan carried over to it.
+diff = client.assemblies.diff(v1, v2).result()
+mpp_v2 = client.planning.adapt(mpp, v2, diff=diff).result()
+```
+
+Runnable versions of each step, with flags and error handling, live in
+[`examples/`](https://github.com/cinf-org/autoassembler-sdk/tree/main/python/examples).
+
+## How the SDK is organized
+
+- **Concepts.** `Assembly` (a CAD file the service knows) and `ProcessPlan` (a manufacturing
+  process plan for one assembly, made of `Station`s).
+- **Actions.** `upload`, `diff`, `plan`, `validate`, `evaluate_dfa`, `adapt`. An action that creates
+  a resource lives on a namespace (`client.assemblies.upload`, `client.planning.adapt`); an action
+  that acts on an existing resource lives on that resource's handle (`mpp.plan(station)`).
+- **Waiting.** Anything that outlives its HTTP request returns an `Operation[T]`.
+  `op.result(timeout=None)` polls with backoff and returns `T`, or raises `OperationFailed` /
+  `OperationTimeout`; `op.done()` checks without blocking. Start several, then collect:
+
+  ```python
+  ops = [client.assemblies.upload(p) for p in cad_files]
+  assemblies = [op.result() for op in ops]
+  ```
+
+Outcomes use the document's own words: a station's planning status is `pending`, `complete`,
+`partial` (a usable partial plan) or `failed`; its validation verdict is `feasible` or
+`infeasible`, with the issues behind it; an assembly is `processing`, `ready` or `failed`.
+
+### The full API: `client.api`
+
+The curated layer above is built on a client generated from the v4 OpenAPI spec, available
+as `client.api` (`client.api.assemblies.get_status(...)`, `client.api.planning.get_mpp(...)`).
+Use it when the vocabulary above does not cover what you need, and
+[tell us](https://github.com/cinf-org/autoassembler-sdk/issues) what was missing.
+Every endpoint is documented in
+[`reference.md`](https://github.com/cinf-org/autoassembler-sdk/blob/main/python/reference.md).
+
+An operation can be resumed by name from any process:
+`client.operations.handle("operations/…").result()`.
+
+### Errors
+
+| Failure | Raised as |
+|---|---|
+| The server answered with an error status | `ApiError` (`status_code`, `body`, `headers`), or a typed subclass: `BadRequestError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `UnprocessableEntityError` |
+| The response did not match the expected schema | `ParsingError` (not an `ApiError`) |
+| No response at all (DNS, connection, timeout) | `httpx.HTTPError` subclasses |
+| A long-running operation failed or was cancelled | `OperationFailed` (`code`, `message`, `operation`) |
+| A long-running operation did not finish in time | `OperationTimeout` (a `TimeoutError`) |
+
+### Async
+
+`AsyncAutoAssembler` currently exposes the generated client (`client.api`) and
+`client.operations`; the curated `assemblies` / `planning` namespaces arrive on the async
+client in a later release under the same names, with `asyncio.gather` as the natural way to
+run work in parallel.
+
+### Advanced
+
+- **Timeouts.** 60 s per request by default: `AutoAssembler(timeout=20.0)` or
+  `request_options={"timeout": 5}` per call.
+- **Retries.** Requests that fail with 408, 409, 429 or 5xx are retried twice with backoff;
+  `request_options={"max_retries": 0}` turns it off per call.
+- **Your own `httpx` client**, for proxies or transports:
+  `AutoAssembler(httpx_client=httpx.Client(proxy="http://..."))`.
+- **Raw responses.** `client.api.<namespace>.with_raw_response.<method>()` returns headers and
+  status alongside the parsed data.
+- **Context managers.** `with AutoAssembler() as client:` closes the connection pool.
+
+## Compatibility
+
+| | |
+|---|---|
+| API | AutoAssembler **v4** (`autoassembler.API_VERSION == "v4"`). The client is generated from the published v4 OpenAPI spec; `fern/openapi/source.json` records which revision. |
+| Servers | `https://app.autoassembler.com` by default; any AutoAssembler deployment that serves the v4 API via `base_url=`. |
+
+## Versioning
+
+The package follows [semantic versioning](https://semver.org/), independently of the API
+version. While 0.x, a minor release may change the surface and a patch release only fixes;
+from 1.0, breaking changes need a major release and removals are deprecated for one minor
+release first. Each release's notes are on
+[GitHub Releases](https://github.com/cinf-org/autoassembler-sdk/releases).
+
+### Alpha
+
+Operations the API offers before they are stable sit under `client.alpha` (also
+`client.api.alpha`): today `client.alpha.jobs` and `client.alpha.planning.apply_ops`. They are
+outside these guarantees: any release may change or remove them. An operation that becomes
+stable moves out of `alpha`, to its namespace's usual place.
+
+## Contributing
+
+Bug reports and feature requests: [issues](https://github.com/cinf-org/autoassembler-sdk/issues).
+Most of `python/src/autoassembler/` is generated from the OpenAPI spec and regenerated on every API
+change, so changes there cannot be merged directly; the hand-written layer (`client.py`,
+`operation.py`, `_custom/`), the examples and the docs welcome pull requests. See
+[`CONTRIBUTING.md`](https://github.com/cinf-org/autoassembler-sdk/blob/main/CONTRIBUTING.md)
+and, for maintainers, [`DEVELOPMENT.md`](https://github.com/cinf-org/autoassembler-sdk/blob/main/DEVELOPMENT.md).
+
+## License
+
+[MIT](https://github.com/cinf-org/autoassembler-sdk/blob/main/LICENSE) © C-Infinity.

autoassembler-0.3.1/examples/README.md

@@ -0,0 +1,117 @@
+# Examples
+
+These scripts are the acceptance test of the SDK's surface: the test suite runs each of
+them offline against a scripted server (`tests/test_examples.py`).
+
+One script per example. The module docstring is the explanation (`uv run <script> --help`
+prints it); dependencies are declared inline (PEP 723), so `uv run` fetches them with no
+install.
+
+| Script | What it shows |
+|---|---|
+| [`login.py`](./login.py) | Log in once with the device flow; later scripts construct `AutoAssembler()` with no token. |
+| [`upload.py`](./upload.py) | CAD files become `Assembly`s you can use; several at once, no threads. |
+| [`diff.py`](./diff.py) | Compare two assemblies and read the report. |
+| [`plan.py`](./plan.py) | Plan an assembly from scratch, then check the plan is buildable. |
+| [`adapt.py`](./adapt.py) | Carry a process plan over to a revised assembly, from the diff between the two. |
+| [`upload_async.py`](./upload_async.py) | The upload flow on the async client, with `asyncio.gather`. Target for the async release; not runnable yet. |
+
+## Running one
+
+```sh
+cd python/examples                           # from the repository root
+export AA_TOKEN="your-api-key"                 # Settings → API keys in the app
+export AA_URL="https://app.autoassembler.com"  # optional; this is the default
+
+uv run login.py                                # instead of AA_TOKEN: log in once in the browser
+uv run upload.py v1.step v2.step               # one or more .step/.stp/.pvz files; prints each assembly id
+uv run diff.py <reference_id> <target_id>      # two assembly ids, e.g. from upload.py
+uv run plan.py <assembly_id> [--name NAME]     # prints the new plan's id
+uv run adapt.py <reference_id> <reference_mpp_id> <target_id> [--name NAME]   # the plan from plan.py, onto a revision
+```
+
+`upload.py`, `plan.py` and `adapt.py` also take `--timeout SECONDS` (default 1800) for how long
+to wait on the server.
+
+Instead of `AA_TOKEN`, log in once with `uv run login.py` (the device flow, confirmed in your
+browser); the token is stored under `~/.config/autoassembler/` and the scripts, which construct
+`AutoAssembler()` without a token, find it.
+
+The runnable CAD examples exit non-zero on failure and clean up resources they create.
+`login.py` deliberately keeps the local credential. `upload_async.py` is a preview of
+the future API and is not runnable in the current release.
+
+From a checkout of this repository, `uv run python upload.py ...` runs a script against the
+checkout's own code instead of the released package: the project environment has the SDK
+installed in editable mode, and the inline dependency header is not consulted.
+
+## The walkthrough: from two CAD revisions to a plan and a diff
+
+The examples compose into one end-to-end flow:
+
+```python
+uploads = [client.assemblies.upload(p) for p in ("gearbox_v1.step", "gearbox_v2.step")]
+v1, v2 = (op.result(timeout=1800) for op in uploads)      # both processed in parallel
+
+report = client.assemblies.diff(v1, v2).result(timeout=1800)
+print(f"{report.summary.candidate_swaps} candidate swaps")
+
+mpp = client.planning.create_mpp(v2, name="Gearbox v2 — greenfield")
+station = mpp.add_station("Final assembly")
+if mpp.plan(station).result(timeout=1800)[station].status == "failed":
+    raise SystemExit("no plan")
+print(mpp.viewer_url)
+```
+
+## Parallel work, sync and async
+
+Starting an operation and waiting for it are separate calls, so the **sync** client runs
+work in parallel without threads: start everything, then collect. The file transfers
+happen one after another, but the processing, which dominates, overlaps on the server, so
+the wall-clock cost is roughly one transfer per file plus the slowest processing.
+
+```python
+ops = [client.assemblies.upload(p) for p in cad_files]     # N uploads, all processing
+assemblies = [op.result(timeout=1800) for op in ops]       # ≈ as long as the slowest one
+```
+
+The **async** client has every verb under the same name. Starting an operation is itself
+an HTTP call, so it is awaited; the handle is then awaited to completion. Two awaits, which
+is exactly what makes `asyncio.gather` natural:
+
+```python
+import asyncio
+from autoassembler import AsyncAutoAssembler
+
+client = AsyncAutoAssembler(token=...)
+ops = await asyncio.gather(*(client.assemblies.upload(p) for p in cad_files))
+assemblies = await asyncio.gather(*(op.result(timeout=1800) for op in ops))
+report = await (await client.assemblies.diff(assemblies[0], assemblies[1])).result()
+```
+
+Async pollers sleep with `asyncio.sleep`, so a hundred pending operations are a hundred
+coroutines, not a hundred threads. See [`upload_async.py`](./upload_async.py). The curated
+namespaces ship sync-first, so that script is the target for the async release; until
+then `AsyncAutoAssembler` offers the generated client at `client.api`.
+
+Both clients can also be used as context managers (`with AutoAssembler(...) as client:`,
+`async with AsyncAutoAssembler(...) as client:`), which closes the HTTP connection pool when
+the block ends. The examples construct the client plainly; both forms are fine.
+
+## When you need the wire
+
+The generated client is one attribute away and documents every endpoint
+([`reference.md`](../reference.md)): `client.api.assemblies.get_status("user", id)`,
+`client.api.planning.get_mpp(...)`. The curated namespaces above are built on it; use it
+when the vocabulary here does not cover what you need, and tell us what was missing.
+
+## Adding an example
+
+1. Copy the closest script. Keep the PEP 723 header, the `uv run` shebang and the
+   `AA_TOKEN` / `AA_URL` environment contract.
+2. Write the module docstring first: what it does, the key steps as a list, what it assumes.
+   That docstring is the documentation; there is no separate README.
+3. Exit non-zero on failure and clean up what you created, so the script can double as a
+   smoke test. Add an `_async.py` twin only when the async variant shows something the sync
+   one cannot.
+4. Add one row to the table above.

autoassembler-0.3.1/examples/adapt.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+#     "autoassembler>=0.3",
+# ]
+# ///
+"""Carry a process plan over to a revised assembly.
+
+    export AA_TOKEN="your-api-key"        # or log in once: uv run login.py
+    uv run adapt.py <reference_assembly_id> <reference_mpp_id> <target_assembly_id> [--name NAME]
+
+Given a plan for one revision of an assembly, builds the plan for the next revision from it
+instead of planning from scratch: stations and steps carry over, adjusted for what changed.
+
+In this example, we:
+  - look the assemblies up with client.assemblies.get(id) and the reference plan with
+    client.planning.get_mpp(assembly, mpp_id);
+  - call client.assemblies.diff(reference, target).result(): what changed between the two
+    revisions, which the adaptation works from;
+  - call client.planning.adapt(reference_plan, target, diff=report).result(): the new
+    ProcessPlan, once saved;
+  - print its stations and mpp.viewer_url, which opens it in the UI.
+
+Both assemblies must be `ready` (see upload.py).
+"""
+
+import argparse
+import os
+import sys
+
+from autoassembler import AutoAssembler, OperationFailed
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("reference_assembly_id")
+    parser.add_argument("reference_mpp_id")
+    parser.add_argument("target_assembly_id")
+    parser.add_argument("--name", default=None, help="name of the adapted process plan")
+    parser.add_argument("--timeout", type=float, default=1800)
+    args = parser.parse_args()
+
+    client = AutoAssembler(
+        base_url=os.environ.get("AA_URL", "https://app.autoassembler.com"),
+    )
+    reference = client.assemblies.get(args.reference_assembly_id)
+    target = client.assemblies.get(args.target_assembly_id)
+    reference_plan = client.planning.get_mpp(reference, args.reference_mpp_id)
+
+    print(f"Comparing {reference.name} → {target.name}...", flush=True)
+    report = client.assemblies.diff(reference, target).result(timeout=args.timeout)
+
+    print(f"Adapting {reference_plan.name!r}...", flush=True)
+    try:
+        mpp = client.planning.adapt(reference_plan, target, diff=report, name=args.name).result(
+            timeout=args.timeout
+        )
+    except OperationFailed as error:
+        print(f"Adaptation failed: {error.message}", file=sys.stderr)
+        return 1
+
+    print(f"Created plan {mpp.id!r} with {len(mpp.stations)} station(s)")
+    for station in mpp.stations:
+        print(f"  {station.name}: {station.status}")
+    print(f"\n{mpp.viewer_url}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())