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.
