GeoSAGE assistant#

GeoSAGE provides geological interpretation of joint gravity–magnetic inversion models as an optional external assistant. Installing its Python package registers geosage.pyhydrogeophysx:ASSISTANT under the existing pyhydrogeophysx.assistants entry-point group, replacing the built-in GeoSAGE scaffold. AQUAH’s registry and workflows remain independent.

The source package is maintained at ZhengyangFang/GeoSAGE. During integration review, install the matching local source branch; older releases may not include this entry point. No private input data or results are included.

Install and start#

From the parent directory of the two source checkouts, in a separate Python 3.11–3.13 environment:

python -m pip install -c GeoSAGE/constraints-tested.txt -e "./PyHydroGeophysX[desktop,desktop-3d]" -e ./GeoSAGE
geosage-studio --module one_click

Alternatively launch Studio normally and choose GeoSAGE in the assistant picker. Install the optional plugin into the same environment as Studio; a frozen desktop build must include the package when rebuilt.

GeoSAGE uses the host’s existing OpenAI/Anthropic API providers and the Codex CLI and Claude Code CLI login bridge. Choose the provider in Assistant → Settings; CLI providers use the same setup and sign-in controls as AQUAH and require no copied API key. Both guided chat and automatic interpretation use that provider. The CLI bridge currently carries text rather than image input. Local inspection and numerical tasks stay offline even if a CLI is already signed in.

Using the workflow#

Copy files in your file manager and paste them into the assistant’s chat input, or drag them into it. Describe your task; AI classification maps files to the installed GeoSAGE plugin’s input roles or identifies them as RAG reference documents. Ambiguous purposes prompt a clarification. Geological literature is searched locally and matching excerpts are included in the AI request. This host chat retrieval is available independently of GeoSAGE’s own reference handling. See Desktop Studio (Qt) for supported reference formats and reading limits.

Choose a Project outside the source data folders. In Data & reports, add an Existing GeoSAGE inversion folder to inspect an archive, or a GeoSAGE configuration (JSON) for a configured inversion. The adapter requires the GeoSAGE input schema and does not infer region, magnetic field or mesh settings from a free-text goal. The independent geophysical module forms do not change the GeoSAGE configuration; a notice on those pages makes the separation explicit.

Choose View results, New inversion, or AI interpretation. Check the inputs and effective configuration before starting. The two local tasks execute without provider credentials. Its result is explicitly Needs review, not an accepted AI interpretation. For interpretation and report review, configure a provider in the assistant panel and select Generate interpretation in the workflow page. Enable per-step approval to inspect each of the six stages before it runs. The existing process cancellation and between-step pause mechanisms apply.

Completed task workflows open the result page with model, data-fit and report actions, plus the local save state. Unavailable artifacts have disabled actions. Saving through Ctrl+S or Saved Results updates that state; switching Project disables actions for a run absent from the newly selected Project.

Inspect exported figures and the VTK volume in Saved Results → Visualization. The compact view lists models and figures; Details reveals metadata and file management. Report displays the saved Markdown report, including its figures. An offline inspection contains a numerical evidence summary and is not presented as an AI interpretation. Model sections and data-fit figures share GeoSAGE’s notebook plotting implementation, with scales derived from each dataset. The property selector switches between density contrast, susceptibility and categorical geological identifiers. The clipping plane exposes the interior. The linked sections use physical coordinates and show values at the selected cell. Clicking a section updates all crosshairs; property changes preserve the selection, camera and clipping plane. Select two runs with Ctrl-click and choose Compare two models for shared colour scales and a B − A map. Only identical rectilinear coordinates are accepted; no resampling is performed. Source mesh coordinates use metres and z elevation, positive up. They must not be read as depth below ground. Use Save to Project to keep the run in history.

Without a compatible 3D renderer the exported sections and data-fit figures remain viewable. Interactive coordinate-based sections also work without OpenGL when PyVista can read the exported grid. Original source files and model arrays are preserved; new products go only into the run’s directory.

Extension points#

Domain launchers can call qt_apps.launcher.main(argv, assistant="geosage") to choose their assistant explicitly after window construction. This works even when saved preferences select another assistant or QSettings cannot be written.

Assistant.offline_workflow defaults to False. Assistants may opt in when their workflow can provide useful results without model access; the dedicated button sends no provider key, model or retrieval settings. It does not change the behavior of existing assistants.

A VTK artifact can supply metadata.scalar_cmaps, a mapping from scalar names to Matplotlib colour-map names. The volume viewer uses it as per-field defaults while respecting user-selected maps. Numeric fields ending in " ID" use categorical colours with compact positions for non-contiguous labels. Dataset arrays are not rewritten for display.

needs_review is preserved in run history and filters. It denotes a completed computation whose interpretation still requires review; incomplete denotes an unfinished workflow.

See the GeoSAGE checkout’s docs/studio.md for input schemas, installation constraints, scientific display conventions and the optional regression suite.

Optional task setup and focused workspace#

Assistant.workflow_setup is an optional lazy module:factory reference. It is loaded only by the Qt workflow page, so discovery and headless execution remain independent of Qt. The factory receives a parent widget and returns a QWidget with:

  • a changed signal and needs_ai, action_label and primary_role properties;

  • allowed_roles() and update_inputs(inputs) for task-specific inputs;

  • request() for the task objective;

  • prepare_payload(payload) returning a validated payload without writing files. It is called before allocating a run, then again with the actual destination;

  • optional show_error(message) for an inline validation message;

  • optional show_configuration(payload) to display the inputs and settings passed at launch. A prepared payload may provide run_label for history.

Assistant.retrieval defaults to ("rag", "mcp"); unsupported controls are hidden and cannot enter a payload. focused_workspace=True starts with the assistant and log docks hidden and navigation focused on tasks and saved results. Toolbar Assistant and View → Show all processing tools restore those controls. All three capabilities are optional, preserving the existing AQUAH experience.

VTK artifacts may set metadata.linked_sections=True and metadata.field_metadata keyed by cell-field name. Fields may supply numeric limits and units, or category colors / names keyed by string IDs. Shared limits and category colours apply to 3D and linked orthogonal sections. Run results may supply completion with numerical, interpretation and review states; the workflow displays them separately from run status.

An optional setup method prepare_continuation(result) may return a new input role dictionary and select the next task. A result with a nonempty continuation then exposes Interpret these models…. The host applies the inputs and opens task setup; it never starts a worker or contacts an AI provider from this action. Errors remain inline, and the action is disabled when the original run is absent from the current Project. Assistants without the method retain their existing behavior.

GeoSAGE writes a local studio_checkpoint.json after each completed stage and a continue_config.json when completed numerical models are reusable. These support continuing interpretation in a fresh run without repeating inversion; they are not solver-iteration checkpoints.

Desktop regression checks#

With desktop dependencies and the GeoSAGE plugin installed, run:

python -m pytest tests/test_agents.py tests/test_core.py

test_agents.py runs the installed plug-in on the studio contract (skipped without GeoSAGE), and test_core.py checks the model comparison’s differences (skipped without PySide6 and PyVista), on Qt’s offscreen platform with synthetic temporary inputs. Windows native folder dialogs and GPU composition also require an interactive check: open a model, switch between figures and reports, accept and cancel a Project folder dialog, and return to the model. The model viewer retains its OpenGL widget across these transitions. An offscreen render alone cannot detect a black top-level window caused by native composition.