client¶

The client of the service: snapshots working trees, then calls the API.

A snapshot is written into the store when it is mounted here (SIMRUN_STORE), else uploaded: the client asks the service which contents the store lacks and sends a tar of only those files.

The CLI (simrun.cli) and the MCP server (simrun.mcp) both go through Client.

ClientError ¶

ClientError(status, detail)

Bases: Exception

The service refused a request.

Attributes:

Name	Type	Description
`status`		The HTTP status.
`detail`		The message of the service.

Create the error.

Client ¶

Client(url, token, store, sources='store', transport=None)

A client of the service of one user or agent.

Parameters:

Name	Type	Description	Default
`url`	`str`	Base URL of the service.	required
`token`	`str`	Bearer token.	required
`store`	`Path \| None`	The run store as mounted locally, where snapshots are written; None for a client which sends no snapshots.	required
`sources`	`Literal['store', 'upload', 'provenance']`	How a source is sent: `store` copies a snapshot into `store`, `upload` sends the files the store of the service lacks, which writes the snapshot, `provenance` sends its provenance only (the local service runs the tasks with the environment of the command).	`'store'`
`transport`	`BaseTransport \| None`	An HTTP transport, e.g. for tests.	`None`

Create the client.

from_env `classmethod` ¶

from_env()

The client of SIMRUN_URL, SIMRUN_TOKEN and SIMRUN_STORE.

With SIMRUN_STORE, the store as mounted here, snapshots are written into it; without it they are uploaded to the service.

Raises:

Type	Description
`RuntimeError`	When `SIMRUN_URL` or `SIMRUN_TOKEN` is not set.

local `classmethod` ¶

local(root, snapshot=False, warn=None)

The client of the local service of a project directory.

The service is started in the background when none runs.

Parameters:

Name	Type	Description	Default
`root`	`Path`	The project directory, where `.simrun/` is.	required
`snapshot`	`bool`	Copy the sources into the local store and install them as on the cluster; else only their provenance is recorded.	`False`
`warn`	`Callable[[str], None] \| None`	Called with a warning for the user, e.g. a service which runs with another environment; by default logged.	`None`

Raises:

Type	Description
`RuntimeError`	The service did not start.

source ¶

source(repo, name)

The provenance of a source, its snapshot written to the store first.

Raises:

Type	Description
`RuntimeError`	When the client has `store` sources without a store, or git fails.
`ClientError`	When the service refuses an upload.

close ¶

close()

Close the connections.

submit ¶

submit(
    workflow,
    sources,
    group=None,
    split=None,
    reserve=None,
    local_commands=None,
)

Plan the tasks, snapshot the sources and submit a workflow.

The settings of a task whose type is installed locally and has a plan are replaced by the planned ones, see plan_tasks.

Parameters:

Name	Type	Description	Default
`workflow`	`Path \| Workflow`	The workflow or its YAML file.	required
`sources`	`dict[str, Path]`	Working trees by source name, the model first.	required
`group`	`str \| None`	Group of the run.	`None`
`split`	`SplitMode \| None`	Split mode of every task.	`None`
`reserve`	`str \| None`	A node to reserve.	`None`
`local_commands`	`str \| None`	With the local service, `docker` runs a `command` task in its image, `direct` (the default) as a process.	`None`

Returns:

Type	Description
`RunSummary`	The summary of the run, `submitting` while the service resolves its
`RunSummary`	environment, builds its image and submits its workflow.

Raises:

Type	Description
`ClientError`	When the service refuses the submission.

estimate ¶

estimate(
    workflow, sources, group=None, split=None, reserve=None
)

The resources, plans and durations of the tasks of a submission.

validate ¶

validate(workflow)

Validate a workflow with its tasks planned, as submit submits it.

Raises:

Type	Description
`ValueError`	The settings of a task are invalid for its local type.

open_edit ¶

open_edit(body)

Open an edit session for the workflow file of this machine.

edit_state ¶

edit_state(session_id, state)

Send what was read from disk to an edit session.

edit_requests ¶

edit_requests(session_id, timeout)

Long poll the open requests of the browser, for up to timeout s.

edit_result ¶

edit_result(session_id, request_id, result)

Answer a request of the browser.

close_edit ¶

close_edit(session_id, timeout=REQUEST_TIMEOUT_S)

Close an edit session, the command stopped, waiting up to timeout s.

wait ¶

wait(run_id, timeout_s=None)

Wait for a run to end, or for timeout_s seconds (None: forever).

A dropped connection or a restarting service is retried with a backoff of 1 s doubling to 10 s, until the timeout.

Returns:

Type	Description
`RunSummary`	The summary of the run, not terminal when the timeout passed; when the
`RunSummary`	timeout passes during an outage, the last summary obtained.

Raises:

Type	Description
`ClientError`	For an unknown run or another refusal.
`TransportError`	When the service was never reached before the timeout.

wait_live ¶

wait_live(run_id, on_update, timeout_s=None)

Follow a run through its event stream until it is final.

The stream ends when the run is final and also every events_max_s of the service; it is opened again then. A dropped connection or a restarting service is retried with a backoff of 1 s doubling to 10 s.

Parameters:

Name	Type	Description	Default
`run_id`	`str`	The run.	required
`on_update`	`Callable[[dict[str, Any]], None]`	Called with the latest `{"run": RunRecord, "progress": dict[str, TaskProgress]}` whenever one of them changed.	required
`timeout_s`	`float \| None`	Seconds to follow (None: until the run is final).	`None`

Returns:

Type	Description
`dict[str, Any]`	The last update; its run is not terminal when the timeout passed.

Raises:

Type	Description
`ClientError`	For an unknown run or another refusal.
`TransportError`	When the service was never reached before the timeout.

status ¶

status(run_id)

The record of a run.

progress ¶

progress(run_id)

The progress of the tasks of a run.

list_runs ¶

list_runs(group=None, agent=None, state=None, owner=None)

The runs, filtered by group, agent, state and owner.

compare ¶

compare(run_ids)

Provenance and summaries of runs side by side.

cancel ¶

cancel(run_id)

Cancel a run.

logs ¶

logs(run_id, task_id, tail_lines=DEFAULT_TAIL_LINES)

The logs of the pods of a task, the last tail_lines of each (0: all).

outputs ¶

outputs(run_id, task_id)

The output files of a task, paths relative to the store.

output_file ¶

output_file(run_id, task_id, path)

The bytes of a file of the output of a task, path relative to it.

output_archive ¶

output_archive(run_id, task_id, to)

Extract the output of a task into the directory to.

Returns:

Type	Description
`list[Path]`	The extracted files, sorted.

delete ¶

delete(run_id)

Delete an ended run.

cleanup ¶

cleanup(
    older_than_days,
    group=None,
    failed_only=False,
    dry_run=False,
)

Remove ended runs and the snapshots nothing refers to any more.

usage ¶

usage()

Bytes of the store per run and group.

plan_tasks ¶

plan_tasks(workflow, types, root=None)

The workflow with the settings of its tasks planned by their types.

A task whose type is in types and has a plan gets the settings the plan returns for its validated settings, the fields which were given or which the plan set, dumped as JSON: the defaults stay with the plugin of the snapshot, which validates the settings in the pods. Every other task is kept as written, e.g. a task of a type which is not installed locally.

Parameters:

Name	Type	Description	Default
`workflow`	`Workflow`	The workflow, which is not changed.	required
`types`	`dict[str, TaskType]`	The task types installed locally, by name.	required
`root`	`Path \| None`	The working tree of the model, first on the path of the imports while planning, as a task imports from it (`podspec.import_root`).	`None`

Returns:

Type	Description
`Workflow`	A copy of the workflow with the planned settings.

Raises:

Type	Description
`ValueError`	The settings of a task are invalid for its type.

client¶

ClientError ¶

Client ¶

from_env classmethod ¶

local classmethod ¶

source ¶

close ¶

submit ¶

estimate ¶

validate ¶

open_edit ¶

edit_state ¶

edit_requests ¶

edit_result ¶

close_edit ¶

wait ¶

wait_live ¶

status ¶

progress ¶

list_runs ¶

compare ¶

cancel ¶

logs ¶

outputs ¶

output_file ¶

output_archive ¶

delete ¶

cleanup ¶

usage ¶

plan_tasks ¶

from_env `classmethod` ¶

local `classmethod` ¶