matrx-runtime

The durable-execution substrate for the Matrx platform.

Every unit of work — a utility call, a workflow run, an agent session — is one row on a single global_execution spine that can nest inside any other. The substrate owns the concerns all three flavors share, so they compose freely and share one lifecycle, one nesting tree, one cost ledger, and one enforced state machine:

  • run identity + lineage (parent_execution_id, denormalized root_execution_id)
  • the lifecycle state machine (transition() — the only legal way to change status)
  • the cost ledger + tree-wide budget and quantity limits
  • cancellation, deadlines, and down-tree propagation
  • generalized checkpoints, leases, recovery, and lifecycle events
  • pluggable durable stores (InMemoryExecutionStore and OrmExecutionStore)
  • immutable per-execution context snapshots with explicit inheritance modes

ContextMode.INHERIT deep-copies the parent's snapshot, SCOPE overlays explicit narrower values, and destructive REPLACE requires a complete replacement context. Omitting that replacement raises MissingReplacementContext both at the engine spawn boundary and in ExecutionContext.derive; silent context erasure is not a valid operation.

Executors plug in as strategies and are NOT owned here: the agent loop (matrx-ai), the superstep DAG (matrx-graph), utility implementations (matrx-scraper).

Status: active. The decision core, durable ORM store, context propagation, metering, budget/cancel/deadline gates, leases, recovery, checkpoints, and request/execution lifecycle are implemented. aidream adopts them through its host integration; domain payloads and entity lookup remain host-owned so this package stays independent and payload-blind.

Durable frontier consumers use runtime.work_item. A provider poll that is still in progress calls defer_work_item(...): it returns the claim to pending, schedules not_before, and does not consume the retry budget. Actual call failures continue through fail_work_item(...) and its bounded retry/dead-letter policy. pending_work_execution_ids(type, limit) is the payload-blind discovery seam for host drainers; providers and domain payloads remain outside this package.

Expired leases obey the same attempt budget: a final expired attempt becomes dead_letter with a typed error instead of returning to pending. Consumers that intentionally encode a resumable terminal wait can use the CAS-fenced resume_failed_work_item(...); it matches the full expected error and restores the claim attempt consumed while discovering that wait.

Large mixed backlogs use generic priority (lower claims first, seq breaks ties). Long workers call renew_work_item_lease(...); coordinators use the bounded list_work_items(...), exact get_work_item(...), and dependency-state lookup without importing ORM rows.

Design + phased plan: docs/runtime/EXECUTION_SPINE.md.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.0.100)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for armanisadeghi from gravatar.com armanisadeghi

Credits

Author: Matrx

License

MIT License (MIT)

Requires

Python >=3.13

Provides Extra

dev

Tags

durable execution matrx orchestration runtime

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

matrx_runtime-0.0.79.tar.gz (89.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

matrx_runtime-0.0.79-py3-none-any.whl (61.8 kB view details)

Uploaded Python 3

File details

Details for the file matrx_runtime-0.0.79.tar.gz.

File metadata

  • Download URL: matrx_runtime-0.0.79.tar.gz
  • Upload date:
  • Size: 89.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for matrx_runtime-0.0.79.tar.gz
Algorithm Hash digest
SHA256 8a251c86ca41d83d26b5e4f87a833b74c0e9d6ee16b8a76eda18ccf238c75cc1
MD5 65afa20434ae542bf0a60108ad1dc85c
BLAKE2b-256 1dac3a238adc93076ebce085530ead742e61e53b73408c4a48a54b873e024305

See more details on using hashes here.

Provenance

The following attestation bundles were made for matrx_runtime-0.0.79.tar.gz:

Publisher: publish-package.yml on AI-Matrix-Engine/aidream

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file matrx_runtime-0.0.79-py3-none-any.whl.

File metadata

  • Download URL: matrx_runtime-0.0.79-py3-none-any.whl
  • Upload date:
  • Size: 61.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for matrx_runtime-0.0.79-py3-none-any.whl
Algorithm Hash digest
SHA256 3b6351a07808ad71b0da2996907ebe26081e782f196708340dfd07072c37e359
MD5 2821d4ac42e237193954ba08e008ebd8
BLAKE2b-256 904f0ae34b304c3c635c5b6da717efca527843f4fb18a209c366ee270bd7e012

See more details on using hashes here.

Provenance

The following attestation bundles were made for matrx_runtime-0.0.79-py3-none-any.whl:

Publisher: publish-package.yml on AI-Matrix-Engine/aidream

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.0.100

2 files

0.0.99

2 files

0.0.98

2 files

0.0.97

2 files

0.0.96

2 files

0.0.95

2 files

0.0.94

2 files

0.0.93

2 files

0.0.92

2 files

0.0.91

2 files

0.0.90

2 files

0.0.89

2 files

0.0.88

2 files

0.0.87

2 files

0.0.86

2 files

0.0.85

2 files

0.0.84

2 files

0.0.83

2 files

0.0.82

2 files

0.0.81

2 files

0.0.80

2 files

This release

0.0.79 This release

2 files

0.0.78

2 files

0.0.77

2 files

0.0.76

2 files

0.0.75

2 files

0.0.74

2 files

0.0.73

2 files

0.0.72

2 files

0.0.71

2 files

0.0.70

2 files

0.0.69

2 files

0.0.68

2 files

0.0.67

2 files

0.0.66

2 files

0.0.65

2 files

0.0.64

2 files

0.0.63

2 files

0.0.62

2 files

0.0.61

2 files

0.0.60

2 files

0.0.59

2 files

0.0.58

2 files

0.0.57

2 files

0.0.56

2 files

0.0.55

2 files

0.0.54

2 files

0.0.53

2 files

0.0.52

2 files

0.0.51

2 files

0.0.50

2 files

0.0.49

2 files

0.0.48

2 files

0.0.47

2 files

0.0.46

2 files

0.0.45

2 files

0.0.44

2 files

0.0.43

2 files

0.0.42

2 files

0.0.41

2 files

0.0.40

2 files

0.0.39

2 files

0.0.38

2 files

0.0.37

2 files

0.0.36

2 files

0.0.35

2 files

0.0.34

2 files

0.0.33

2 files

0.0.32

2 files

0.0.31

2 files

0.0.30

2 files

0.0.29

2 files

0.0.28

2 files

0.0.27

2 files

0.0.26

2 files

0.0.25

2 files

0.0.24

2 files

0.0.23

2 files

0.0.22

2 files

0.0.21

2 files

0.0.20

2 files

0.0.19

2 files

0.0.18

2 files

0.0.17

2 files

0.0.16

2 files

0.0.15

2 files

0.0.14

2 files

0.0.13

2 files

0.0.12

2 files

0.0.11

2 files

0.0.10

2 files

0.0.9

2 files

0.0.8

2 files

0.0.7

2 files

0.0.6

2 files

0.0.5

2 files

0.0.4

2 files

0.0.3

2 files

0.0.2

2 files

0.0.1

2 files

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