feat: Python runtime interface by johnchildren · Pull Request #651 · Quantinuum/tierkreis

johnchildren · 2026-09-15T10:33:41Z

Adds a pythonic interface to the runtime that can be used when a user wants to use the runtime in their python interpreter. The API should be flexible enough to be usable with runtime daemons running on the users system or remotely in future.

johnchildren · 2026-09-15T12:43:03Z

Things to include:

Type stubs for the new interface
A test for running multiple workflows on the same runtime simultaneously
Default file location creation (maybe another issue)

johnchildren · 2026-09-15T13:20:11Z

+    with runtime:
+        workflow_id = await runtime.save_workflow("will_fail", graph)
+        run_id = await runtime.start_new_run(workflow_id, {})
+        with pytest.raises(ValueError) as raises:


I guess it's probably worth adding a custom exception here?

I think the point here was that will_fail just raises a ValueError there is no specific I chose this

makes sense, I'm experimenting with trying to make some richer exceptions which the locations that failed so it might make sense for them to be a custom type.

johnchildren · 2026-09-16T10:12:36Z

    if "defaults" in name:
        pytest.skip("default arguments not supported")

-    run_outputs = run_workflow(name, g, inputs)


possibly we can just remove this function now? Or move the implementation into python

I orginally wrote it to have a more user friendly way (hiding the storage/executor) I think with the new interface this can now be deprecated

philipp-seitz · 2026-09-16T18:27:57Z

+    ///
+    /// # Errors
+    ///
+    /// Will


philipp-seitz · 2026-09-16T19:00:26Z

+        }
+
+        #[pyo3(signature = (run_id, attempt=0, /, timeout=604_800))]
+        async fn wait_for(&self, run_id: Uuid, attempt: u32, timeout: u64) -> PyResult<()> {


we return UUID from start_new_run but expect UUID,attempt with wait_for is this intended?

Sort of, I figured as starting a new run always gives attempt 0 it wasn't necessary to return it from start_new_run (though this is a difference to the rust interface). Notice that the pyo3 signature defines a default value for attempt

Co-authored-by: Philipp Seitz <philipp.seitz@quantinuum.com>

johnchildren · 2026-09-17T08:54:55Z

+    }
+
+    // TODO: I'm not sure how debuggable this is
+    #[pyclass(name = "RuntimeConfig")]


It's not really possible to create one of these objects directly right now as they only exist as arguments to new_from_config. Possibly we could start returning them from the runtime though if users want to debug it?

>>> runtime = await new_from_config({}) Traceback (most recent call last): File "/nix/store/d20zkzz2dwl57ncmpi89rmfbvb2cs5c9-python3-3.13.15-env/lib/python3.13/concurrent/futures/_base.py", line 460, in result return self.__get_result() ~~~~~~~~~~~~~~~~~^^ File "/nix/store/d20zkzz2dwl57ncmpi89rmfbvb2cs5c9-python3-3.13.15-env/lib/python3.13/concurrent/futures/_base.py", line 402, in __get_result raise self._exception File "<python-input-2>", line 1, in <module> runtime = await new_from_config({}) ^^^^^^^^^^^^^^^^^^^^^^^^^ Exception: missing field `asset_storage` while processing 'config'

example error

johnchildren · 2026-09-17T08:57:43Z

+        }
+    }
+
+    // TODO: I'm not sure how debuggable this is


>>> with runtime: ... id = await runtime.save_workflow(None, {}) ... Traceback (most recent call last): File "/nix/store/d20zkzz2dwl57ncmpi89rmfbvb2cs5c9-python3-3.13.15-env/lib/python3.13/concurrent/futures/_base.py", line 460, in result return self.__get_result() ~~~~~~~~~~~~~~~~~^^ File "/nix/store/d20zkzz2dwl57ncmpi89rmfbvb2cs5c9-python3-3.13.15-env/lib/python3.13/concurrent/futures/_base.py", line 402, in __get_result raise self._exception File "<python-input-7>", line 2, in <module> id = await runtime.save_workflow(None, {}) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ValueError: AttributeError: 'dict' object has no attribute 'model_dump_json' while processing 'workflow'

johnchildren · 2026-09-17T09:02:15Z

+            }
+        }
+
+        fn __enter__(&mut self) {


This isn't working quite as intended:

with runtime: ... with runtime: ...

Doesn't work as we consume the event listener. Possibly a fixable bug but a kind of annoying design flaw otherwise.

johnchildren · 2026-09-17T09:04:12Z

+        }
+    }

+    // TODO: I'm not sure how debuggable this is


>>> with runtime: ... wf_id = await runtime.save_workflow(None, compile_simulate()) ... run_id = await runtime.start_new_run(wf_id, {"a": max}) ... Traceback (most recent call last): File "/nix/store/d20zkzz2dwl57ncmpi89rmfbvb2cs5c9-python3-3.13.15-env/lib/python3.13/concurrent/futures/_base.py", line 460, in result return self.__get_result() ~~~~~~~~~~~~~~~~~^^ File "/nix/store/d20zkzz2dwl57ncmpi89rmfbvb2cs5c9-python3-3.13.15-env/lib/python3.13/concurrent/futures/_base.py", line 402, in __get_result raise self._exception File "<python-input-14>", line 3, in <module> run_id = await runtime.start_new_run(wf_id, {"a": max}) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ TypeError: failed to extract enum ValueOrMappingOrBytes ('dict[str, bytes] | ValueOrBytes') - variant BytesMapping (dict[str, bytes]): TypeError: failed to extract field ValueOrMappingOrBytes::BytesMapping.0, caused by TypeError: 'builtin_function_or_method' object is not an instance of 'bytes' - variant ValueOrBytes (ValueOrBytes): TypeError: failed to extract field ValueOrMappingOrBytes::ValueOrBytes.0, caused by TypeError: failed to extract enum ValueOrMapping ('Mapping | Value') - variant Mapping (Mapping): TypeError: failed to extract field ValueOrMapping::Mapping.0, caused by TypeError: failed to extract enum Value ('bool | int | float | str | complex | Sequence | Mapping') - variant Bool (bool): TypeError: failed to extract field Value::Bool.0, caused by TypeError: 'builtin_function_or_method' object is not an instance of 'bool' - variant Int (int): TypeError: failed to extract field Value::Int.0, caused by TypeError: 'builtin_function_or_method' object cannot be interpreted as an integer - variant Float (float): TypeError: failed to extract field Value::Float.0, caused by TypeError: must be real number, not builtin_function_or_method - variant String (str): TypeError: failed to extract field Value::String.0, caused by TypeError: 'builtin_function_or_method' object is not an instance of 'str' - variant Complex (complex): TypeError: failed to extract field Value::Complex.0, caused by TypeError: must be real number, not builtin_function_or_method - variant List (Sequence): TypeError: failed to extract field Value::List.0, caused by TypeError: 'builtin_function_or_method' object is not an instance of 'Sequence' - variant Dict (Mapping): TypeError: failed to extract field Value::Dict.0, caused by TypeError: 'builtin_function_or_method' object is not an instance of 'dict' - variant Value (Value): TypeError: failed to extract field ValueOrMapping::Value.0, caused by TypeError: failed to extract enum Value ('bool | int | float | str | complex | Sequence | Mapping') - variant Bool (bool): TypeError: failed to extract field Value::Bool.0, caused by TypeError: 'dict' object is not an instance of 'bool' - variant Int (int): TypeError: failed to extract field Value::Int.0, caused by TypeError: 'dict' object cannot be interpreted as an integer - variant Float (float): TypeError: failed to extract field Value::Float.0, caused by TypeError: must be real number, not dict - variant String (str): TypeError: failed to extract field Value::String.0, caused by TypeError: 'dict' object is not an instance of 'str' - variant Complex (complex): TypeError: failed to extract field Value::Complex.0, caused by TypeError: must be real number, not dict - variant List (Sequence): TypeError: failed to extract field Value::List.0, caused by TypeError: 'dict' object is not an instance of 'Sequence' - variant Dict (Mapping): TypeError: failed to extract field Value::Dict.0, caused by TypeError: failed to extract enum Value ('bool | int | float | str | complex | Sequence | Mapping') - variant Bool (bool): TypeError: failed to extract field Value::Bool.0, caused by TypeError: 'builtin_function_or_method' object is not an instance of 'bool' - variant Int (int): TypeError: failed to extract field Value::Int.0, caused by TypeError: 'builtin_function_or_method' object cannot be interpreted as an integer - variant Float (float): TypeError: failed to extract field Value::Float.0, caused by TypeError: must be real number, not builtin_function_or_method - variant String (str): TypeError: failed to extract field Value::String.0, caused by TypeError: 'builtin_function_or_method' object is not an instance of 'str' - variant Complex (complex): TypeError: failed to extract field Value::Complex.0, caused by TypeError: must be real number, not builtin_function_or_method - variant List (Sequence): TypeError: failed to extract field Value::List.0, caused by TypeError: 'builtin_function_or_method' object is not an instance of 'Sequence' - variant Dict (Mapping): TypeError: failed to extract field Value::Dict.0, caused by TypeError: 'builtin_function_or_method' object is not an instance of 'dict' while processing 'inputs'

johnchildren commented Sep 15, 2026

View reviewed changes

johnchildren force-pushed the python-runtime-interface branch 5 times, most recently from 4f0f854 to 639d646 Compare September 15, 2026 15:35

johnchildren marked this pull request as draft September 15, 2026 16:02

johnchildren commented Sep 15, 2026

View reviewed changes

Comment thread tierkreis/tests/controller/test_resume.py Outdated

johnchildren added 2 commits September 16, 2026 10:33

feat: Expand new python interface

06ee670

chore: Add timeouts and optional attempt numbers

469821d

johnchildren force-pushed the python-runtime-interface branch from 639d646 to 469821d Compare September 16, 2026 10:10

johnchildren commented Sep 16, 2026

View reviewed changes

johnchildren added 3 commits September 16, 2026 12:04

chore: Further API improvements and bugfixes

de728f1

chore: linting and cancellation improvements

240e55b

chore: fix more lint errors

3bfb981

johnchildren marked this pull request as ready for review September 16, 2026 12:17

johnchildren requested a review from philipp-seitz September 16, 2026 12:17

philipp-seitz reviewed Sep 16, 2026

View reviewed changes

Comment thread tierkreis/src/runtime.rs

///

/// # Errors

///

/// Will

philipp-seitz Sep 16, 2026

Copy link
Copy Markdown

Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗡

philipp-seitz reviewed Sep 16, 2026

View reviewed changes

Comment thread tierkreis/src/lib.rs Outdated

philipp-seitz reviewed Sep 16, 2026

View reviewed changes

philipp-seitz requested changes Sep 16, 2026

View reviewed changes

fix: Correct classname

d4d3299

Co-authored-by: Philipp Seitz <philipp.seitz@quantinuum.com>

johnchildren commented Sep 17, 2026

View reviewed changes

Uh oh!

Conversation

johnchildren commented Sep 15, 2026

Uh oh!

johnchildren commented Sep 15, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

johnchildren Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

johnchildren Sep 17, 2026 •

edited

Loading