matrx-scheduler

Server-side execution engine for the matrx scheduling spine (sch_* tables in Supabase). Provides:

  • a scanner loop that claims due tasks atomically,
  • a runner that drives the host's agent_runner / tool_runner,
  • an authoritative cron parser + next-due computation,
  • and (since 0.3) an HTTP API surface (FastAPI) for task / trigger / run CRUD, manual fires, scanner status, and cron preview.

Any host application (aidream is the reference) wires it up via configure() and either runs the scanner directly, mounts the HTTP routes, or both.

What it does (under the hood)

  • Polls sch_task for rows where next_due_at <= now() and the host surface is in surfaces[] (or 'any').
  • Atomically claims a candidate by inserting a sch_run with claim_token and claim_expires_at (the lease).
  • Drives the matrx-ai agent runner (host-injected) against the claimed task, or the host's tool_runner for kind='tool'.
  • Writes back results (status, result_summary, output_ref, etc.).
  • Recomputes the next fire time on recurring triggers; the DB cascade updates sch_task.next_due_at automatically.

Capability-within, injection-without

matrx-scheduler doesn't import from a host app. It exposes a configure() function the host calls at startup, passing in:

  • supabase_client — service-role client used by the SCANNER to read sch_task across users and update lease state.
  • surface — the string this host identifies as in sch_task.surfaces[] (e.g. 'server' for aidream, 'desktop' for matrx-local).
  • agent_runner — callable that runs an agent (kind='agent' tasks).
  • tool_runner — optional callable for kind='tool' tasks. Hosts that don't claim tool tasks (e.g. aidream itself) leave this unset.
  • user_supabase_factory — optional callable (user_jwt) -> AsyncClient used by the HTTP routes to build per-request user-scoped clients. If not provided, the package falls back to an env-based factory keyed on SUPABASE_MATRIX_URL + SUPABASE_MATRIX_PUBLISHABLE_KEY.
  • get_app_context, emitter_factory, scan_interval_seconds, lease_seconds — see the _ext.configure docstring.

Install with the host extra (pip install matrx-scheduler[host]) when using it inside a full host app. Add the api extra (pip install matrx-scheduler[api]) to mount the HTTP routes.

HTTP API

Available since 0.3. Optional — drop the import if you only want the scanner.

from fastapi import FastAPI
import matrx_scheduler

app = FastAPI()

# Host startup wiring (any host).
matrx_scheduler.configure(
    supabase_client=service_role_client,
    surface="server",  # or "desktop", "extension", ...
    agent_runner=my_agent_runner,
    user_supabase_factory=my_user_client_factory,  # optional
)
await matrx_scheduler.start_scanner()

# Mount the HTTP routes.
matrx_scheduler.api.include_routers(app, prefix="/scheduler")

Endpoints

All routes use matrx_connect.AppContext via Depends(context_dep). Every write goes through a per-request Supabase client built from the caller's JWT; RLS is the only line of authority on row ownership. The service-role client (used by the scanner) is never accessible from these routes.

Method Path Purpose
POST /scheduler/tasks Create a task (optionally with agent_task + trigger)
GET /scheduler/tasks List tasks (filter by kind, enabled)
GET /scheduler/tasks/{id} Get task hydrated with agent_task, triggers, runs
PATCH /scheduler/tasks/{id} Patch task fields (title, enabled, tags, etc.)
DELETE /scheduler/tasks/{id} Soft-delete (set enabled=false)
POST /scheduler/tasks/{id}/run-now Enqueue a manual run via sch_enqueue_manual_run
GET /scheduler/triggers?task_id=... List triggers for a task
POST /scheduler/triggers Create a trigger on an existing task
PATCH /scheduler/triggers/{id} Patch a trigger (recomputes next_due_at if type/config changed)
DELETE /scheduler/triggers/{id} Hard-delete a trigger
GET /scheduler/runs?task_id=...&status=... List run history
GET /scheduler/runs/{id} Get one run
POST /scheduler/cron/validate Validate a cron expression + preview next N fires
POST /scheduler/cron/preview-fires Preview next-fire times for any trigger config
POST /scheduler/compute-next-due-at Compute the single next due_at for a trigger config
GET /scheduler/status Scanner health (admin only)

PATCH distinguishes an omitted nullable field from an explicit JSON null. Sending {"description": null} or {"expires_at": null} clears that field; omitting it leaves the stored value unchanged. This distinction is enforced with Pydantic's model_fields_set, never by dropping every None value.

Co-existence with aidream's /scheduling/*

aidream had a small router at /scheduling/* (cron validation, run-now, admin force-disable) before this surface existed. The package routes use /scheduler/* (singular) so they don't collide. aidream can mount both simultaneously, or migrate clients to the package routes opportunistically. matrx-local mounts only the package routes; it has no /scheduling/* routes to begin with.

See docs/SCHEDULING.md in the matrx-frontend repo for the full data-model spec, trigger taxonomy, and lifecycle.

Key dates

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

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

api dev host

Tags

agents cron matrx scheduler supabase

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_scheduler-0.3.149.tar.gz (74.9 kB view details)

Uploaded Source

Built Distribution

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

matrx_scheduler-0.3.149-py3-none-any.whl (59.3 kB view details)

Uploaded Python 3

File details

Details for the file matrx_scheduler-0.3.149.tar.gz.

File metadata

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

File hashes

Hashes for matrx_scheduler-0.3.149.tar.gz
Algorithm Hash digest
SHA256 55dff73705f99acba03c6d3ad9df4f1f135d712e6db2568b59f36ed0616aa09f
MD5 4e3d17353448a3cdb50ac53575918e0c
BLAKE2b-256 766d6b97e724c6da248b8a550779a8425c82e7ec8ca02ea791f9569e4a9e32ac

See more details on using hashes here.

Provenance

The following attestation bundles were made for matrx_scheduler-0.3.149.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_scheduler-0.3.149-py3-none-any.whl.

File metadata

File hashes

Hashes for matrx_scheduler-0.3.149-py3-none-any.whl
Algorithm Hash digest
SHA256 bb81b72721f201080ff27ec3054aa76be7f8b61ebea3959c7078c7b397b12957
MD5 45cd630cde4d987558fe256e82819300
BLAKE2b-256 2682c4f235218dde48597efe9108de7da0fb7f2448408f5c6227910b2e190bd1

See more details on using hashes here.

Provenance

The following attestation bundles were made for matrx_scheduler-0.3.149-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.3.156

2 files

0.3.155

2 files

0.3.154

2 files

0.3.153

2 files

0.3.152

2 files

0.3.151

2 files

0.3.150

2 files

This release

0.3.149 This release

2 files

0.3.148

2 files

0.3.147

2 files

0.3.146

2 files

0.3.145

2 files

0.3.144

2 files

0.3.143

2 files

0.3.142

2 files

0.3.141

2 files

0.3.140

2 files

0.3.139

2 files

0.3.138

2 files

0.3.137

2 files

0.3.136

2 files

0.3.135

2 files

0.3.134

2 files

0.3.133

2 files

0.3.132

2 files

0.3.131

2 files

0.3.130

2 files

0.3.129

2 files

0.3.128

2 files

0.3.127

2 files

0.3.126

2 files

0.3.125

2 files

0.3.124

2 files

0.3.123

2 files

0.3.122

2 files

0.3.121

2 files

0.3.120

2 files

0.3.119

2 files

0.3.118

2 files

0.3.117

2 files

0.3.116

2 files

0.3.115

2 files

0.3.114

2 files

0.3.113

2 files

0.3.112

2 files

0.3.111

2 files

0.3.110

2 files

0.3.109

2 files

0.3.108

2 files

0.3.107

2 files

0.3.106

2 files

0.3.105

2 files

0.3.104

2 files

0.3.103

2 files

0.3.102

2 files

0.3.101

2 files

0.3.100

2 files

0.3.99

2 files

0.3.98

2 files

0.3.97

2 files

0.3.96

2 files

0.3.95

2 files

0.3.94

2 files

0.3.93

2 files

0.3.92

2 files

0.3.91

2 files

0.3.90

2 files

0.3.89

2 files

0.3.88

2 files

0.3.87

2 files

0.3.86

2 files

0.3.85

2 files

0.3.84

2 files

0.3.83

2 files

0.3.82

2 files

0.3.81

2 files

0.3.80

2 files

0.3.79

2 files

0.3.78

2 files

0.3.77

2 files

0.3.76

2 files

0.3.75

2 files

0.3.74

2 files

0.3.73

2 files

0.3.72

2 files

0.3.71

2 files

0.3.70

2 files

0.3.69

2 files

0.3.68

2 files

0.3.67

2 files

0.3.66

2 files

0.3.65

2 files

0.3.64

2 files

0.3.63

2 files

0.3.62

2 files

0.3.61

2 files

0.3.60

2 files

0.3.59

2 files

0.3.58

2 files

0.3.57

2 files

0.3.56

2 files

0.3.55

2 files

0.3.54

2 files

0.3.53

2 files

0.3.52

2 files

0.3.51

2 files

0.3.50

2 files

0.3.49

2 files

0.3.48

2 files

0.3.47

2 files

0.3.46

2 files

0.3.45

2 files

0.3.44

2 files

0.3.43

2 files

0.3.42

2 files

0.3.41

2 files

0.3.40

2 files

0.3.39

2 files

0.3.38

2 files

0.3.37

2 files

0.3.36

2 files

0.3.35

2 files

0.3.34

2 files

0.3.33

2 files

0.3.32

2 files

0.3.31

2 files

0.3.30

2 files

0.3.29

2 files

0.3.28

2 files

0.3.27

2 files

0.3.26

2 files

0.3.25

2 files

0.3.24

2 files

0.3.23

2 files

0.3.22

2 files

0.3.21

2 files

0.3.20

2 files

0.3.19

2 files

0.3.18

2 files

0.3.17

2 files

0.3.16

2 files

0.3.15

2 files

0.3.14

2 files

0.3.13

2 files

0.3.12

2 files

0.3.11

2 files

0.3.10

2 files

0.3.9

2 files

0.3.8

2 files

0.3.7

2 files

0.3.6

2 files

0.3.5

2 files

0.3.4

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

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