Skip to main content

rekuest

codecov PyPI version PyPI pyversions

The distributed runtime for Arkitekt apps.

An Arkitekt app is a declaration: the actions, states and hooks it offers. The declaration itself is arkitekt-spec's, and executing it locally is arkitekt-runtime's. rekuest adds what running it distributed takes:

  • an agent that registers the declaration with a rekuest server over a websocket, is assigned tasks, and reports their progress, logs and results back;
  • the caller through which one app's actions call other apps' actions via the server;
  • Rekuest, the GraphQL client for the server: find actions and implementations, call them, and watch their tasks.

You rarely import rekuest yourself. run(app) in arkitekt uses it, and the names an app is written with (App, Task, the Annotated markers, the policies) come from arkitekt.

Install

pip install "arkitekt[rekuest]"   # what an app needs to run(app)
pip install rekuest               # just the runtime and client

The optional extras are units (physical-quantity ports, via kanne) and types (annotated-types constraints). rekuest requires Python 3.11+.

Offering actions

Declare the app with arkitekt and run it. run connects it through rekuest's provider, which builds the agent and keeps it offering the app's actions until you stop it:

from arkitekt import App, Task, run

app = App("measure", "0.1.0")


@app.action
def double(x: int, task: Task) -> int:
    """Double

    Doubles a number.
    """
    task.log(f"doubling {x}")
    return x * 2


if __name__ == "__main__":
    run(app)

An app can also name the provider explicitly: App(..., providers=[rekuest_provider]) with from rekuest.arkitekt import rekuest_provider.

Calling actions

From a script, name the rekuest service and call an action by its id (or pass an Action/Implementation you looked up). The call is a root task:

from arkitekt import easy
from rekuest.arkitekt import rekuest_service

with easy("my-script", rekuest_service) as rekuest:
    result = rekuest.call("<action-id>", x=21)

Only a workflow may call other actions. A call made inside one is a child of the task it runs in, so it goes through the task: resolve the target with the client, then call it on the task. A plain @app.action that calls raises NotAWorkflowError, and rekuest.acall inside a task raises RootOnlyCallError:

from arkitekt import App, Task
from rekuest.arkitekt import rekuest_service
from rekuest.client.client import Rekuest

app = App("orchestrate", "0.1.0", services=[rekuest_service])


@app.workflow
async def double_twice(x: int, action_id: str, task: Task, rekuest: Rekuest) -> int:
    """Double Twice"""
    action = await rekuest.aresolve(action_id)
    once = await task.acall(action, x=x)
    return await task.acall(action, x=once)

Usually a workflow names what it needs of another app as a protocol instead (@app.declare, see Agent dependencies) and calls its methods; a method annotated as a generator streams the other action's yields.

Actions, implementations, shortcuts, test cases, test results and task events travel between actions by id (@rekuest/action, @rekuest/implementation, …), so an action can take and return them directly.

When an agent dies

Nothing is re-run behind your back.

  • A plain task whose agent dies mid-run ends LOST: not failed, its fate unknown. rekuest.call raises AgentLost with what is known (started, last_progress, and the action's effects), and whoever called decides. Work that was never picked up is simply delivered again.
  • A workflow is resumed: it runs again from the top, but the calls it already made return their recorded results, and task.now(), task.random(), task.sleep() and task.record(fn) return their recorded values. Inside it, a lost step raises AgentLost, and task.retry, task.hold and task.guard cover the usual answers.

effects= on an action (NONE, REPEATABLE, UNKNOWN, IRREVERSIBLE) says what running it again would do. It is information for whoever decides, never a rule the server acts on. See Workflows.

Package layout

Module What it is
rekuest.arkitekt The service (rekuest_service), the agent provider (rekuest_provider) and the @rekuest/* structures
rekuest.agents The agent, its websocket transport, control channel and caller
rekuest.client Rekuest, the GraphQL client, and its postman
rekuest.api.schema The generated GraphQL operations and types
rekuest.protocol The wire protocol the agent speaks with the server

Guides

  • Workflows — calling other actions, and what happens when an agent dies
  • Agent dependencies — declare the actions and states an app depends on
  • Disconnect policy — what happens to in-flight work when the agent loses its connection
  • The agent journal — the ordered, persisted record of everything an agent reports

Development

uv sync                       # install dependencies
pytest -m "not integration"   # fast unit tests
pytest -m integration         # full integration tests (require Docker)

Integration tests spin up the rekuest stack with Docker Compose and exercise real calls against it; see tests/conftest.py.

Learn more

License

GPL-3.0-or-later

Metadata

Release files for rekuest 12.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rekuest 12.1.0
File Size Uploaded Provenance Actions
rekuest-12.1.0.tar.gz 193.1 kB Without provenance Details for rekuest-12.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rekuest 12.1.0
File Interpreter ABI Platform Actions
rekuest-12.1.0-py3-none-any.whl Python 3 none any Details for rekuest-12.1.0-py3-none-any.whl

Total release size: 397.7 kB

Release files / rekuest-12.1.0.tar.gz

Download URL rekuest-12.1.0.tar.gz
Size 193.1 kB
Tags Source
SHA-256 checksum
How to use checksums
13f7688f73d833fb543210ea897af93f53bb974806de3d5852002a6d9e7e309a
BLAKE2b-256 checksum
How to use checksums
75c04c722cb0a0092a1aa842df1098b6443210dd01b5ab8438104c766ff7cf1c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / rekuest-12.1.0-py3-none-any.whl

Download URL rekuest-12.1.0-py3-none-any.whl
Size 204.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9e96c56278a2c257a434c8a83c759ec55cf4c3a9e21a8fd6f74dbde899499970
BLAKE2b-256 checksum
How to use checksums
48086f0c23bfaa6516c6d19f6d52db7b4bc871e221e7c9b958820284568fb3b6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for rekuest 12.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

12.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page