Ray Simple Job Submission Tutorial¶
A short guide to running a CheckMAITE capability asynchronously with the lightweight ray-simple job backend.
Who this is for: ML Engineer moving analyses off the notebook's main process, or a Data Scientist whose analyses outgrow their local machine.
Where this fits: stage 5, Run at scale, of the T&E workflow. It runs a stage 2–4 capability as a local Ray task and writes the result to the analytics store. For tracked jobs on a shared cluster, move on to the Ray Job Submission tutorial.
When to use this backend¶
Use ray-simple for local notebooks, demos, and single-driver workflows where you want one Ray task per submitted capability run.
Important assumptions:
- job handles live only in the current Python process;
- every submission creates a new Ray task;
- completed results are written to the configured analytics store before
job.result()succeeds.
Setup¶
import tempfile
from pathlib import Path
from checkmaite.core.analytics_store import AnalyticsStore, ParquetBackend
from checkmaite.core.object_detection import DataevalCleaning
from checkmaite.core.object_detection.dataset_loaders import load_coco_detection_dataset
from checkmaite.jobs import (
configure_job_backend,
get_job,
list_jobs,
shutdown_job_backend,
submit_capability,
)
# Find the repository root whether the notebook is run from docs/tool-usage or elsewhere.
REPO_ROOT = next(path for path in [Path.cwd(), *Path.cwd().parents] if (path / "pyproject.toml").exists())
# Use the tiny COCO fixture included with the repository.
dataset_root = REPO_ROOT / "tests/data_for_tests/coco_dataset"
dataset_ann = dataset_root / "ann_file.json"
dataset = load_coco_detection_dataset(
root=str(dataset_root),
ann_file=str(dataset_ann),
dataset_id="coco-job-tutorial",
)
output_root = Path(tempfile.mkdtemp(prefix="checkmaite_jobs_"))
store_dir = output_root / "analytics_store"
analytics_store_config = {"backend": "parquet", "uri": str(store_dir)}
artifact_store_config = {"uri": str(output_root / "report_artifacts")}
print(f"Dataset: {dataset.metadata['id']} ({len(dataset)} images)")
print(f"Analytics store: {store_dir}")
/home/runner/work/checkmaite/checkmaite/.venv/lib/python3.11/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html from .autonotebook import tqdm as notebook_tqdm 2026-11-02 18:11:17,404 INFO util.py:155 -- Missing packages: ['ipywidgets']. Run `pip install -U ipywidgets`, then restart the notebook server for rich notebook output.
Dataset: coco-job-tutorial (4 images) Analytics store: /tmp/checkmaite_jobs_zz0i41o4/analytics_store
Configure ray-simple¶
The required analytics- and artifact-store configs are forwarded before workers run.
configure_job_backend(
"ray-simple",
address="local",
force_reinit=True,
analytics_store=analytics_store_config,
artifact_store=artifact_store_config,
)
print("Configured ray-simple job backend.")
2026-11-02 18:11:17,463 WARNING authentication_token_setup.py:85 -- Token authentication is enabled for this Ray cluster. Set RAY_AUTH_MODE=disabled to opt out. For more information, see https://docs.ray.io/en/latest/ray-security/token-auth.html
2026-11-02 18:11:17,463 INFO authentication_token_setup.py:50 -- Generated new authentication token and saved to /home/runner/.ray/auth_token
2026-11-02 18:11:20,752 INFO worker.py:2024 -- Started a local Ray instance. View the dashboard at http://127.0.0.1:8265
Configured ray-simple job backend.
Submit a capability job¶
capability = DataevalCleaning()
job = submit_capability(
capability,
datasets=[dataset],
use_cache=False,
)
print(f"Job ID: {job.job_id}")
print(f"Initial status: {job.status}")
Job ID: 1c29e24495b540188df61e54b011b5d4 Initial status: JobStatus.PENDING
Wait for completion and get the result reference¶
job.result() returns a CapabilityRunRef, not the full capability output object.
final_status = job.wait(timeout=120)
print(f"Final status: {final_status}")
ref = job.result(timeout=10)
print(f"Run UID: {ref.run_uid}")
print(f"Store URI: {ref.store_uri}")
(_execute_capability_ref pid=5142) /home/runner/work/checkmaite/checkmaite/src/checkmaite/core/_common/dataeval_cleaning_capability.py:532: FutureWarning: The default value of normalize_pixel_values will change from True to False in v1.1. Pass normalize_pixel_values explicitly to silence this warning. (_execute_capability_ref pid=5142) stats = compute_stats( (_execute_capability_ref pid=5142) /home/runner/work/checkmaite/checkmaite/src/checkmaite/core/object_detection/dataeval_cleaning_capability.py:41: FutureWarning: The default value of normalize_pixel_values will change from True to False in v1.1. Pass normalize_pixel_values explicitly to silence this warning. (_execute_capability_ref pid=5142) boxes_stats_output = compute_stats(
Final status: JobStatus.COMPLETED Run UID: 7a553ac2b7b42fd836159672b761d777fba055ad19f77f39cdf2c3c17b9234ed Store URI: /tmp/checkmaite_jobs_zz0i41o4/analytics_store/dataeval_cleaning/1793643085763_71567f4a.parquet
List jobs remembered by this backend object¶
for remembered_job in list_jobs(limit=10):
print(remembered_job.job_id, remembered_job.status)
print("Fetched by ID:", get_job(job.job_id).status)
1c29e24495b540188df61e54b011b5d4 JobStatus.COMPLETED Fetched by ID: JobStatus.COMPLETED
Query the analytics store¶
store = AnalyticsStore(ParquetBackend(str(store_dir)))
print(f"Tables: {store.list_tables()}")
cleaning_results = store.query_sql("""
SELECT
dataset_id,
exact_duplicate_count,
image_outlier_count,
image_outlier_ratio,
mean_brightness
FROM dataeval_cleaning
""")
print(cleaning_results)
Tables: ['dataeval_cleaning', 'runs'] shape: (1, 5) ┌───────────────────┬────────────────────┬───────────────────┬───────────────────┬─────────────────┐ │ dataset_id ┆ exact_duplicate_co ┆ image_outlier_cou ┆ image_outlier_rat ┆ mean_brightness │ │ --- ┆ unt ┆ nt ┆ io ┆ --- │ │ str ┆ --- ┆ --- ┆ --- ┆ f64 │ │ ┆ i64 ┆ i64 ┆ f64 ┆ │ ╞═══════════════════╪════════════════════╪═══════════════════╪═══════════════════╪═════════════════╡ │ coco-job-tutorial ┆ 0 ┆ 0 ┆ 0.0 ┆ 0.305882 │ └───────────────────┴────────────────────┴───────────────────┴───────────────────┴─────────────────┘
Shut down¶
shutdown_job_backend(wait=True)
print("Job backend shut down.")
Job backend shut down.