Skip to content
ashgillmanPublic

About

A library for interacting with Radmachine - uploads, backups and logging/reporting

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

radlog — RadMachine workflow tools

What radlog is for

RadMachine is the system of record for equipment QA, service events, faults, and review. radlog is a small Python library and command-line tool for workflows that need to reuse those records outside a single RadMachine test list or report. It reads the RadMachine API, resolves related records, and lets you define how to filter, combine, present, or draft from them.

The main use case is turning several source records into one useful piece of work. For example, a monthly linac logbook entry may draw on many performed QA sessions and a service event. A composite QA test may need results from both monthly dosimetry and a QuickCheck session. Radlog can find those sources, retain their links and IDs, and prepare an output for a person to review.

Current interfaces:

Needradlog entry point
Inspect or export API recordspython -m radlog.cli --export-raw ...
Build factual QA reports with local filterspython -m radlog.cli --report qa ...
Draft Org logbook entries for reviewM-x radlog-import-radmachine
Build a composite QA submissionexamples/quickcheck_constancy_tcc.py
Write another site workflowradlog.api, radlog.collect, radlog.qa_results

Radlog does not replace RadMachine’s QA review or clinical record. Its Org entries are editable summaries, and its example QA compiler shows the proposed payload before any upload.

How it relates to RadMachine

RadMachine already provides configurable QA tests, Python calculations, trending, scheduled and ad hoc reports, service and fault logging, and an API. Use those native features for routine data entry, analysis, and review. Radlog is useful when a task needs custom selection across sessions or record types, a local report format or filter, an external authored logbook, or a repeatable transformation before API submission.

Radformation’s RadMachine overview describes the product features. Its feature comparison lists API access. The public QATrack+ API guide documents a related JSON API, including pagination, filtering, and test-list submission. Radlog’s endpoint choices and RadAuthorization header are based on the API behaviour observed on a RadMachine customer instance; QATrack+ documentation is useful background, not a complete specification for every RadMachine deployment. Confirm instance-specific fields and permissions before adapting a workflow.

Start here

This repository is currently intended for use from a source checkout. The Nix development shell supplies Python, requests, Emacs, and a radlog command wrapper:

nix develop

Run commands from the checkout root. If you use direnv, arrange for it to load the Nix shell and your local environment, then run direnv allow. Without Nix, use a Python environment with requests installed and run python -m radlog.cli from the checkout root.

Copy config.toml.example to ~/.config/radlog/config.toml (or pass --config /path/to/config.toml). Set your base URL and customer ID. The recommended token setup is:

[radmachine]
base_url = "https://radmachine.radformation.com"
customer_id = "your-customer-id"
username = "your-username"
token_env = "RADMACHINE_TOKEN"

Set RADMACHINE_TOKEN in your shell environment or a local secret manager. Do not commit a token. The example config also supports a local token field. RADLOG_CONFIG can point to a different config file. On Windows, the default config location is %APPDATA%\radlog\config.toml.

Check connectivity and available API roots:

python -m radlog.cli

The client uses token authentication and the customer API root /<customer_id>/api/. It follows paginated results responses. The CLI reports API errors to stderr.

Workflows

Explore source records

Use raw export to inspect records before writing a transformation:

python -m radlog.cli \
  --export-raw qa-testlistinstances \
  --start 2026-09-30 --end 2026-09-30 \
  --limit 100

Other targets are qa-testinstances, qa-unittestcollections, units, service-events, and service-log-return-to-service-qa. Repeated --param KEY=VALUE options pass API filters through to RadMachine. For targets with a known date field, --start and --end also filter returned records locally. Raw export does not write back to RadMachine.

For normalized records, use --collect qa-sessions. For draft candidates, use --collect qa-candidates:

python -m radlog.cli \
  --collect qa-candidates \
  --start 2026-09-30 --end 2026-09-30 \
  --user your-username

The JSON contains source records and grouped candidates, including their rendered_org drafts. Candidate output depends on the configured grouping rules and renderer. The conservative defaults group by date, unit, and source title; the example modules under examples/ show a more tailored logbook. The --user filter applies to QA sessions; service events are collected for the date range independently.

Review Org logbook drafts

Load elisp/radlog.el in Emacs, configure a destination Org file and an Org heading ID, then run M-x radlog-import-radmachine. The command asks for a date range and username, retrieves candidates, and inserts each draft into its destination buffer for in-place editing and review.

(load-file "/path/to/radlog/elisp/radlog.el")
(setq radlog-python-command "python"
      radlog-target-file "~/org/logbook.org"
      radlog-destination-map
      '(("default" :file "~/org/logbook.org" :id "YOUR-ORG-HEADING-ID")))

Emacs must be able to run Python with requests installed. The command runs Python from the repository root. If your Python executable is elsewhere, set radlog-python-command accordingly. For different logbook subtrees, map specific candidate entry_type values to :file and :id destinations.

During review, edit the Org text normally, then use:

KeyAction
C-c C-cKeep the edited draft and continue
C-c C-kRemove this draft and skip it
C-c C-dDefer it until the remaining candidates are reviewed
C-c C-qQuit and discard unreviewed candidates

Each draft includes RM_GROUP_KEY and RM_SOURCE_IDS properties. If its group key is already present in the target buffer, Emacs asks whether to insert it again. A skipped or deferred draft is removed from the buffer. Kept entries remain authored logbook records; review their wording and source links before accepting them.

Make a focused QA report

The report command collects performed QA results and supports JSON, plain text, HTML, or a temporary local browser preview:

python -m radlog.cli \
  --report qa --last-week \
  --where 'issue in action,tolerance,comment' \
  --render html-serve

--render html-serve serves a temporary local page until Ctrl-C. --render html writes HTML to stdout. Use --start and --end for explicit dates, --user to restrict QA submitted by a particular account, and --group-by equipment or --group-by date for display. Reports include all result rows by default; --filter-by-results action,tol,comment is a short form for common filtering.

Repeat --where to combine conditions with AND. Expressions support parentheses, !, in, not-in, contains, matches, exists, missing, -not, -and, and -or; a comma is also an OR operator.

python -m radlog.cli \
  --report qa --last-month \
  --where '( issue = action -or issue = tolerance ) -and equipment matches "LA.*"' \
  --render plaintext

Define repeatable named reports under [reports.NAME] in your TOML config; config.toml.example contains one. A preset may set its date window, filters, renderer, and grouping. CLI date/render/grouping flags can override those defaults. Preset source filters are not combined with CLI source filters; define a second preset for a different selection.

Compose a QA result from earlier sessions

examples/quickcheck_constancy_tcc.py is a site-specific example. It finds monthly dosimetry and same-day QuickCheck sessions, resolves result slugs, then builds a QuickCheck constancy submission payload with source links.

python -m examples.quickcheck_constancy_tcc \
  --linac LA11 --date 2026-09-30 \
  --interactive-select --dry-run

The default is a dry run: it prints the draft and payload without submitting anything. --interactive-select lets you choose when more than one session matches a source role. --practice-run submits to the example’s practice assignment; --upload submits to the target assignment resolved from the QuickCheck serial. Both write modes require a battery-check result and should be adapted to the site’s own test definitions before use. Run this example with python -m examples.quickcheck_constancy_tcc from the checkout root.

Build a site workflow

The reusable layers are intentionally small:

  • radlog.api.RadMachineClient handles authenticated JSON requests, pagination, and selected typed endpoints.
  • radlog.rm_models exposes common API fields while retaining each raw payload for fields the model does not yet know.
  • radlog.collect resolves QA sessions with their assignments and units, collects service events, and normalizes source records.
  • radlog.qa_results maps performed result rows to test-definition slugs.
  • radlog.group converts normalized records into candidates using a GroupingRules object.
  • radlog.render and radlog.renderers render candidate drafts.

To customize a logbook, copy examples/group_tcc_similar.py and examples/render_ag_org.py into a personal extensions directory and set:

[extensions]
paths = ["~/.config/radlog/extensions"]

[grouping]
rules = "my_grouping:RULES"

[render]
logbook_org_renderer = "my_render:render_candidate"

Extension paths are expanded from ~; relative paths are resolved from the process working directory. Keep site names, source selection rules, and output templates in those modules rather than changing the API client. For a known set of assignments, use collect_unit_test_collections followed by collect_resolved_qa_sessions_for_collections to avoid scanning all QA sessions. The examples/sample_api_payloads/ directory contains redacted records for offline development.

Scope and current limits

The library supports the endpoints and shapes exercised here; it is not a complete RadMachine SDK. The default logbook grouping is deliberately conservative, while the richer examples encode local conventions. A draft requires human review, especially for clinical meaning, notable events, and links. The QA report path currently covers QA result rows, not every RadMachine report type. Fault extraction and broader candidate classification remain future work; see TODO.org.

About

A library for interacting with Radmachine - uploads, backups and logging/reporting

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages