AI research assistant — PF Simulation r34

The AI research assistant opens from a completed simulation run. It can inspect retained scientific inputs, outputs, logs and source, accept attachments, and propose private source-code corrections. A correction is an ordered layer over an immutable core release. It never changes the shared PF installation.

Windows standalone setup

Use a long-path-capable ZIP extractor for the complete release. Retained historical evidence includes relative paths longer than Windows' traditional 260-character limit, even before the destination folder is added. A short installation folder helps but does not resolve that limit by itself. Enable Windows long-path support for Python 3.12 when retaining or reproducing the complete evidence; extraction software must also support long paths. Preserve the recorded filenames and folder structure. See Python's Windows instructions and Microsoft's long-path requirements.

1. Extract this release into a new folder. Keep earlier releases and their runs.
2. Use the 64-bit Python 3.12 research workbench. Run setup_research_worker.bat for a new installation. Its requirements now include the assistant's database and PDF-reading dependencies.
3. Run configure_ai_research_assistant.bat to select an available model and enter credentials. For an existing research environment that needs only the new dependencies, run setup_ai_research_assistant.bat instead.
4. Launch Launch_PF_Research.bat, complete a simulation, select its run, and open AI research assistant. The same workbench is launched by PF_Simulation_GUI.pyw, which now prefers an installed .venv_research over legacy environments. An explicit PF_RESEARCH_PYTHON setting takes precedence. Choosing a Python manually keeps that interpreter for dependency installation, the GUI and scientific workers.

The assistant does not include an AI model subscription, API key, downloaded model weights, or a Docker runtime. Setup records configuration; it does not claim that an account has access to the selected model. Restart the workbench when configuration changes. Use Check environment to confirm the GUI executable, Python version and assistant dependency imports. The assistant status also distinguishes missing dependencies from missing model configuration.

The configuration wizard stores settings in the current OS user's profile: %LOCALAPPDATA%\PFSimulation\ai_research_assistant.json on Windows, or $XDG_CONFIG_HOME/PFSimulation/ai_research_assistant.json (default ~/.config/PFSimulation/...) on Linux. The credential is a secret stored in that file: do not include it in shared reports or package archives. Environment settings override the file. Hosted services do not automatically read a local workbench user's profile. Set PF_AI_CONFIG_FILE to an absolute, administrator-managed JSON file to configure a hosted provider and executor together; process environment values take precedence. Credential files must have owner-only permissions on POSIX systems.

Ordinary scientific runs and the existing research APIs remain available without a model connection. Missing model configuration produces an explicit unavailable state, never a canned answer presented as an AI investigation. Chat itself does not require WSL. Executing generated code requires the separate configured sandbox described below. The existing native Einstein Toolkit, MATLAB, Simulink and instrument prerequisites still apply to those backends.

Investigating a run

The conversation binds to an exact completed execution attempt. In SaaS, choose the desired attempt before opening it. A retry or later simulation does not replace the conversation's original evidence.

Useful requests include:

• “Explain this fidelity difference and identify the arrays and assumptions that determine it.”
• “Compare the recorded clock integrals with this attached table. Keep numerical agreement separate from experimental accuracy.”
• “Reproduce the discrepancy in this run and propose a correction if it is an implementation defect.”
• “Show the code and evidence behind this conclusion, including its limits.”

The assistant retrieves data through bounded tools. It does not load every array and source file into a model prompt at once. References in tool records identify their source scope, path and byte hash. An answer is still a model interpretation; the evidence and numerical checks remain available for review.

Attach text, JSON, CSV, supported numerical arrays, PDFs or images. Attachments are private evidence, not instructions that can authorize code execution or change validation rules. PDF extraction reads text; it does not establish that scanned pages, equations represented as images or every figure were understood. Image inputs require an image-capable configured model and explicit image-input configuration. Unsupported content is identified rather than silently treated as parsed. Large artifacts are inspected in bounded excerpts; upload, snapshot and execution limits are reported by the service.

With a remote model, the selected evidence excerpts and enabled image inputs are transmitted to that provider. An operator can instead configure a local OpenAI-compatible endpoint that supports the required tool-calling protocol. Model capability and data-handling arrangements belong to that deployment.

Proposing and using personal layers

1. Ask the assistant to inspect the relevant source and propose a correction.
2. Inspect the proposed files, code diff, rationale and classification: bug fix, model change, or exploratory.
3. Select Validate. The configured executor materializes the exact parent stack and candidate stack in separate private workspaces, executes the saved scientific workflow, and runs the fixed reference suite.
4. Review the validation report, numerical comparison and available plots.
5. Activate only a passing, intact candidate. Activation records a new private profile revision. A changed parent stack requires a new proposal/revalidation.
6. Use the active profile to rerun the disputed case or select Use my active overrides when starting a newly configured run.

A private result records the core identity, ordered layer identities, effective source hash, input identities, configured runtime identity, validation record and actual execution outcome. The original run remains unchanged. Private results and their downloadable evidence are shown inside the assistant.

Layers can replace existing editable scientific Python files. This release does not permit layers to edit authentication, quotas, installers, provider clients, validation orchestration, acceptance tests, expected reference data, deployment configuration or dependency requirement files. New dependencies require an operator-built, pinned executor image followed by revalidation. Source fixes do not install licensed software or create missing experimental observations.

A successful reference suite supports its declared cases only. A proposed scientific-model change is not automatically a bug fix; successful execution is not proof that the new model is physically correct. The assistant must preserve that distinction in its rationale and reports.

Removing, deleting and upgrading layers

Removing an active layer creates another profile revision. Later layers may depend on it; the interface requires removal of dependent layers or an explicit rebase and new validation. It never silently combines incompatible source edits.

Archiving/removing from the active stack preserves code needed by historical run records. Permanent deletion removes the layer's stored source edits and marks historical stacks that need them as no longer reconstructible. Original outputs remain historical records. Separately retained chat, attachments or exported files have their own copies; deleting a layer is not a promise to erase its text from every separately retained artifact.

A core release upgrade changes the base identity. Layers are not silently transferred onto a different release. Retain the prior installation for historical studies, then propose/rebase and revalidate against the new core.

Source and input provenance

New regular standalone and SaaS runs record assistant_provenance.json inside the actual scientific interpreter or container. It includes source identities, Python/package versions and before/after source and declared-input checks. Credentials and arbitrary environment-variable values are excluded.

Older runs can still be discussed. If their execution source is unknown or no longer matches a retained base, the assistant identifies that limitation and blocks a claimed corrective replay. Rerun the original configuration with this release to establish a new recorded baseline. Changed or missing external input files are also not silently substituted for the historical data.

The recorded package versions help reconstruct a Python environment. They do not fully specify native libraries, operating systems, hardware, licenses or external services. Container image identities and native integration provenance must be retained where those components affect reproducibility.

Model configuration

Supported providers are OpenAI Responses, OpenAI-compatible Chat Completions, DeepSeek, native Google Gemini generateContent and native Anthropic/Claude Messages. See R33_AI_PROVIDERS_GUIDE.md for selection, default endpoints, configuration and protocol scope. Generic compatible servers must implement the required tool protocol.

HTTPS is required for remote endpoints. Plain HTTP is accepted only for an explicitly configured loopback endpoint. Credentialed redirects are rejected. The browser cannot select provider URLs, pass a shell command or retrieve API credentials. Model errors and partial tool activity remain distinguishable from a completed response.

Private code execution

Build the separate dependency image from the package root on a machine with Docker available:

docker build -f Dockerfile.assistant -t pf-ai-research-assistant:r34 .

Configure PF_AI_DOCKER_IMAGE=pf-ai-research-assistant:r34, or select that image in the local configuration wizard. The executor resolves the actual local image identity for each run and records it. Revalidate layers after runtime changes. Do not mount a Docker socket or service credentials inside a scientific job.

The job container has a read-only source tree and root filesystem, no network, no added capabilities, a nonroot user and bounded CPU, memory, processes, files and wall time. Only its own output workspace is writable. An optional PF_AI_DOCKER_RUNTIME can select an administrator-installed runtime such as runsc; installation and deployment tests are separate.

Additional settings include PF_AI_EXECUTION_TIMEOUT_SECONDS, PF_AI_MEMORY_MIB and PF_AI_MAX_OUTPUT_BYTES. There is no automatic fallback to running AI-generated code directly on the host. A developer-only test constructor executes authored test fixtures locally and is never exposed through the web interface or model tools.

No-network execution requires captured inputs. Live tracking downloads and license-server-dependent operations may need an independently designed operator-managed backend; this executor does not silently broaden network access. The bundled Dockerfile installs Python research dependencies, not a native Cactus solver, proprietary MATLAB installation or hardware SDK license.

SaaS deployment

The SaaS adapter uses the existing authenticated session, CSRF protections and project permissions, then adds a strict private owner scope for user, organization and project. Another member or administrator of the same organization does not inherit access to a user's assistant sessions or layers. The owner is derived server-side; it is never accepted from a message or upload.

Metadata uses the configured SQLAlchemy database. Production requires the existing PostgreSQL deployment plus an explicitly configured durable shared assistant state directory visible at the same path to all serving replicas:

PF_SAAS_ASSISTANT_ENABLED=true
PF_SAAS_ASSISTANT_SHARED_STATE=true
PF_SAAS_ASSISTANT_STATE_DIR=/srv/pf-assistant
PF_AI_PROVIDER=openai
PF_AI_MODEL=<your available model identifier>
PF_AI_DOCKER_IMAGE=pf-ai-research-assistant:r34

Inject PF_AI_API_KEY through the deployment's secret mechanism. Do not put it in the scientific image, frontend bundle, user request or release archive. Run python -m pf_saas init to apply the additive version-2 database migration before serving production traffic. Assistant metadata tables (ai_ra_*) and usage records are additive. Back up metadata and assistant state together. The existing SaaS object store remains the source of committed original run artifacts; opening an assistant session creates a separately retained private investigation copy.

The API performs blocking provider/execution work in its threadpool with bounded execution and per-profile serialization. This release does not provide a separately distributed assistant queue, streaming token responses or a production deployment certification. Configure service request timeouts for the selected operation bounds. Assistant scientific executions share organization compute, storage and concurrent execution allowances with ordinary jobs. Model requests also have a separate PF_SAAS_ASSISTANT_MONTHLY_MESSAGES cap (default 1,000 per organization per month). Recorded provider tokens and external provider charges are distinct from the service's wall-time accounting; this is not a dollar spending guarantee.

After a service crash, reservations remain held. An operator can list them with python -m pf_saas assistant-operations. Stop any associated request processes and containers, then use python -m pf_saas assistant-reconcile --operation <id> --confirm-stopped. Reconciliation checks the owner lease, conservatively charges reserved compute and refreshes retained storage. It is not exposed as an end-user endpoint.

Validation scope

To execute release_tools/validate_r34_release.py execute, install the research and development Python test dependencies and ensure Node.js is available as node on PATH. Node.js runs the JavaScript interface behavior suites; it is not needed for ordinary workbench use or the retained-evidence verify command.

Read R34_VALIDATION_REPORT.md for the current executed evidence and limitations; R30_VALIDATION_REPORT.md retains the original subsystem's historical evidence. The trusted reference suite evaluates four Lorentz boosts, complex two-qubit state preservation, density-state rejection, three Gaussian mode-overlap cases, and short-time Minkowski/gauge-wave BSSN evolution and convergence. The original and candidate configured workflows are also executed.

Default evidence limits are 32 MiB per file, 256 MiB per captured run, 1 GiB retained evidence per private profile, and 4 MiB per attachment through the provided HTTP interfaces. Runs beyond these bounds are rejected explicitly; this release does not provide unlimited or streaming access to arbitrary-sized datasets. Service configuration can impose lower limits.

The suite does not reproduce an entire published numerical-relativity test campaign, prove every possible source edit correct, establish experimental accuracy, or substantiate stronger commercial claims. Its expected values and tolerances are controlled outside user-editable source. Each candidate has its own validation identity; r29 evidence is retained as historical evidence and is not relabeled as validation of arbitrary custom builds.

Primary implementation references:

• OpenAI function calling
• Docker security model
• Apples with Apples test specifications
• Apples with Apples revised comparisons

API protocol fixtures, numerical checks, source integrity and authorization tests answer different questions. Passing a protocol fixture is not a live model trial; passing a numerical test is not a container-isolation test.

r31 reliability update

See R31_AI_ASSISTANT_FIXES.md for the launcher repair, corrected assistant behavior, upgrade instructions and validation boundaries. The r31 evidence remains historical; the current release gate is release_tools/validate_r34_release.py.

r32 Windows and diagnostics update

See R32_AI_ASSISTANT_FIXES.md for canonical cross-platform source identities, Windows-to-Linux executor paths, persistent safe provider errors, setup settings preservation, hosted admission accounting and upgrade instructions. Earlier runs keep their original evidence; a fresh run with the current release is required when the original provenance cannot be verified. Native Windows and deployed sandbox execution remain separately qualified in R32_VALIDATION_REPORT.md.

r33 provider support

See R33_AI_PROVIDERS_GUIDE.md for DeepSeek, Gemini and Anthropic/Claude setup and supported assistant behavior. The same provider backend serves standalone and SaaS; provider credentials remain outside browser responses and private continuation remains account-scoped. R33_VALIDATION_REPORT.md identifies which protocols and scientific lifecycles were actually executed.

r34 bounded recovery and continuation

See R34_INVESTIGATION_RECOVERY_GUIDE.md for partial responses, a reserved conclusion opportunity, duplicate-tool protection and Continue investigation. A continuation restores a private, bounded checkpoint for the same provider, run evidence and active source/profile state. Each continuation requires an explicit action and a new bounded admission. Source-layer validation, activation and owner boundaries remain unchanged. Historical r33 failures cannot be resumed because that release did not retain investigation checkpoints.