Agent Workflow: folders, references and MCP ================================================================================ One place to ask, one place to inspect -------------------------------------------------------------------------------- Use AQUAH on the right for the goal, provider, model and API key. Send the goal and choose **Auto to report**. In the central Workflow page, choose a data folder or add individual files. Folder selection is local: files are not moved or copied. When you send the goal, the worker scans the folder and sends filenames and short text previews to the selected AI provider for classification. Binary file content is not decoded for classification. API usage may incur charges. The editable classification table shows each file, suggested role, confidence and evidence. Review these suggestions and send **continue** in AQUAH. Assign unknown files a role or Ignore. Confidence is an AI estimate, not a calibrated probability. If the model cannot be reached, or its answer still cannot be read after one retry, the files it did not classify stay unknown with the reason. Roles read from the files themselves are kept, and the scan is not lost. Multiple surveys are not silently assumed to be time-lapse data. Arrange time-lapse files chronologically with the up/down controls after roles have been applied. Manual file selection remains available. Scans are limited to 300 supported files, 2 KiB read per text preview, and 1200 characters sent per preview. Hidden, credential-named, linked files and common generated-output directories are skipped. A truncated scan produces a warning: select a smaller data folder to include the remaining files. Coordinates and terrain -------------------------------------------------------------------------------- The classifier distinguishes measurements, electrode coordinates, geophone coordinates, independent terrain and reference documents. A file being classified does not imply every workflow can consume it. * ERT uses the existing ``electrode_file`` loader for electrode geometry, including elevations. A coordinate table with one evenly spaced row for each electrode an ERT survey beside it uses is that survey's electrode file. This is read from the files themselves (the survey's electrode count, the table's rows and spacing), before the model is asked, and also when such a table reaches a run labelled as terrain. Any other DEM/XYZ terrain is left out of an ERT run with a note in the run's record, rather than stopping it. The assistant reads the note and can carry on, ask you, or propose a temporary script for you to approve. Prepare such terrain in the mesh workflow. * Raw SEG-Y accepts ``geophone_file`` with exactly three numeric columns: ``receiver_id x z`` (the optional header must use those names). IDs must match the SEG-Y receiver IDs; row order is not used to guess station identity. * Raw SEG-Y also accepts ``topography_file`` with exactly two numeric columns: ``x z``. Elevations are interpolated at source/receiver x before travel-time export. Coordinates must share units and datum; missing IDs, duplicate profile x values, nonfinite values and out-of-profile points cause an error. * Existing travel-time files must already contain their sensor geometry; a geophone file given with them is left out with a note. GeoTIFF/3D XYZ terrain is recognized as a possible input but is not supported by this two-dimensional automatic profile adapter. Model and reasoning -------------------------------------------------------------------------------- Local CLI login (no API key) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Qt assistant starts with **Codex CLI (ChatGPT login)** by default. You can choose **Claude Code CLI (local login)** or an API provider in settings. Setup runs automatically in the background: the studio finds an existing installation (including common installations not on PATH) or downloads the official native CLI into its own user data directory. Downloads are verified against the publisher's SHA-256 checksum before use. No administrator privileges, Node.js installation or PATH edits are needed. If you are already signed in with a subscription, chat becomes ready. Otherwise, click **Log in** and complete the official sign-in in your browser; the studio checks the saved login and enables chat when you return. The sign-in status line carries one small button for what fits the state: **Log in** when signed out, **Log out** when signed in (to use another account, log out, then log in), **Cancel** during an unfinished sign-in and **Retry** after a failed download or installation check. **Log out** asks first, because it signs the CLI out on the whole computer, also where you use it in a terminal. The button is disabled during active chat or workflow runs. The API key and Apply controls are hidden. Your account must include access to that CLI; subscription usage limits still apply. The studio does not copy login tokens or turn a subscription into an API key. Advanced configuration is optional: ``PHGX_CODEX_CLI`` or ``PHGX_CLAUDE_CLI`` can point at a custom executable, and ``PHGX_CLI_DIR`` can change the managed installation directory. Standard npm launchers on Windows are supported when Node.js and the package's JavaScript entry point are installed together. On Windows the default managed directory is ``%LOCALAPPDATA%/PyHydroGeophysX/cli``; macOS uses Application Support and Linux uses XDG_DATA_HOME (or ``~/.local/share``). After Codex sign-in, the studio reads the CLI's visible model catalog in the background and fills the Model dropdown. It refreshes the list after signing in again. The options follow the installed CLI and its account configuration. If discovery fails (for example, with an older CLI or a timeout), login stays ready and the previous list remains usable. On a first run without a catalog, ``default`` and manually entered model IDs are still available. Discovery uses the same native or npm launcher as model requests on Windows, macOS and Linux. The model value ``default`` leaves selection to the CLI; choose another entry or enter a model ID to override it. ``PHGX_CODEX_MODEL`` and ``PHGX_CLAUDE_MODEL`` can set the initial model. Codex receives the Reasoning setting; Claude Code uses its own defaults. Both step-by-step assistance and AQUAH's **Auto to report** support CLI access, including folder classification. Both also run on an OpenAI-compatible endpoint (for example a vLLM server): the Base URL entered in Assistant settings, or ``OPENAI_COMPAT_BASE_URL``, reaches every agent of the run. Proposed studio actions follow the existing approval and execution mode. This initial bridge supports text and structured studio state; screenshot analysis is available with the API providers. Each call sends the current bounded conversation to the CLI through stdin, and the CLI contacts its model service. A missing login, exhausted quota or invalid model is reported by the CLI. ``PHGX_LLM_TIMEOUT_S`` controls the request timeout (120 seconds by default). See `Codex non-interactive mode `_ and `Claude Code CLI reference `_. API models ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The default OpenAI model is ``gpt-5.6-luna`` (an explicit ``OPENAI_MODEL`` environment setting still overrides the default). The Reasoning selector defaults to ``medium`` and offers ``none``, ``low``, ``medium``, ``high``, ``xhigh`` and ``max``. Reasoning options are sent only to supported OpenAI reasoning-model requests; legacy models retain their usual parameters. Provider access is account-dependent. See `OpenAI's GPT-5.6 Luna model documentation `_. Progress displays actual backend stages and logs, along with elapsed time. It does not fabricate activity or expose private model chain-of-thought. Stop terminates the worker; inputs and partial outputs remain available for retry. RAG: give the AI reference material -------------------------------------------------------------------------------- **RAG · consult local references** retrieves text excerpts from repository documentation (when available) and selected reference files. This initial implementation uses bounded lexical retrieval, not a vector database or internet search. Supported reference formats are Markdown, reStructuredText and plain text. PDF/Word references need text extraction before retrieval. A wheel installed without repository docs can still use explicitly selected reference text files. Sources, line numbers and excerpts are saved with the report. Retrieved passages are reference data, not executable instructions. The relevant excerpts are sent to the selected AI provider. If no matching passages are found, the report says so. MCP: expose existing project functions -------------------------------------------------------------------------------- Install the optional SDK (Python 3.10 or newer): .. code-block:: bash python -m pip install "pyhydrogeophysx[mcp]" python -m PyHydroGeophysX.mcp_server --root /path/to/project The standard stdio MCP server exposes: * ``list_workflows``: registered ERT, seismic, EM, hydrology and other workflows. * ``scan_data_folder``: bounded local inventory under the configured root. * ``search_docs``: reference excerpts with source locations. * ``validate_recipe``: validation of an existing workflow JSON recipe. * ``run_recipe``: enabled only when the server owner starts with ``--allow-run``; executes an existing trusted recipe through the isolated workflow CLI and saves results and logs into a unique ``mcp_runs`` directory. The root scopes inventory and recipe-file selection. It is not an operating system sandbox: execution-enabled clients and recipe contents must be trusted, and referenced input files follow the workflow engine's normal access rules. Do not expose this local server to unauthenticated remote clients. An example MCP client configuration (use an absolute Python executable path): .. code-block:: json { "mcpServers": { "pyhydrogeophysx": { "command": "/path/to/environment/bin/python", "args": ["-m", "PyHydroGeophysX.mcp_server", "--root", "/path/to/project"] } } } On Windows, use the environment's ``python.exe`` and escaped backslashes or forward slashes in JSON paths. Add ``--allow-run`` only when you want the client to execute trusted project recipes. Existing recipes come from Studio workflow exports; MCP does not provide arbitrary Python or shell execution tools. The desktop **MCP · connect local tool catalog** option performs a real MCP stdio connection and reads available workflow APIs into the agent's context. The unified desktop pipeline still computes through its existing engine; this option does not route every numerical function call through MCP or connect arbitrary remote servers. See the `official MCP Python SDK `_. Reports and uncertainty -------------------------------------------------------------------------------- OpenAI reasoning models use the Responses API for AQUAH function tools, retaining reasoning state between tool results. This avoids the Luna Chat Completions restriction on combining function tools with reasoning. OpenAI-compatible third-party providers continue to use their Chat Completions endpoint. Follow-up messages refine the current goal, including after folder classification. Use **New chat** to start a new goal while retaining selected files. The ``max_attempts`` setting counts the initial evaluation; ``1`` disables retries. ``auto_adjust: false`` evaluates the supplied settings without optimizing them. Solver ``max_iterations`` is a separate limit. Reports and the workspace display **Needs review** if quality criteria are unmet even when computation completes. Quality scores are heuristic diagnostics, not calibrated confidence levels. Reciprocal ERT measurements are optional. When pairing is missing or incomplete, the default export uses the full loaded dataset with source or estimated errors. Missing reciprocal errors do not fail quality control; measured reciprocal errors above the configured threshold can still be filtered. Every successful automatic computation writes ``detailed_report.md`` and ``processing_audit.json``, along with the original engine reports and numerical outputs. The detailed report includes input names/paths and SHA-256 hashes, configuration, AI settings, recorded stages and elapsed times, observed Python function calls, software versions/project references, RAG sources and warnings. Reviewed file classifications are saved separately. Directory inputs are identified as directories; individual consumed files require the backend log. Runtime tracing covers Python calls in the worker, not native internals or child processes, and is capped at 2000 distinct function names with a truncation flag. Package references are obtained from installed distribution metadata; missing metadata is reported rather than invented. Original HTML/PDF engine reports remain unchanged; the full audit is in the detailed Markdown/JSON outputs. The uncertainty section distinguishes measured fit from confidence. It identifies data noise and missing observations, geometry and first-break errors, mesh and regularization choices, nonuniqueness, petrophysical assumptions and AI limitations. Confidence intervals or ensemble validation are not claimed unless the executed workflow actually computed them.