32Human and agent interfaces

The same science needs more than one front door

A scientist comfortable with Python can construct objects and call algorithms directly. Another researcher may prefer repeatable shell commands. An AI assistant needs structured operations it can discover, call, and interpret. A colleague reviewing an active space may learn more from orbital pictures than from a coefficient matrix.

QDK Chemistry serves these situations through the command-line interface, the MCP server, project-based artifact management, visualization tools, and a Copilot plugin. They are not different physical theories. They are different ways to access and coordinate the scientific machinery we have already studied.

The key engineering principle is to make a tool invocation traceable to actual inputs and outputs. A friendly assistant response is not itself an SCF calculation. A rendered circuit is not proof that it executed. A file named after a molecule is not a complete description of its charge, spin, and approximation choices.

The AI-assistant guide introduces these interfaces. This lesson follows their implementations so we can distinguish convenient presentation from guarantees the code actually makes.

1. Python, the CLI, and MCP have related but different contracts

A command-line interface, or CLI, exposes operations as commands entered in a terminal. QDK Chemistry installs the executable qc. A command parses text arguments, calls the relevant implementation, and prints a result that a human or another program can inspect.

MCP, the Model Context Protocol, gives an AI client a structured way to discover and invoke tools exposed by a server. The server advertises tool names, parameter schemas, and descriptions. The client supplies structured arguments rather than inventing a Python call from scratch.

A schema describes expected input fields and types. A transport describes how requests and responses move between the client and server. Neither chooses the scientifically appropriate basis, active space, or energy accuracy on its own.

The shared tools module contains many operations used by both CLI handlers and MCP registration. Most file-producing tools load named artifacts, create a selected algorithm, apply settings, run it, and save declared outputs. They expose an artifact workflow rather than passing arbitrary Python objects through the assistant conversation.

There is still a difference between the Python algorithm API and these tool wrappers. The wrapper catalog is finite, its accepted arguments are explicit, and not every newly registered algorithm type automatically gets an entirely new CLI command or assistant tool. Plugins can extend supported implementations behind an existing interface; exposing a new kind of task may require a wrapper as well.

2. Discover the actual operations before choosing settings

The tool catalog is organized around the scientific journey:

list_algorithms reports implementations that are actually registered. describe_algorithm exposes their setting schema. get_algorithm_default_type and get_algorithm_default_settings report defaults. describe_backend explains available remote/cache backend configuration, including what an MCP client may change.

The server deliberately exposes compact operation descriptions. Detailed usage knowledge is provided separately in the MCP skill and reference. Compact descriptions reduce catalog overhead, but they do not contain every scientific caveat. A capable assistant must use both the schema and the domain guidance, and still preserve the scientific requirements stated by the user.

The catalog checks enumerate the reviewed tool names and optional visualizers. Installed optional dependencies affect the live catalog, so a static tool count is less useful than discovery in the actual environment.

3. Bind an assistant process to the intended workspace

A plugin-launched MCP process may start in the installed plugin directory, not in the folder containing the scientist data. Resolving relative filenames against that accidental working directory would be a serious workflow mistake.

The workspace binding mechanism therefore binds one process to one explicit absolute workspace. It can use a single file root supplied by the MCP client or an explicit workspace_root argument to bind_workspace.

The packaged MCP configuration sets QDK_REQUIRE_WORKSPACE_BINDING=1. Its middleware rejects workspace-dependent operations until binding succeeds, unless it can safely discover the one required client root. Middleware is a layer that checks a request before passing it to the actual tool.

Once bound, the process cannot be rebound to a different workspace. A different workspace needs another process. Repeating the same binding is acceptable, but rebinding for every tool call is unnecessary.

Binding establishes default projects, cache, and jobs storage beneath the workspace, subject to the explicit cache/job environment overrides. It does not change the global process working directory. Project-specific contexts supply the correct resolved paths for individual operations.

This matters when two requests or projects coexist: one request should not redirect another by changing a process-wide current directory. The workspace tests express that invariant directly.

Binding is not read-only. It can create the required storage directories. Importing the UI configuration also initializes storage. Consequently, even a command intended only for inspection should not be assumed to have zero filesystem side effects merely because it does not run chemistry.

4. A project is a namespace for artifacts, not a physical model

The UI project directory contains files such as structures, orbitals, wavefunctions, Hamiltonians, circuits, and results. A project name groups them for tool access; it does not set a molecular charge or select a scientific method.

The validation layer requires a suitable single-component project name and verifies that resolved files stay inside the intended project. It handles both Windows and POSIX path conventions, rejects parent traversal and inappropriate absolute paths, and checks where symlinks resolve. Some tools accept nested paths explicitly, while others strip supplied directories and work with basenames.

Those policies make filename handling more predictable. They are not a complete general-purpose operating-system sandbox or cloud authorization scheme.

The type marker in a filename remains important. Helpers can insert the expected marker for an output name, but a downstream tool still needs the returned actual filename rather than an assumed spelling. A wrapper may return a file or an energy plus filename; the exact tool schema and result must be read.

For our nitrogen calculation, the structure-construction tool expects coordinates in bohr. Its coordinates_json input is a JSON string representing a nested array with one three-component row per atom. It checks the shape against the element list and the optional mass/charge array lengths. The implementation explicitly directs callers with ångström data toward convert_coordinates.

This differs from Structure.from_xyz, which interprets XYZ coordinates in ångströms. An assistant must not copy numbers between those entry points without the corresponding conversion.

5. Trace one tool call all the way to a saved result

The run_scf tool accepts a project, a structure filename, an output wavefunction filename, charge, spin multiplicity, basis name, and optional implementation/settings/execution controls.

Its flow is concrete:

1. Resolve and check the output filename.
2. Load the structure using the expected data class.
3. Create the requested scf_solver implementation.
4. Apply its settings, including nested references where supported.
5. Execute through the common local/cache/remote helper.
6. Save the wavefunction and return the energy with the filename.

The wrapper is not a second Hartree–Fock implementation. It coordinates the same algorithm contract we examined earlier.

Existing output handling is a separate decision. If the requested output already contains valid data and overwrite is false, the tool reports an exists status. This protects against accidentally replacing an expensive artifact.

However, an existing valid wavefunction at a filename is not proof that it came from the newly requested geometry and settings. File-existence protection and content-identity caching are different mechanisms. Before accepting an old output, inspect its provenance. Before overriding it, decide whether the original should be retained under a distinct name.

On the common execution path, overwrite=True is also forwarded as a force-rerun request for caching. It can therefore do more than permit replacing a file: it can cause expensive numerical work to be repeated.

6. Status envelopes are part of scientific correctness

The structured wrapper converts most ordinary tool results into an envelope:

The bind_workspace result has its own bound confirmation, and visualization tools use MCP App result structures with text fallbacks. It is therefore more accurate to inspect each contract than to claim every server operation returns an identical envelope.

For remote work, the common tool helper starts the response-wait window only after a durable job handle has been recorded. If the calculation finishes within remote_timeout, the tool can return the normal result. Otherwise it returns submission metadata, and the caller can use check_remote_job and retrieve_remote_results later. A backend-raised timeout remains an actual error rather than being mislabeled as ordinary successful submission.

A submitted job identifier is not an energy. An exists response is not a newly calculated result. An exception converted into a JSON error is still a failure, even if the transport request itself succeeded.

The CLI has its own presentation formatter, so do not assume its displayed wrapper is byte-for-byte identical to the MCP result. Workflow automation should inspect documented status information rather than search for a reassuring word in a text message.

7. The current CLI is grouped, despite an older flat-command header

The actual argument parser organizes commands into groups:

qc run scf ...
qc data summary ...
qc config algorithms
qc project list
qc util convert-energy ...
qc workflow ...
qc describe ...
qc plugin ...

Some older docstrings still show flat names such as qc run-scf. The current create_parser implementation is the reliable guide for this revision.

An explicit SCF command uses --project-name, --structure-filename, --out-wavefunction-filename, --charge, --spin-multiplicity, and --basis-set, with optional implementation and JSON settings. Help text can also retain stale descriptions of defaults; the algorithm registry determines the actual default implementation.

Compound workflows support a JSON configuration file and --set key.path=value overrides. A dotted path identifies a value inside nested configuration records. Values are parsed as JSON when possible, so a numeric value, boolean, and string need not be confused. This supports configuring the child algorithms inside a larger procedure without editing Python code.

qc --dry-run ... previews parameters without invoking the requested calculation. A workflow dry run additionally checks known commands, required arguments, and filename references. It is not a proof of valid chemistry, available dependencies, converged algorithms, or side-effect-free module initialization.

The CLI workflow command runs a sequence of supported steps. References such as $prev, $prev.1, and $step.3 connect declared output filenames from previous steps. These are workflow reference strings, not shell variables in this context. The implementation recognizes a finite set of workflow operations, not arbitrary Python expressions.

Dry-run validation can identify unresolved references or an input that must already exist. Actual execution stops on an explicit error envelope. It does not make all stages one atomic transaction: earlier results can remain after a later stage fails. The caller must also account for statuses such as exists and submitted rather than treating every non-error return as ready input to the next numerical step.

8. Installable skills supply guidance; the server supplies capabilities

The Copilot plugin combines two kinds of material.

Skills are readable domain guidance: explanations of tool contracts, method-selection considerations, remote execution, visualization, resource estimation, and coding patterns. They help an assistant choose and use tools.

The MCP server configuration tells the client how to launch the executable that actually performs supported operations.

A skill file does not install a scientific dependency or grant permission to a remote service. Conversely, an available server can expose a method whose safe scientific use requires more knowledge than its short description contains.

The plugin installer integrates with Copilot plugin installation and binds the MCP command to the intended Python environment. A virtual environment is an isolated Python installation context used to keep package dependencies separate from unrelated projects.

For a user-scoped installation, the fetched plugin is maintained in the corresponding Copilot scope and its command is bound to the selected environment. With --target-dir, the installer deploys skills and relevant configuration into that workspace, including .vscode/mcp.json and .github/mcp.json, and records fetch/binding state under .qdk_chem.

The two configuration files use their respective expected top-level server keys. The installer merges server information instead of treating them as identical formats. Local plugin directories, marketplace specifications, and supported repository subdirectory specifications have different resolution paths.

Updates can refresh plugin files and disturb the command binding unless it is restored. The qc plugin update and qc plugin rebind paths preserve or re-establish the intended executable relationship. A stale binding to an environment that no longer exists is an operational error, not evidence that a chemistry method is unavailable in principle.

These installation operations change configuration and files. They are described here, not performed on the source repository or a reader workspace.

9. MCP is optional, and transport choices do not add scientific authority

The optional integration module preserves shared CLI functions when the MCP dependency is absent. Installing the MCP extra enables actual server registration and the available visualization resources.

The executable qcmcp starts the server. The entry point supports standard input/output, streamable HTTP, and server-sent-events transport. Standard input/output connects directly to a client process. HTTP transports communicate through a listening endpoint; the default host is loopback, 127.0.0.1, and the default port is 8081.

Compatibility switches can remove output-schema/UI metadata for older hosts, use sessionless HTTP, return JSON rather than event-stream framing, or relax an HTTP Accept-header requirement. They address protocol compatibility. They do not provide authentication, safe internet deployment, scientific correctness, or quantum hardware access by themselves.

Changing the server to listen beyond the local machine is an operational deployment decision. Network exposure, authorization, filesystem permissions, and secret handling need their own controls. The fact that a client speaks MCP does not make every requested action scientifically appropriate or authorized.

10. Visualize actual artifacts and state what the picture means

The visualization module registers interactive MCP App resources when the required widget package is available. An MCP App is a view the host can render alongside a tool result. A host without that support may receive the structured/text data without displaying the interactive widget.

The available views serve different questions:

• visualize_molecule displays the saved nuclear geometry.
• visualize_orbitals evaluates selected orbital fields and displays isosurfaces with the molecule.
• visualize_orbital_entanglement displays the available entropy and mutual-information data using orbital labels.
• visualize_circuit converts a saved circuit into the widget-compatible representation.
• visualize_scatter_plot renders caller-supplied numerical series, with labels and optional logarithmic axes.

The molecular and orbital widgets are supplied by the broader QDK widget package. Chemistry supplies structures, basis coefficients, and grid data. The local scatter renderer builds an SVG plot from supplied numbers. It is a presentation tool, not a computation of those numbers.

Orbital visualization needs basis and coefficient information. Entanglement visualization needs the relevant reduced-density/entropy information; it does not generally run a missing correlated calculation on behalf of the viewer. Its selected-index mapping converts absolute orbital labels into the positions used by the chart, avoiding the common mistake of confusing active-space position zero with molecular orbital zero.

The circuit viewer obtains QASM and converts it through the QDK circuit representation. A Circuit object that lacks a supported route to that representation can fail to render. A diagram is therefore one view of an available circuit, not a universal serialization of all its executable behavior or physical cost.

Orbital views do not change the stored wavefunction, but evaluating cube data can allocate substantial memory and use temporary files through the convenience helper. More grid points can improve the picture while increasing cost; a prettier surface does not validate the basis or correlation model.

A scatter plot can help compare resource frontiers or energy curves, but it does not verify axis units, matched scientific models, or whether the supplied points came from valid calculations. The person or workflow producing the series retains that responsibility.

11. The assistant should preserve decisions, not hide them

An assistant can make the workflow more accessible: discover methods, construct typed inputs, call a solver, inspect a result, display orbitals, and keep track of remote jobs. The danger is collapsing this into a story that sounds successful while losing the actual choices.

A good assistant-mediated nitrogen workflow still records the geometry and units, charge and spin, basis, implementation and settings, convergence/stability evidence, selected model space, energy constants, qubit encoding, actual execution result, and any resource assumptions. It reports missing prerequisites or unsupported combinations. It does not invent an energy when a tool returns an error or label a queued job as a completed calculation.

The user-interface workstream therefore connects domain expertise, reliable software contracts, readable error/status information, and useful visual explanations. Its value is not that the scientist can forget the scientific model. Its value is that the mechanics become easier to operate while the model and evidence remain visible.

The next lesson looks underneath these interfaces at the build, dependency, testing, and release work that makes the whole package available and maintainable.