Client API reference¶

This page is generated from the exported sysml_studio classes and their docstrings. New public methods appear automatically. Defaults and signatures come from Python source, rather than a manually maintained copy.

All requests use the origin and key configured on sysml_studio.Client. Non-2xx HTTP responses raise sysml_studio.APIError; connection and HTTP timeout failures remain httpx exceptions. The client does not retry requests.

Public Dimmara Studio client API.

class sysml_studio.Client(base_url, api_key=None, *, timeout=30, transport=None)[source]¶

Bases: object

Synchronous authenticated client for a Studio application.

Parameters:

base_url (str) – Application origin, such as https://studio.example. Paths, queries and credentials in the URL are rejected. Plain HTTP is allowed only for loopback hosts.
api_key (str | None) – Bearer key; defaults to SYSML_STUDIO_API_KEY.
timeout (float | httpx.Timeout) – Per-request HTTP timeout in seconds. Job polling uses its own deadline; see wait().
transport (httpx.BaseTransport | None) – Optional custom HTTP transport, primarily for tests. Normal network requests verify TLS.

Raises:

ValueError – Invalid application origin or missing/invalid API key.

Use a with Client(...) as studio: block or call close() to release connections. HTTP errors raise APIError; transport failures remain httpx exceptions. Redirects and automatic retries are disabled. The server enforces entitlements, authorization, API-key scopes and quotas.

cancel_job(job_id)[source]¶

Request cancellation of a queued or running job.

Parameters:: job_id (str) – Job UUID.
Returns:: Server cancellation response. Poll get_job() for the terminal status; a running worker may take time to stop.
Return type:: dict

check_access()[source]¶

Check this key’s current server-verified entitlement and limits.

Returns:: Access, plan and quota information supplied by Studio.
Return type:: dict
Raises:: APIError – Key, entitlement or required agreements are not accepted.

close()[source]¶: Close the underlying HTTP connection pool; returns None.

contract()[source]¶

Read the server’s versioned modeling contract and capabilities.

Returns:: API/engine versions, project/job schemas and supported job states.
Return type:: dict

create_space(name, *, description='', visibility='private')[source]¶

Create a project space using the caller’s authorized sharing scope.

Parameters:

name (str) – Space display name.
description (str) – Optional descriptive text.
visibility (str) – private, project or organization; organization visibility requires an active seat.

Returns:

New project-space record, including its UUID.

Return type:

dict

delete_model(model_id)[source]¶

Delete a model the caller is permitted to delete.

Parameters:: model_id (str) – Model UUID.
Returns:: The server accepted the deletion.
Return type:: None
Raises:: APIError – Permission, dependency or other server checks reject it.

dependents(model_id)[source]¶

List visible saved models that depend on this model.

Parameters:: model_id (str) – Referenced model UUID.
Returns:: Server-filtered dependency impact information.
Return type:: list[dict]

download_results(job_id, output_dir)[source]¶

Download every advertised artifact and write a client job manifest.

Parameters:

job_id (str) – Successful job UUID.
output_dir (str | Path) – Destination directory, created if needed. Use a fresh directory for each run or download attempt.

Returns:

Absolute paths to job.json and downloaded artifacts.

Return type:

list[Path]

Raises:

JobFailed – The job has not succeeded.
ValueError – An artifact has an unsafe or duplicated filename.
FileExistsError – Any destination already exists or is a symlink.
APIError – An artifact request is rejected.

Archives are saved without extraction. If a transfer fails, completed files and the manifest remain; only the incomplete file is removed. Network failures propagate as httpx exceptions. Retry into a new directory to avoid overwriting the completed files.

get_component(component_id)[source]¶

Fetch a visible catalog component and its generated model source.

Parameters:: component_id (str) – Catalog component UUID.
Returns:: Definition, source, model_spec and edit permission.
Return type:: dict

get_connected_model(model_id, *, version=None)[source]¶

Resolve a saved revision and its pinned dependencies for local execution.

Requires sysml2py. Typed Python also requires the reference compiler.

Parameters:

model_id (str) – Root model UUID.
version (int | None) – Root revision; None selects the latest.

Returns:

Executable local model whose dependency revisions were authorized and resolved by Studio.

Return type:

sysml2py.modelgraph.ConnectedModel

Raises:

ImportError – The local engine is not installed.
ValueError – Source violates the supported execution profile.
RuntimeError – Required reference compiler resources are unavailable.

get_graph(model_id, *, version=None)[source]¶

Resolve authorized sources into local executable graph data.

Parameters:

model_id (str) – Root model UUID.
version (int | None) – Root revision; None selects the latest.

Returns:

Graph with instances, attributes, connections and behaviors.

Return type:

dict

Uses get_connected_model() and has the same local prerequisites.

get_job(job_id)[source]¶

Fetch the current job status, progress and artifact metadata.

Parameters:: job_id (str) – Job UUID.
Returns:: Fresh snapshot; previously returned snapshots do not update.
Return type:: Job

get_model(model_id)[source]¶

Fetch the latest visible revision of a model.

Parameters:

model_id (str) – Model UUID.

Returns:

Source, revision number, sharing scope and dependency pins.

Return type:

Model

Raises:

APIError – Model is unavailable to this key.
ValueError – Identifier is not a UUID.

instantiate_component(component_id)[source]¶

Create a saved model from a visible component template.

Parameters:: component_id (str) – Catalog component UUID.
Returns:: Newly saved model snapshot.
Return type:: Model

list_components(*, search='', offset=0)[source]¶

Fetch one page of visible catalog components.

Parameters:

search (str) – Server-side text filter.
offset (int) – Zero-based page offset, initially zero.

Returns:

items and next_offset; None means no further page.

Return type:

dict

list_models()[source]¶

List visible model summaries, up to the server’s current limit.

Returns:: Summaries. Use get_model() to retrieve source and a Model snapshot. No pagination is performed by the SDK.
Return type:: list[dict]

list_spaces()[source]¶

List project spaces available to this caller.

Returns:: Owned and shared project spaces, subject to server limits.
Return type:: list[dict]

resolve_model(model_id, *, version=None)[source]¶

Fetch an authorized root revision and its pinned dependencies.

Parameters:

model_id (str) – Root model UUID.
version (int | None) – Root revision; None selects the latest.

Returns:

Resolved bundle with documents in dependency order and the root last, plus provenance. No local engine is required.

Return type:

dict

Raises:

APIError – A revision is missing, inaccessible or cannot be resolved.

results(job_id)[source]¶

Download numerical simulation data as versioned JSON.

Parameters:

job_id (str) – Successful simulation job UUID.

Returns:

sysml2py.results.v1 data with columns, units, rows and metadata. The first column is time.

Return type:

dict

Raises:

ValueError – The result schema is unsupported by this client.
APIError – The result artifact is not available to the caller.

revisions(model_id)[source]¶

List saved revisions without downloading each source.

Parameters:: model_id (str) – Model UUID.
Returns:: Revision number, creation time and language, newest first.
Return type:: list[dict]

save_component(definition, *, component_id=None)[source]¶

Create or update a catalog component using the server’s schema.

Parameters:

definition (dict) – ComponentInput fields. For updates include the existing version to detect conflicting edits.
component_id (str | None) – Existing component UUID, or None to create.

Returns:

Saved component response.

Return type:

dict

Raises:

APIError – Invalid definition, denied access or stale revision (409).

save_model(model, *, source=None, dependencies=None)[source]¶

Create a revision using optimistic concurrency control.

Parameters:

model (Model) – Snapshot whose version is the expected current revision. Its name, language and sharing settings are preserved.
source (str | None) – Replacement source; None keeps the old source.
dependencies (Iterable[dict] | None) – Replacement revision pins; None preserves them, while an empty iterable removes them.

Returns:

New saved snapshot; the input object is unchanged.

Return type:

Model

Raises:

APIError – HTTP 409 if another save made this revision stale.

share(kind, item_id, *, visibility='private', project_space_id=None)[source]¶

Update an item’s server-enforced sharing scope.

Parameters:

kind (str) – projects, jobs or components.
item_id (str) – UUID of the item to update.
visibility (str) – Authorized scope, for example private, organization or project for a project space.
project_space_id (str | None) – Space UUID required by project scope.

Returns:

Updated sharing response.

Return type:

dict

Raises:

ValueError – Unsupported item kind.
APIError – The caller cannot assign the requested scope.

simulate(model_id, *, initial_time=0, end_time=10, step_size=1, inputs=None, initial_values=None, events=None, time_attribute=None, step_attribute=None, version=None, idempotency_key=None, output_dir=None, timeout=300)[source]¶

Run a saved connected model remotely and optionally download artifacts.

Parameters:

model_id (str) – Saved root model UUID.
initial_time (float) – Initial simulation time in seconds.
end_time (float) – Final time in seconds, not before initial_time.
step_size (float) – Positive step duration in seconds.
inputs (dict | None) – Fully qualified undriven input paths mapped to numbers, booleans, {value, unit} quantities, or {samples: [{time, value}], unit} sampled signals.
initial_values (dict | None) – Permitted stored-attribute overrides, as scalars or quantities. Connected/bound targets are rejected.
events (list[dict] | None) – Scheduled events with time in seconds, target state-machine path and event name.
time_attribute (str | None) – Declared duration input populated with the simulation clock, in the model’s unit.
step_attribute (str | None) – Declared duration input populated with the actual step duration, including the final partial step.
version (int | None) – Root revision; None selects the latest saved revision. Dependency revisions remain pinned.
idempotency_key (str | None) – Stable key for retrying the same job.
output_dir (str | Path | None) – Download destination, or None to leave artifacts on the server. Existing files are not replaced.
timeout (float) – Waiting deadline in seconds, passed to wait(). This does not include the optional artifact download time.

Returns:

Successful job with simulation metadata. results() fetches numerical rows; download_results() fetches all files.

Return type:

Job

Raises:

APIError – Submission or downloads are rejected.
JobFailed – The worker fails or the job is cancelled.
TimeoutError – Waiting expires without cancelling the remote job.
FileExistsError – A requested download would overwrite a file.

For long-running work use start_job(), retain its ID, then call wait() separately. No local compiler or engine is required.

space_items(space_id)[source]¶

List the visible models, jobs and components assigned to a space.

Parameters:: space_id (str) – Project-space UUID.
Returns:: Server-grouped items for the requested project space.
Return type:: dict

start_job(model_id, kind, *, idempotency_key=None, **options)[source]¶

Submit work and return immediately with its job ID.

Parameters:

model_id (str) – Saved model UUID.
kind (str) – compile for reference validation, validate for execution-profile validation, translate or simulate.
idempotency_key (str | None) – Stable retry key for the same request.
**options – Job options validated by the server. version pins the root revision. Simulation accepts the inputs and clocks documented by simulate(); translation accepts executable=True for executable Python interchange.

Returns:

Initial snapshot. Retain its ID for polling and cancellation.

Return type:

Job

Raises:

ValueError – Unsupported job kind or invalid model UUID.
APIError – Quota, permissions or job options are rejected.

submit_model(name, source, *, language='sysml', dependencies=(), idempotency_key=None)[source]¶

Save a new model without starting validation or simulation.

Parameters:

name (str) – Model display name.
source (str) – SysML text or supported declarative Python source.
language (str) – "sysml" or "python".
dependencies (Iterable[dict]) – Pins with project_id UUID and integer version for each linked model.
idempotency_key (str | None) – Stable key for retrying the same submission after an ambiguous network failure.

Returns:

Saved initial revision. Saving does not certify validity.

Return type:

Model

Raises:

ValueError – Language is unsupported.
APIError – Submission is rejected by the server.

submit_object(name, model, *, dependencies=(), idempotency_key=None)[source]¶

Serialize a local engine object and save it as SysML.

Parameters:

name (str) – Saved model display name.
model (object) – A sysml2py.Model, SysMLDocument or ConnectedModel. Connected models embed their source bundle.
dependencies (Iterable[dict]) – External revision pins to attach.
idempotency_key (str | None) – Stable key for the same submission.

Returns:

Saved Studio snapshot.

Return type:

Model

Raises:

ImportError – The optional local engine is not installed.
ValueError – Object or arbitrary runtime callbacks cannot be serialized.

validate(model_id, *, version=None, idempotency_key=None, **wait_options)[source]¶

Submit reference-compiler syntax/semantic validation and wait.

Parameters:

model_id (str) – Saved model UUID.
version (int | None) – Root revision; None selects the latest.
idempotency_key (str | None) – Stable key for the validation request.
**wait_options – timeout and poll_interval for wait().

Returns:

Completed compiler job. Check its result report for validity.

Return type:

Job

Raises:

JobFailed – Compiler work failed or was cancelled.
TimeoutError – Waiting expired; the job remains available by ID.

Python is checked as supported interchange, without executing source. Compiler resources live on the worker; no local engine is required. Reference validity and executable-profile support are separate checks.

validate_execution(model_id, *, version=None, idempotency_key=None, **wait_options)[source]¶

Submit execution-profile validation and wait for its report.

Parameters:

model_id (str) – Saved model UUID.
version (int | None) – Root revision; None selects the latest.
idempotency_key (str | None) – Stable key for the validation request.
**wait_options – timeout and poll_interval passed to wait(), in seconds.

Returns:

Completed validation job. Inspect job.result["valid"] and job.result["diagnostics"]; successful processing can report an invalid model. Typed Python additionally requires reference checks.

Return type:

Job

Raises:

JobFailed – The job failed or was cancelled.
TimeoutError – Waiting expired; the remote job continues.

wait(job_id, *, timeout=300, poll_interval=2)[source]¶

Poll until a job succeeds, fails, is cancelled or reaches a deadline.

Parameters:

job_id (str) – Job UUID retained from start_job().
timeout (float) – Positive finite waiting deadline in seconds.
poll_interval (float) – Positive finite delay between polls, in seconds.

Returns:

Snapshot with status == "succeeded".

Return type:

Job

Raises:

JobFailed – The job failed or was cancelled.
TimeoutError – Deadline expired. The remote job remains running; retrieve it later with the same ID or explicitly cancel it.
ValueError – Timing arguments are not finite and positive.

Each poll’s HTTP timeout is bounded by 30 seconds and the remaining deadline. HTTP failures propagate immediately, without automatic retry.

class sysml_studio.Model(id, name, source, language, version, visibility='private', project_space_id=None, dependencies=())[source]¶

Bases: object

An immutable snapshot of a saved Studio model revision.

Variables:

id (str) – Model UUID.
name (str) – Display name.
source (str) – Saved SysML or declarative Python source.
language (str) – "sysml" or "python".
version (int) – Revision used for optimistic saves and pinned jobs.
visibility (str) – Current sharing scope.
project_space_id (str | None) – Owning project space, if assigned.
dependencies (tuple) – Revision pins containing project_id and version. Referenced dictionaries are not deeply immutable.

Parameters:

id (str)
name (str)
source (str)
language (str)
version (int)
visibility (str)
project_space_id (str | None)
dependencies (tuple)

classmethod from_response(data)[source]¶

Construct a snapshot from a Studio response, ignoring extra fields.

Parameters:: data (dict) – Response containing the required model fields.
Returns:: Snapshot with dependency pins stored as a tuple.
Return type:: Model

to_connected_model()[source]¶

Build the current execution profile for a standalone saved model.

Linked sources need Client.get_connected_model(id, version=version), which retrieves their exact authorized dependency revisions.

Returns:

Resolved executable model.

Return type:

sysml2py.modelgraph.ConnectedModel

Raises:

ValueError – The model has external dependencies or invalid source.
ImportError – The optional local engine is not installed.
RuntimeError – Required reference compiler resources are unavailable.

to_document()[source]¶

Convert this source to a local SysML document without executing it.

Returns:

Text interchange document.

Return type:

sysml2py.translation.SysMLDocument

Raises:

ImportError – The optional sysml2py engine is not installed.
ValueError – Python is outside the supported authoring subset or generated SysML fails validation.
RuntimeError – Typed Python needs an unavailable reference compiler.

This method does not fetch dependencies. Use Client.get_connected_model() for a linked source bundle.

to_model()[source]¶

Convert to the legacy numeric assignment model.

Returns:: Legacy model supporting the older assignment subset.
Return type:: sysml2py.Model

Use to_connected_model() for current actions, calculations, units, state machines and requirements. Requires the optional local engine; unsupported constructs raise ValueError.

class sysml_studio.Job(id, status, result=None, error=None, artifacts=(), progress=0, cancel_requested=False, provenance=())[source]¶

Bases: object

An immutable snapshot of a remote job, refreshed with Client.get_job.

Variables:

id (str) – Job UUID.
status (str) – queued, running, succeeded, failed or cancelled.
result (dict | None) – Job-kind-specific report or simulation metadata. Fetch numerical rows using Client.results().
error (str | None) – Worker failure detail when available.
artifacts (tuple) – Advertised artifact metadata, including each name.
progress (int) – Reported completion percentage.
cancel_requested (bool) – Whether cancellation has been requested.
provenance (tuple) – Root and dependency revisions used by the job.

Parameters:

id (str)
status (str)
result (dict | None)
error (str | None)
artifacts (tuple)
progress (int)
cancel_requested (bool)
provenance (tuple)

classmethod from_response(data)[source]¶

Construct a job snapshot from a Studio response.

Parameters:: data (dict) – Response containing at least id and status.
Returns:: Snapshot with defaults for fields not yet supplied by a worker.
Return type:: Job

exception sysml_studio.APIError(status_code, detail, retry_after=None, request_id=None)[source]¶

Bases: RuntimeError

An HTTP response outside the 2xx range, including redirects.

Parameters:

status_code (int) – HTTP status returned by Studio.
detail (object) – Server error detail, or "Request rejected".
retry_after (str | None) – Raw Retry-After header, when supplied.
request_id (str | None) – Server request identifier for troubleshooting.

Variables:

status_code (int) – HTTP status, for example 409 for a stale revision.
detail (object) – Error detail returned by the server.
retry_after (str | None) – Retry hint; the client does not retry itself.
request_id (str | None) – Correlation identifier, when available.

Connection failures and HTTP timeouts remain httpx exceptions.

exception sysml_studio.JobFailed[source]¶

Bases: RuntimeError

A waited job failed or was cancelled, or results are not yet available.

The message contains the worker’s error when available. Retain the job ID from Client.start_job() to inspect or resume a detached workflow.