Working with agents · for developers

What the recipes actually do

The short version for people who would rather read the commands than be walked through them. What the scaffolder writes, how authentication resolves, what the agent context files contain, and where to hook your own code in.

Nothing here is hidden from the other track · it is the same recipes. This page just skips the explanation of what an agent is.

Nought to a result

$ python3 -m venv .venv && source .venv/bin/activate$ pip install --upgrade pip cadmould-sdk-auth$ cadmould-sdk-auth$ pip install ".[result-viewer]"$ python examples/result-viewer/scripts/08_result_viewer.py

The index token is short-lived. If a later install fails with an auth error, run cadmould-sdk-auth again and retry.

The last step runs offline against the bundled reference result and its geometry. No cloud call, and nothing to authorise beyond the index login.

What the starter kit contains

One plain repository · the concept docs, three standalone examples of increasing depth, and a pytest suite. There is no scaffolder and no hidden state: you work in the checkout, and the examples are scripts rather than a library to import.

What is in the checkout

cadmould-api-toolkit-starter-kit/  docs/    PLATFORM.md    SOLVERS.md    SETUP.md    RESULTS_AND_IO.md    api/README.md  examples/    result-viewer/    cloud-quickstart/    gate-study/  tests/  .claude/skills/cadmould-cloud/  CLAUDE.md  AGENTS.md  pyproject.toml

Standalone scripts, not a library

The three examples are ordered by depth · result-viewer offline, then cloud-quickstart for one run, then gate-study for a full decision. Nothing imports across them, so you can copy one out and delete the rest.

Two context files and a skill

CLAUDE.md carries the project and dev workflow. AGENTS.md carries the cloud-domain guidance · how to organise a study, which client to pick, how to spend compute. The cadmould-cloud skill under .claude/skills/ stays out of context until the agent needs the API surface.

Tests that skip rather than fail

pytest runs the offline suite on numpy and h5py alone. The licence and cloud suites are opt-in behind CADMOULD_RUN_LICENCE_TESTS and CADMOULD_RUN_CLOUD_TESTS, so a missing dependency skips instead of failing.

Installing into your own project

If you are dropping the SDK into an existing project rather than working in the starter kit. Two things are authorised separately today: resolving the licensed wheel from our index, and running simulations.

pip

$ pip install --upgrade pip cadmould-sdk-auth$ cadmould-sdk-auth$ pip install cadmould

$ uv venv && source .venv/bin/activate$ uv pip install cadmould-sdk-auth$ uv pip install cadmould --index "$(cadmould-sdk-auth --print-index-url)"

uv works too, with one wrinkle · cadmould-sdk-auth writes the index URL into pip’s config, which uv ignores. Pass it across explicitly with cadmould-sdk-auth --print-index-url.

Failure modes, and which system they point at

No matching distribution foundThe index token expired, or you are on an unsupported Python. Run cadmould-sdk-auth again and check you are on 3.9 to 3.14. Nothing to do with your cloud access.

AttributeError on cadmould.cloudThe import failed because the SDK is not in the active interpreter. Re-run the verify check, and make sure you are running the venv’s Python rather than the system one.

LICENCE_API required, enter a Session firstCloud calls are outside an active session. Wrap set_base_url and every cloud call in one Session.user_based(). If it persists inside a session, the licence lacks the entitlement.

Licence released mid-scriptNested sessions. One Session.user_based() around the whole run · an inner session releases the licence when its with block exits, leaving later calls unlicensed.

401 on every cloud callA custom REST client with a missing or expired CLOUD_SOLVER_TOKEN. The cadmould.cloud SDK opens the browser flow itself on first use.

SDK or your own client

The platform is a plain REST service · the SDK is a convenience over it, not a gate in front of it.

Stay on cadmould.cloud

Wraps geometry upload, materials and running simulations, and owns the cloud login. Local meshing lives here too, which a REST client cannot do. Right answer for single runs and most automation.

Bring your own client

Needed for the management surface · projects, groups and the decision log are REST-only and not wrapped by the SDK. Any language, bearer token, base URL api.simcon.ai/api/v1. The gate study takes this path and ships the client.

Interactive API reference · api.simcon.ai/scalar

Conventions worth adopting

These are the parts of the recipes we would copy into any pipeline of our own. Each one exists because getting it wrong cost us a re-run.

01One licence session around the whole run. Open Session.user_based() once, put meshing and every cloud call inside it, and never nest. A helper that opens its own session must skip that when the caller already holds one.

02Organise as project, then groups, then a decision log. One project per mould that will be built, groups as logical increments, and the reason behind each choice posted to the project’s notes as it is made.

03Simulations are deterministic, so never re-run the same configuration. Spend compute freely on configurations you have not tried, and treat a repeat of an identical config as a bug rather than a safety net.

04Keep concurrency low, around two, with retry and backoff. The endpoint sheds load under concurrency · a wall of 504s usually means the model went cold, so wait and let one request warm it.

05Hold the units contract at every boundary. Temperatures K, pressure Pa, spatial mm, flow cm³/s. Most wrong answers that survive review are a unit, not a method.

Next: take a recipe apart

The DOE campaign is the one worth reading if you are building something similar · seven resumable stages, a guardrail lint, and the checks that make its output defensible.

Frontloaded DOE All recipes