r34 with personal AI keys

BYOK is optional for ordinary hosted simulation use. Follow the hosted trial guide to begin without configuring a personal provider. Native HF operators should use the native HF guide; Docker image and host-runtime directions in this guide apply to Linux/Docker deployments.

This guide covers personal AI credentials in the current r34 package, including private-workflow lifecycle controls and the current public-service revisions. It retains the existing Python source-overlay workflow. The current package identity and completed acceptance are in the r34 validation report.

Current hosted access and disclosure policy

The 24 September r34 adoption update applies organization/project access and AI disclosure policy to operator-managed providers and personal BYOK. Provider and endpoint permissions, administrator-assigned data classification, source disclosure and any required consent are checked before every outbound attempt, including retries and continued investigations. BYOK cannot bypass these controls. Disabling source disclosure blocks provider requests; it does not silently strip source from a request.

Existing installations retain the legacy default until configured. The new Linux reference uses institutional, initially disabling external AI and source disclosure. Administrators configure approved access; users review the disclosure and grant consent when required. Consent expires after 24 hours and is bound to the current user, project, policy, provider/model/endpoint and credential revision. Provider retention and data-location arrangements require institutional approval. See research policy and project confidentiality.

Research capabilities and source disclosure

The assistant can inspect permitted solver source, propose corrected Python files as private layers, show diffs, validate a candidate, explicitly activate it and execute later simulations using the user's active stack. Dependent stacks, removal, private attachments, pause/resume and derived research sessions retain the r34 mechanisms. Neither a model response nor a validation pass is automatic permission to activate a layer.

The installed shared engine remains unchanged by user layers. Execution uses a private materialized copy. The assistant can propose changes within its existing editable-path and execution rules; this does not promise arbitrary host access or that a proposed scientific correction is valid. An operator update is needed to make a correction part of the installed engine for everyone.

Relevant source excerpts can be sent to the user's selected AI provider. Layer contents, source tools and diffs can expose core implementation to that user. This release deliberately preserves that behavior. BYOK provides credential and billing separation; it does not make the shared implementation confidential. The full operator ZIP and the standalone source distribution also contain source.

Standalone continues using its existing operator/local provider configuration; the new personal-account controls are SaaS-only. Existing SaaS source sessions and Python layers keep their original namespace and format. r35 JavaScript layers are not converted into Python overlays by this release.

Personal account settings

With BYOK enabled, use AI research assistant → Your personal AI account to select OpenAI, an approved OpenAI-compatible endpoint, DeepSeek, Google Gemini or Anthropic/Claude; enter a model and personal API key, then save. Each user's credential applies across their projects. Their conversations, attachments and layer stacks remain scoped by user, organization and project.

Saving a key does not contact the provider or establish model access. The key is used when an admitted assistant request is sent. AI usage is associated with that provider account under its applicable access and usage rules. PF Simulation compute, storage and admission limits still apply independently.

When BYOK is enabled, missing, deleted, invalid or inaccessible personal credentials block AI requests without falling back to an operator key. Existing owned evidence and layers remain accessible under ordinary authorization. Key, model, provider or endpoint changes invalidate prior personal investigation checkpoints; start a new question with the updated account settings. Switching an operator-managed investigation to BYOK also requires a new investigation. Deleting a key prevents subsequent checked calls; it cannot undo a request already transmitted to the provider.

Keys are never returned by the settings API, including suffixes. The browser clears submitted keys and does not retain them in local or session storage. Credentials are encrypted at rest with AES-256-GCM and authenticated metadata binding the user, provider, model, endpoint and revision. Account status and credential revision are checked again before outbound calls and retries.

The API derives the owner from the authenticated account, never a user ID in the request body:

Authentication and existing CSRF controls apply. Settings do not require project selection. Compatible providers use operator-approved endpoint IDs rather than user-supplied URLs. Transport requires HTTPS, checks public DNS destinations, pins the checked connection address while verifying the hostname with TLS, and rejects redirects and implicit environment proxies. Credential values and raw provider error bodies are excluded from public diagnostics.

Operator setup and migration

BYOK defaults to disabled for compatibility with existing r34 deployments. The complete Linux reference explicitly enables it and starts with institutional AI restrictions. Use the hosting reference; environment flags alone do not provision the required runtime or durable state. Set:

PF_SAAS_ASSISTANT_ENABLED=true
PF_SAAS_ASSISTANT_STATE_DIR=/data/assistant
PF_SAAS_ASSISTANT_SHARED_STATE=true
PF_SAAS_ASSISTANT_BYOK_ENABLED=true
PF_SAAS_ASSISTANT_CREDENTIALS_KEY=REPLACE_WITH_DEDICATED_VAULT_KEY
PF_SAAS_ASSISTANT_COMPATIBLE_ENDPOINTS={}
PF_AI_DOCKER_IMAGE=REPLACE_WITH_PINNED_ASSISTANT_IMAGE

The vault key must be a URL-safe base64 encoding of 32 random bytes, distinct from PF_SAAS_SECRET_KEY. Inject it through the deployment's secret manager. Retain the vault key securely as part of a consistent database/private-state recovery set; keep it distinct from the storage-vault and session keys. Losing or replacing it requires users to save credentials again; this release does not provide automatic vault-key re-encryption. Session-secret rotation and vault-key rotation are separate.

An optional compatible endpoint mapping has the form {"approved-provider":"https://api.example.com/v1"}; replace the example with an approved provider. Empty {} disables compatible endpoint choices. Changing a mapping requires affected users to save their settings again. Named provider destinations are fixed by the adapter. Model access remains provider-dependent.

Install the release's SaaS requirements, back up the database and private state together, stop the API and workers, then run the explicit additive migration before serving the new code:

python -m pf_saas init

The current additive migration advances the SaaS database to schema 10; project grants and institutional AI policy remain enforced. The product remains r34. It does not rewrite scientific run artifacts, Python layers or conversations. Production uses PostgreSQL and explicitly configured durable shared assistant storage at the same path on each API replica. Declaring shared storage does not provision it. Rebuild and pin the existing Dockerfile.assistant executor image from this release. The API host still needs an operational container runtime; ordinary AWS Batch worker configuration does not supply that runtime by itself. No separate JavaScript extension image is required.

Disabling BYOK explicitly restores operator-managed provider configuration. Personal-key checkpoints cannot silently resume under the operator's key. A rollback must use a compatible database schema and consistent filesystem backup; replacing code alone does not reverse the additive migration.

Validation and reproducibility

The release gate runs the original r34 regression and provider/edition lifecycle matrix, additional personal-key isolation and transport tests, browser DOM tests, and a five-provider SaaS source-correction lifecycle. Provider replies and API keys in these tests are scripted/synthetic; scientific calculations are executed.

The source-correction fixture introduces a known Lorentz-equation sign error only in an isolated test copy. Its scripted provider reads that source and proposes the original correct equation as a Python layer. Candidate validation and active-stack probes exercise the corrected implementation. This is a test of source-repair capability, not a claim that the delivered scientific solver contained that defect or that a live model independently discovered a correction. Historical core bytes are retained alongside the reviewed maintenance changes described in the current validation report.

This branch also includes the narrow r34 execution-monitor repair: a temporary output file disappearing during a live scan does not invalidate a legitimate run. Final output collection remains strict. Existing Python layer and crash-repair validation semantics are preserved.

The recovery revision also supplies explicit continuation guidance and the previous partial response, retains safe checkpoints after retryable failures before the first tool result, and distinguishes request timeouts from connection interruptions. The interface shows the current failed/paused/completed state and offers a saved-investigation retry when possible. Credential revision, owner, source and evidence checks still apply. See R34_INVESTIGATION_RECOVERY_GUIDE.md for timeout settings and the source-binding implications of upgrading.

Completed OpenAI BYOK answers also retain credential-bound plain-text context for ordinary follow-up questions. Other providers retain their existing native continuation formats. Old answers without a valid private continuation remain visible in the transcript; they are not silently assigned a new credential's identity.

Verify an untouched extraction of the current application package:

python release_tools/package_r34_public_service.py verify --package

Current public-service and UI-correction evidence is under validation_r34_public_service. The earlier lifecycle evidence is retained under validation_r34_lifecycle. The earlier validation_r34_adoption and validation_r34_byok records retain their own source identities and historical execution scope. Read current validation for the exact scope and the lifecycle guide before backup, recovery or rollback. Do not regenerate earlier hashes against this update.

Local validation does not establish live model behavior, paid API access, production Docker isolation, production PostgreSQL contention, cloud deployment or native Windows/browser visual behavior. Those checks must be run on the configured deployment. The local test executor is explicitly selected test infrastructure, not a new production execution fallback. Final counts and archive identity are supplied in the accompanying validation report.

Workflow and conversation lifecycle

Private-workflow restore/permanent deletion and saved-conversation deletion are end-user controls. They do not require a configured AI key or consume model calls. Deleting a conversation does not delete independently saved workflows or layers. See the lifecycle and recovery guide.