Skip to content

Migrate from background threads to Ray actors#46

Draft
metesaka wants to merge 37 commits into
mainfrom
ums-ray-backend
Draft

Migrate from background threads to Ray actors#46
metesaka wants to merge 37 commits into
mainfrom
ums-ray-backend

Conversation

@metesaka

@metesaka metesaka commented Jul 4, 2026

Copy link
Copy Markdown
Contributor

This PR is for changing the acquirium backend to use Ray for running Apps (soft sensors), Drivers and other background processes without using python threads or Docker.

Builds on #45 so we need to merge that one first

metesaka added 29 commits June 29, 2026 22:09
ParquetIngestDriver mirrors the CSV/XLSX tabular drivers: watches a
directory for *.parquet/*.pq files, supports wide/narrow layouts and
row-offset paging. Includes unit tests.
Adopt the build -> change_inputs -> solve model contract and load points
from the model's watertap-mapping.json instead of a hand-authored RDF
graph. Registering a stream per mapped point writes its external
reference and Pyomo variable (hasExternalReference/hasPyomoVar) via the
insert-graph interface. watertap_graph_path is now optional (model
ontology insert). Tests updated to the mapping contract.
Quote the dependency (the unquoted entry was invalid TOML and broke
test collection); streamlit is required by the WaterTAP GUI driver.
Point the example at watertap_mapping_path (+ optional model.ttl insert)
and document the new required/optional keys.
Each model folder exposes the standard interface: build-and-solve.py
(build/change_inputs/solve), generate-values.py (generate_new_values),
watertap-mapping.json (point URI -> Pyomo path), and an s223 model.ttl.
Remove the old flat simple-pipe ttl.
data-generator.py writes parquet snapshots for any model folder.
simulation_driver.py auto-generates inputs and solves each tick;
gui_driver.py solves on changes from a model-agnostic Streamlit GUI
(input_gui.py). acquirium.toml wires both models x {simulation, GUI,
parquet} with one block enabled. Remove the old pump scripts.
Single README introducing both models, data generation, the drivers,
and how to change the config; replaces the two per-model READMEs.
 - New app methods to start, stop and list drivers
 - Removing driver only server command
 - All drivers are now ray actors
 - App manages all of the drivers
 - cli changes for server, users can add new drivers to a running server but not in different processes
@metesaka

metesaka commented Jul 4, 2026

Copy link
Copy Markdown
Contributor Author

Changes up to now:

Drivers no longer run as daemon threads inside the server process — each one
runs as a Ray actor that connects back to the server over the HTTP API. This
is the first step of moving the backend's concurrency onto Ray, and it makes
drivers independently startable, stoppable, and observable at runtime.

Driver execution on Ray

  • DriverRunner actor (Server/ray_backend.py): hosts one driver's
    tick loop. The driver is constructed and setup() inside the actor, so
    driver state never crosses the process boundary. Graceful stop via an
    asyncio event — driver.stop() cleanup actually runs.
  • DriverSupervisor: name-keyed registry of runner actors, owned by the
    FastAPI app. Holds its lock across setup() so setup-time graph writes
    stay serialized (same guarantee the old thread staging gave).
  • New endpoints: POST /drivers/start, POST /drivers/stop,
    GET /drivers/list.
  • New CLI: acquirium driver start <config.toml> (submits drivers and
    exits), acquirium driver list, acquirium driver stop --name X.
  • [[drivers]] in the server config still work: a startup task waits for
    /health, then starts them through the supervisor.
  • ray.init/ray.shutdown live in the FastAPI lifespan; drivers are stopped
    cleanly on shutdown.

Breaking changes

  • Drivers now always talk to the server over HTTP; the in-process
    DirectAcquirium path for drivers is gone.
  • [server] enabled = false no longer runs driver loops locally — it submits
    the config's drivers to the remote server (same as acquirium driver start).
  • Driver specs are imported on the server host: path/to/file.py:Class
    entries must resolve on the machine running the server.
  • New dependency: ray. Note Ray's uv hook requires launching
    uv run acquirium server from the repo root (or set
    RAY_ENABLE_UV_RUN_RUNTIME_ENV=0).

Testing

  • New integration test (tests/integration/test_driver_ray.py): boots a
    real server subprocess with a [[drivers]] entry and verifies the full
    path — actor startup, CSV ingestion over HTTP (exact row counts including
    text-valued status streams), live pickup of files dropped into watch_dir,
    and stop/restart/duplicate-rejection via the API. Uses the new
    tests/dummy fixture plant (CSV driver + model + data generator). The
    embedding cache is persisted under tests/.cache/ so reruns take ~2 min.

@metesaka

metesaka commented Jul 9, 2026

Copy link
Copy Markdown
Contributor Author

Changes up to now:

  • Added a regulation example to DPR
  • Embedding model is moved to acquirium data dir (otherwise OS might delete certain parts of it in temporary directories)
  • Fix the sparql query generator to improve find entity and related entity queries. Performance increase upto 60-70x
  • Minor edits to ray backend

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant