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:
| Need | radlog entry point |
|---|---|
| Inspect or export API records | python -m radlog.cli --export-raw ... |
| Build factual QA reports with local filters | python -m radlog.cli --report qa ... |
| Draft Org logbook entries for review | M-x radlog-import-radmachine |
| Build a composite QA submission | examples/quickcheck_constancy_tcc.py |
| Write another site workflow | radlog.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.
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.
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 developRun 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.cliThe client uses token authentication and the customer API root
/<customer_id>/api/. It follows paginated results responses. The CLI
reports API errors to stderr.
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 100Other 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-usernameThe 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.
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:
| Key | Action |
|---|---|
C-c C-c | Keep the edited draft and continue |
C-c C-k | Remove this draft and skip it |
C-c C-d | Defer it until the remaining candidates are reviewed |
C-c C-q | Quit 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.
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 plaintextDefine 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.
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-runThe 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.
The reusable layers are intentionally small:
radlog.api.RadMachineClienthandles authenticated JSON requests, pagination, and selected typed endpoints.radlog.rm_modelsexposes common API fields while retaining each raw payload for fields the model does not yet know.radlog.collectresolves QA sessions with their assignments and units, collects service events, and normalizes source records.radlog.qa_resultsmaps performed result rows to test-definition slugs.radlog.groupconverts normalized records into candidates using aGroupingRulesobject.radlog.renderandradlog.renderersrender 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.
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.