Skip to main content

screendoor

PyPI Python versions CI License GitHub stars

screendoor runs dynamic screens: searches over trials (knockouts, ablations, parameter sweeps) where the next trials depend on the results of earlier ones, on a workstation or a Slurm cluster, with no database, broker or server.

A daemon wakes on a cron schedule, rebuilds state from append-only JSONL records, asks the assay's churn function what to do next, and carries out the actions it returns. The records are the state: kill the daemon at any moment; start it again and the dispatch resumes. Churn is pure: records in, actions out. Every side effect is a hook, and no hook has a default: a dispatch sets all of its hooks; the dispatchdir's dispatch_hooks.json sets the daemon's.

screendoor is standard library only, Python 3.10+. Built-in assays cover smoke tests, potentiation scans and skeletonization (jenga, ddmin, Minesweeper, hybrid and GAMA); see docs/skeletonization.md. Trials run as local processes or as Slurm array jobs. See docs/guide.md for writing assays, every dispatch setting and hook, trials, the daemon, storage and orchestrators.

Usage

mkdir -p work && cat > work/dispatch_hooks.json <<'JSON'
{
  "how_read_dispatch_submissions": "scd.record.appendjsonl.read_dispatch_submissions()",
  "how_write_dispatch_submissions": "scd.record.appendjsonl.write_dispatch_submissions()",
  "how_read_dispatch_payloads": "scd.record.appendjsonl.read_dispatch_payloads()",
  "how_write_dispatch_payloads": "scd.record.appendjsonl.write_dispatch_payloads()",
  "how_read_dispatch_telemetry": "scd.record.appendjsonl.read_dispatch_telemetry()",
  "how_write_dispatch_telemetry": "scd.record.appendjsonl.write_dispatch_telemetry()",
  "how_log_info": "logging.info",
  "how_notify_liveness": "scd.notify.null.notify()",
  "how_notify_termination": "scd.notify.log.notify()"
}
JSON
python3 -m screendoor.daemon.submit_dispatch - --dispatchdir work <<JSON
{
  "meta_project": "default",
  "meta_experiment": "default",
  "meta_treatment": "default",
  "meta_user": "$(id -un)",
  "meta_redo": "0",
  "meta_seed": 1,
  "assay": "scd.churn.seed_global_rngs(scd.assaylib.testing.exercise)",
  "assay_kwargs": {"n": 4, "cmd": "echo \"!!!screendoor:payload \$((i * i))\""},
  "schedule": "* * * * *",
  "how_launch": "scd.orch.subprocess.launch()",
  "how_poke": "scd.orch.subprocess.poke()",
  "how_kill": "scd.orch.subprocess.kill()",
  "how_throttle_churn": "scd.orch.subprocess.throttle(max_procs=4)",
  "how_setup": "scd.record.appendjsonl.setup()",
  "how_read_trial_submissions": "scd.record.appendjsonl.read_trial_submissions()",
  "how_write_trial_submissions": "scd.record.appendjsonl.write_trial_submissions()",
  "how_read_trial_payloads": "scd.record.appendjsonl.read_trial_payloads()",
  "how_write_trial_payloads": "scd.record.appendjsonl.write_trial_payloads()",
  "how_prep_trial_payloads": "scd.record.appendjsonl.prep_trial_payloads()",
  "how_read_trial_telemetry": "scd.record.appendjsonl.read_trial_telemetry()",
  "how_write_trial_telemetry": "scd.record.appendjsonl.write_trial_telemetry()",
  "how_read_churn_memo": "scd.record.appendjsonl.read_churn_memo()",
  "how_write_churn_memo": "scd.record.appendjsonl.write_churn_memo()",
  "how_read_churn_notify": "scd.record.appendjsonl.read_churn_notify()",
  "how_write_churn_notify": "scd.record.appendjsonl.write_churn_notify()",
  "how_notify_progress": "scd.notify.log.notify()",
  "how_notify_eta": "scd.notify.log.notify()",
  "how_notify_success": "scd.notify.log.notify()",
  "how_notify_failure": "scd.notify.log.notify()",
  "how_notify_warning": "scd.notify.log.notify()",
  "how_notify_anomaly": "scd.notify.log.notify()",
  "how_unblock_churn": "scd.unblock.all_trials_ready()",
  "how_cleanup_success": "scd.cleanup.tar(clear=True)",
  "how_cleanup_failure": "lambda ctx, completed: None"
}
JSON
python3 -m screendoor.daemon.run_busyloop --dispatchdir work
python3 -m screendoor.daemon.print_status --dispatchdir work

dispatch_hooks.json holds the daemon's own hooks. The dispatch has labels, an assay with its kwargs, a cron schedule and its hooks; the smoke-test assay here launches n trials of cmd, each with $i in its env, and succeeds with what they sent. The second heredoc is unquoted so the shell fills in meta_user, so the trial script's $ is written \$. Submitting only records the dispatch; run_busyloop runs it, ticking until nothing is open. print_status then shows it succeeded with results [0, 1, 4, 9], and work/ holds:

work/
  dispatch_hooks.json
  dispatch_submissions.jsonl  dispatch_payloads.jsonl  dispatch_telemetry.jsonl
  dispatch_notify.jsonl       dispatch_log.txt
  project=default/
    date=2026-11-12+what=default%default%1+redo=0/
      trial_submissions.jsonl  trial_payloads.jsonl  trial_telemetry.jsonl
      churn_notify.jsonl
      jobs/            # the local processes' pidfiles and logs
      trials.tar.gz    # trials/ (cmd.sh, stdout, stderr), archived on success

python3 -m screendoor lists every command.

Installation

python3 -m pip install screendoor

From source:

git clone https://github.com/mmore500/screendoor
python3 -m pip install ./screendoor

On a cluster, the daemon can run from the container image:

apptainer exec docker://ghcr.io/mmore500/screendoor:v0.1.2 \
  python3 -m screendoor.daemon.run_tick_once --dispatchdir .
eval "$(apptainer exec docker://ghcr.io/mmore500/screendoor:v0.1.2 \
  cat /opt/screendoor/slurm-binds.sh | sh)"

The worker runs on the host. Where screendoor isn't installed, point the launcher at the .pyz attached to each GitHub release: scd.orch.slurm.launch(worker="python3 /shared/screendoor-0.1.0.pyz worker").

AI Use

Substantial portions of screendoor were prepared using agentic coding tools.

Metadata

Release files for screendoor 0.1.2

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

Source distribution (sdist)

Source distribution for screendoor 0.1.2
File Size Uploaded Provenance Actions
screendoor-0.1.2.tar.gz 122.8 kB Without provenance Details for screendoor-0.1.2.tar.gz

Built distribution (wheel)

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

Total release size: 282.5 kB

Release files / screendoor-0.1.2.tar.gz

Download URL screendoor-0.1.2.tar.gz
Size 122.8 kB
Tags Source
SHA-256 checksum
How to use checksums
9a5ec29aff823c31867e4041589fca9ec833ed7ea2f04faf69597cbec3a9d81e
BLAKE2b-256 checksum
How to use checksums
8d1a43bbe35372b498c5dc9261482f2dbc37e5e8907bf7fefe5d54e5d7ec546a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / screendoor-0.1.2-py3-none-any.whl

Download URL screendoor-0.1.2-py3-none-any.whl
Size 159.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4c2cd2790281e02e5580b075dec3c27b6b698f3c522b81008a0d5f44fb35ad6a
BLAKE2b-256 checksum
How to use checksums
1084bad21443d12555021657615cb63f07b5a3344870db32dfea3700bb211330
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for screendoor 0.1.2

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

0.1.2 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