ci: use the shared branch-aware CodeQL worker

Co-Authored-By: Codex <noreply@openai.com>

.circleci/config.yml

@@ -1,60 +1,14 @@
 version: 2.1
-
+setup: true
 orbs:
-   qqq-orb: kingsrook/qqq-orb@0.6.8
-
-commands:
-   configure-package-install:
-      steps:
-         - run:
-              name: Keep package installation unattended
-              command: |
-                 # These build machines are discarded after the job.
-                 sudo install -d /etc/needrestart/conf.d
-                 printf '%s\n' '$nrconf{restart} = "l";' | sudo tee /etc/needrestart/conf.d/99-qqq-ci.conf >/dev/null
-
+  qqq-orb: kingsrook/qqq-orb@0.7.12
 workflows:
-   test_only:
-      jobs:
-         - qqq-orb/mvn_test_only:
-              pre-steps:
-                 - configure-package-install
-              context: [qqq-maven-registry-credentials]
-              filters:
-                 branches:
-                    ignore: /(develop|release\/.*)/
-
-   publish_snapshot:
-      jobs:
-         - qqq-orb/mvn_publish:
-              pre-steps:
-                 - configure-package-install
-              context: [qqq-maven-registry-credentials]
-              branch_type: snapshot
-              filters:
-                 branches:
-                    only: [develop]
-
-   publish_release_candidate:
-      jobs:
-         - qqq-orb/mvn_publish:
-              pre-steps:
-                 - configure-package-install
-              context: [qqq-maven-registry-credentials]
-              branch_type: release_candidate
-              filters:
-                 branches:
-                    only: [/release\/.*/]
-
-   publish_release:
-      jobs:
-         - qqq-orb/mvn_publish:
-              pre-steps:
-                 - configure-package-install
-              context: [qqq-maven-registry-credentials]
-              branch_type: release
-              filters:
-                 branches:
-                    ignore: /.*/
-                 tags:
-                    only: [/^v\d+\.\d+\.\d+$/]
+  setup:
+    jobs:
+    - qqq-orb/generate_pipeline:
+        orb_version: 0.7.12
+        filters:
+          branches:
+            ignore: automation/qbit-rc-pending
+          tags:
+            only: /^v\d+\.\d+\.\d+$/

.github/workflows/codeql.yml

@@ -0,0 +1,23 @@
+name: CodeQL
+'on':
+  push:
+    branches:
+    - main
+    - develop
+    - release/**
+    - hotfix/**
+  pull_request: {}
+  schedule:
+  - cron: 41 16 * * 0
+  workflow_dispatch: {}
+permissions:
+  contents: read
+  actions: read
+  security-events: write
+  packages: read
+concurrency:
+  group: codeql-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+jobs:
+  analyze:
+    uses: QRun-IO/qqq-orb/.github/workflows/qbit-codeql.yml@c288a8864fe9054f68410e1d78f5863aea4c4d22

.github/workflows/release-rc.yml

@@ -1,25 +1,74 @@
-# Cut the next release candidate (QRun-IO/qqq docs/QRUN-QBIT-REPO-STANDARD.md, C6):
-# run this workflow by hand, or merge a develop PR labelled `release:rc`. It merges develop into
-# the release line and the release/* push runs CircleCI publish_release_candidate.
 name: Release candidate
-
-on:
+'on':
   workflow_dispatch:
     inputs:
       dry_run:
-        description: Print the plan without merging or creating branches
+        description: Plan a cut without changing release state
         type: boolean
         default: false
+      finalize:
+        description: Retry finalization of an existing cut; do not cut another RC
+        type: boolean
+        default: false
+      recover:
+        description: Recover the same published RC after a deployment timeout; never
+          reupload
+        type: boolean
+        default: false
+      circle_build:
+        description: Original Circle publisher build number (recovery only)
+        type: string
+        default: ''
+      merge_sha:
+        description: Existing cut merge_sha (finalize retry only)
+        type: string
+        default: ''
+      bump_sha:
+        description: Existing cut bump_sha (finalize retry only)
+        type: string
+        default: ''
+      branch:
+        description: Existing cut branch (finalize retry only)
+        type: string
+        default: ''
+      version:
+        description: Existing cut version (finalize retry only)
+        type: string
+        default: ''
   pull_request:
-    types: [closed]
-    branches: [develop]
-
+    types:
+    - closed
+    branches:
+    - develop
+  repository_dispatch:
+    types:
+    - qbit-rc-published
 permissions:
   contents: write
-
+  actions: read
+  checks: read
 jobs:
   release-rc:
-    if: github.event_name == 'workflow_dispatch' || (github.event.pull_request.merged == true && contains(github.event.pull_request.labels.*.name, 'release:rc'))
-    uses: QRun-IO/.github/.github/workflows/qbit-release-rc.yml@main
+    if: github.event_name == 'workflow_dispatch' || github.event_name == 'repository_dispatch'
+      || (github.event_name == 'pull_request' && github.event.pull_request.merged
+      == true && github.event.pull_request.base.ref == 'develop' && contains(github.event.pull_request.labels.*.name,
+      'release:rc'))
+    uses: QRun-IO/qqq-orb/.github/workflows/qbit-release-rc.yml@cc30f599e63c8e41629c99d23395bac1adb8bc44
     with:
-      dry_run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run }}
+      dry_run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run || false
+        }}
+      finalize: ${{ github.event_name == 'repository_dispatch' || (github.event_name
+        == 'workflow_dispatch' && inputs.finalize) }}
+      recover: ${{ github.event_name == 'workflow_dispatch' && inputs.recover || false
+        }}
+      circle_build: ${{ github.event_name == 'workflow_dispatch' && inputs.circle_build
+        || '' }}
+      merge_sha: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.merge_sha
+        || inputs.merge_sha || '' }}
+      bump_sha: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.bump_sha
+        || inputs.bump_sha || '' }}
+      branch: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.branch
+        || inputs.branch || '' }}
+      version: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.version
+        || inputs.version || '' }}
+    secrets: inherit

.gitignore

@@ -19,3 +19,6 @@ dependency-reduced-pom.xml
 /.env.local
 /.cache/
 .claude/settings.local.json
+
+# Runtime output from every provider module
+log/

.qqq-ci.yml

@@ -0,0 +1,16 @@
+profile: qbit
+orb_version: 0.7.12
+default_branch: develop
+java_version: '21'
+browsers: true
+api_checks: false
+docs_only: false
+release_on_main: false
+release_tag_policy: stable
+test_branch_policy: non-release
+publish:
+  snapshot: true
+  release_candidate: true
+  release: true
+  asciidoc: false
+release_completion: true

AGENTS.md

@@ -29,6 +29,8 @@ Always use the wrapper: Maven 3.10 cannot read the parent POM. The committed def
 
 ## Modules
 
+- `qbit-assistant-provider-api`: standalone provider SPI/value types and `ModelPricing`, all exclusively in `com.kingsrook.qbits.assistant.spi`; only Jackson annotations in production. Provider validation takes unresolved `ProviderSettings`, not an entity.
+
 - `qbit-assistant` (`com.kingsrook.qbits.assistant`):
   - `AssistantQBitProducer`, `AssistantQBitConfig` (with `AssistantModelRouting` and `AssistantBudgets`), `AssistantRuntime`, `AssistantSecurity`.
   - `metadata/`: tables, owner key type, the Assistant app (home + main tables in the nav), the retention process, the settings customizer (key-reference checks, masked key status), and the `assistant.admin` custom permission checker.
@@ -37,11 +39,16 @@ Always use the wrapper: Maven 3.10 cannot read the parent POM. The committed def
   - `persistence/AssistantStore`: the **only** code that calls QQQ data actions, and only on the QBit's own tables, under the user's session.
   - `engine/`: `TurnEngine` (the loop), `ContextBuilder` (cache-prefix order), `SystemPrompt`, `PolicyService` (policy row, budgets), `RateLimiter`, the `TurnEvent` / `TurnEventLog` stream, and `MessageParts`.
   - `api/`: `AssistantApi` (transport-free) and `AssistantRouteProvider` (Javalin, SSE).
-  - `provider/`: the provider-neutral SPI, plus `fake/ScriptedModelProvider` for tests, evals and demos.
+  - `provider/`: runtime-backed `RegistryModelProvider`, plus `fake/ScriptedModelProvider` for tests, evals and demos. The SPI lives in `qbit-assistant-provider-api`.
   - `developer/`: the record Developer-screen panel, on the core developer-panel contract.
   - `processes/`: `AssistantRetentionStep` and `TestConnectionProcess` (record action on `assistant_provider`).
   - `engine/ProviderService` (active provider from `assistant_provider` rows, key references, prices), `UsageRecorder` (one `assistant_usage` row per model call), `ConnectionTest`.
 - `qbit-assistant-provider-anthropic`: `AnthropicModelProvider` and `AnthropicMapping` (anthropic-java streaming).
+- `qbit-assistant-provider-openai`: OpenAI-compatible Chat Completions, model discovery and health using JDK HTTP and Jackson.
+- `qbit-assistant-provider-bedrock`: Claude through the Anthropic Bedrock backend, AWS default credentials and SigV4; IRSA/web-identity hosts supply STS.
+- `qbit-assistant-provider-vertex`: Claude through the Anthropic Vertex backend and Gemini through OpenAI-compatible Chat Completions, with refreshed Google ADC tokens.
+
+- `qbit-assistant-rag-pgvector`: JDBC vector storage; depends on the runtime RAG interfaces (`VectorStore`, `ChunkVector`).
 
 ## Invariants (do not break)
 
@@ -90,4 +97,4 @@ QQQ style:
 - `develop` publishes SNAPSHOTs.
 - `release/*` publishes RCs; the orb bumps `<revision>` in the root POM.
 - `v*` tags publish releases.
-- Both modules and the parent POM publish. The flatten plugin resolves `${revision}`.
+- All seven modules and the parent POM publish. The flatten plugin resolves `${revision}`.

CHANGELOG.md

@@ -1,20 +1,249 @@
 # Changelog
 
+## Unreleased - Conversation management (UI API extension 1.6.0)
+
+- `assistant_conversation` is open to every assistant user (`assistant.hasAccess` or `assistant.admin`, through the new `AssistantAccessPermissionChecker`) in the standard table UI. Rows stay locked to their owner by the `userId` record lock, so a user only ever sees, updates and deletes their own conversations; admins with the all-access key still see everyone's. The Assistant app (its nav) and every other assistant table stay admin-only.
+- Users change only a conversation's title, pinned flag and status (Active / Archived) through the table; the other fields are the assistant's own. A new title is encrypted in HIPAA mode, including literal text beginning with `enc:v1:`. Only an exact match to the same record's stored ciphertext is preserved unchanged; internal SYSTEM writes retain their existing storage path.
+- A table delete of a conversation also deletes its messages, turns, turn events, tool calls, feedback, data audits and pending actions (the same rows `DELETE /conversations/{id}` removes), so nothing is orphaned on a database without the cascading foreign keys. A conversation with an answer in progress is refused.
+- New record actions on `assistant_conversation`: **Archive conversations**, **Restore conversations** and **Delete conversations** (standard streamed ETL: selected records, Review, Result; same permission as the table; only rows the user can see; delete skips conversations with an answer in progress).
+- UI API extension assistant 1.6.0: `GET /conversations` items have `running` (an answer in progress: a RUNNING or CANCELLING turn that is not orphaned); `PATCH /conversations/{id}` accepts `{"read": true}` (sets `unreadCount` to 0); `GET /config` has `conversationsTable: "assistant_conversation"` when the session may query that table.
+
+## Unreleased - Starter prompts follow access
+
+- `profile.starterPrompts` in `GET /assistant/config` is built per user: up to three prompts generated from tables the user can read that have rows (UI API metadata and count as the user, bounded, current access rechecked on every request, stable order for the day), plus configured prompts only when tagged with tables the user can read (`[table] prompt`, `[none] prompt`; untagged lines are dropped). See UPGRADE.md.
+
+## Unreleased - Chat turns are not jobs
+
+- Ordinary chat turns no longer create core tracking jobs: they stay out of the Jobs tray and Jobs tables, and core no longer sends an "Assistant answer finished" notification for every answer. Crash safety is unchanged; it comes from the assistant's own turn table (leased, heartbeated `assistant_turn` rows, seq-numbered `assistant_turn_event` replay and the abandoned-turn sweep). The panel's Stop (`POST /turns/{id}/cancel`) is unchanged.
+- Removed the `AssistantRunTracker` SPI, `JobTrackingRunTracker` and `AssistantQBitConfig.withRunTracker` / `setRunTracker` / `getRunTracker` (see UPGRADE.md).
+- Real multi-step work stays a real job: a confirmed bulk load still launches through `POST /qqq/v1/processes/{p}/jobs`, and its tool result now carries `jobHref` (the job's `/app` link) next to `jobId`, plus a record ref to the job; the confirm response's `href` links to the job.
+- Scheduled task notifications (output mode Notification or Both) now go through core `QAlerts.notify` (category Job, the owner as the only audience, a link to the conversation, success/error/warning severity by run status), replacing the reflective call into an older alerts SPI that no longer matched.
+
+## Unreleased - Attachments
+
+- Files attached in the panel (`pageContext.attachments`, core upload refs) are read for the question: as the signed-in user's own upload, in memory, with per-file and per-question byte and character caps (`AssistantQBitConfig.attachments`). The type is sniffed from content; executables, archives and unknown binary data are refused. Text, Markdown and JSON are decoded with charset detection, PDF page text is extracted (PDFBox via QQQ core, no scripts, host font mapper preserved), CSV/TSV/XLSX become a header + rows + count preview, and PNG/JPEG/GIF/WebP images go to vision models as image parts.
+- Images are decoded with ImageIO before provider submission, rejecting truncated data and decoder warnings. A 16-million aggregate pixel / 100-frame budget bounds decoded data; original bytes are forwarded. WebP uses the explicit TwelveMonkeys decoder.
+- Content reaches the model in an untrusted `uploaded_file` block (delimiters neutralized) in the question's user message; the system prompt says it is data, never instructions. A file that cannot be read adds a notice to the answer and never fails the turn. In HIPAA mode attachments count as PHI.
+- Provider SPI: `ModelPart.Type.IMAGE` (`mediaType`, base64 `data`), mapped by the Anthropic, Bedrock and OpenAI-compatible providers. Claude models report vision. `ModelPart.toString()` never includes text or image data.
+- `GET /config`: `features.attachments`, `limits.maxAttachmentBytes`, `limits.maxAttachments`, `limits.attachmentTypes`.
+- System prompt: when `create_record` / `update_record` are offered, the model proposes the change instead of saying it cannot create records.
+
+## Unreleased - Optional provider health
+
+- An enabled provider that is not the default and not the only route for any configured routing (an enabled profile's simple/complex model, a budget downgrade model or a knowledge source's embedding model, with no fallback on another usable provider) is optional: when it is unreachable, its `assistant.provider.<id>` and `assistant.model.<id>` checks report DEGRADED with a message naming the provider requests use instead, so one unfinished local server no longer turns the whole `assistant` component DOWN. The default provider and sole routes still report DOWN. A failed provider probe still carries `reachable=false`, so the circuit breaker keeps refusing the provider.
+- New `assistant_provider.setup_state` (Setup state: Active / Setting up, empty counts as Active). A provider that is Setting up is never routed to (default, profile models, fallbacks, budget downgrades, embeddings) and gets no provider or model health checks; Test connection and Discover models still work. Apply the Provider setup state DDL (UPGRADE.md).
+
+## Unreleased - Fail soft (UI API extension 1.5.0)
+
+- Every message part, tool render and presentation is validated before it is stored or streamed, and again when stored parts and events are read: all render types (records, record, count, widget, history, pending_action, bulk_load_dry_run) and presentation blocks always carry their lists. A render that cannot be repaired is replaced by an error notice ("This result could not be displayed."); unknown part and render types pass through. Problems are logged with the type and a fixed code only.
+- Tool calls have their own limit (`toolCallTimeoutSeconds`, default 60) besides the turn's (`maxTurnSeconds`, default 300). A timed-out or failing tool gets an ERROR (`is_error`) result for the model, an ERROR tool part and an error notice for the user; internal details go only to the log.
+- Every turn ends: terminal events are emitted independently, so a failing emit never skips `message.end` or the terminal turn row. Conversation detail repairs assistant messages left `STREAMING` (an orphaned run is reaped; a run that already ended gives its status), and the retention process finalizes runs still `RUNNING` past the hard stream limit (e.g. after a pod restart).
+- `POST /qqq/v1/assistant/client-errors` (extension 1.5.0): the panel reports errors it hit (`scope`, `message`, optional stacks, route, ids, part/render type, app version, `occurredAt`). Answers `202 {"accepted": true}`; over `clientErrorsPerUserPerMinute` (default 30) it answers `202 {"accepted": false}` and drops the report. Fields are bounded, message and stacks scrubbed (secrets, e-mails, long numbers, tokens, query strings), ids kept only when they are the user's own. Rows go to the new owner-locked `assistant_client_error` table (Assistant app nav, retention after `toolResultRetentionDays`), and the `assistant.client-errors` health check turns degraded at `clientErrorWarnPerHour` (default 20) reports in an hour. Apply the Fail soft DDL (UPGRADE.md).
+
+## Unreleased - Empty renders and stream context (UI API extension 1.4.0)
+
+- Tool result renders always carry their lists: a `records` render for a query that matched nothing now has `"rows": []` and `"columns": []` (QQQ's JSON omitted empty lists, and Next's Assistant crashed the page reading `rows.length`). Parts and events stored before the fix are completed when read. Extension 1.4.0 documents the shape as `AssistantRecordsRenderV1`.
+- Streamed text arrives on the provider's own (virtual) thread; the turn's progress updates now run in the turn's QContext, so job progress no longer fails with "Could not flush job progress" (NPE on the missing instance).
+
+## Unreleased - UI API 1.6.0
+
+- UI API extension assistant 1.3.0 (requires QQQ 4.1.0-RC.15, UI API 1.6.0): operationIds, standard error responses with BasicErrorResponseV1, extension tags and trace IDs. Preserve HTTP statuses and assistant-specific error codes.
+- Retain AssistantErrorV1 as a deprecated component for compatibility. Remove dangling `null` schema references from the two bodyless 204 responses (delete conversation and feedback), with an empty-content workaround for core schema traversal. Success payloads are unchanged; the contract test retains the release baseline with explicit exceptions for the error schema migration and these documentation corrections.
+
+## Unreleased - Central health
+
+### Added
+
+- Dynamic `assistant.provider.<id>` and `assistant.model.<id>` dependency checks in component `assistant`, category AI, reusing provider diagnostics and minimal connection calls with deadlines, cost-cap/kill-switch skips and TEST usage accounting.
+- LOCAL breaker reuse of central provider outcomes younger than 60 seconds, with its existing lazy probe as fallback.
+- Generic Assistant health status card linking to filtered System Health; registration, status, accounting, deadline and sentinel-secret tests.
+- QQQ 4.1 compatibility for the header shim: setting extra headers avoids duplicates now that core forwards them too.
+
+### Removed
+
+- The home's independent answering/last-test health indicators and per-provider health/down-until display. Central health owns status and history. Manual Test connection actions, `lastTest*` fields and the circuit breaker remain.
+
+## Unreleased - Jobs tray
+
+- Track assistant answers in the core Jobs tray through `JobTracking`, with thinking, tool and writing progress and Stop support.
+- Require QQQ 4.1.0-RC.8 and the host's durable jobs runtime and jobs tables; answers remain untracked when the runtime is absent.
+- Default to `JobTrackingRunTracker`; opt out with `withRunTracker(AssistantRunTracker.NOOP)`.
+
+## Unreleased - In-app help
+
+- Ship the host-neutral Assistant help bundle through QQQ's native registry, replacing the temporary loader.
+- Cover Assistant tables, fields, actions, widgets and selectors; retain live metadata references and add a bundle coverage gate.
+- Document HOST bundle overrides and remove deployment-specific provider, classification, retention and backup guidance.
+
+## Unreleased - Transcript redaction
+
+- Tokenize classified PII/PHI in stored messages, tool inputs/results, replay events, pending actions and derived summaries using QQQ secured-data tokens. Preserve eligible model requests and live SSE.
+- Stage content until turn completion, redact split deltas and classify criteria even when no records match; protect assistant logs with a scoped core redactor.
+- Reject proposals whose parameters were redacted; prevent confirmation before turn completion.
+- Read core table-level classification metadata and add secured-data canary tests for storage, audits, logs and in-memory model access.
+- Preserve durable-turn watchdog, supersede, shutdown and restart recovery with turn-scoped transcript redaction; widen token-bearing columns and entity limits, with H2-safe upgrade SQL.
+- Require QQQ 4.1.0-RC.7 (qqq#1182); retain the default audit-history opt-in and avoid duplicated routing headers against current core. RC.7 is released.
+## Unreleased - Foreign keys
+
+- Reference DDL: add the missing foreign keys (conversation tree, usage, data audit,
+  budget accounting, profile skills) with orphan quarantine and their indexes; make
+  `assistant_model.provider_id` `ON DELETE CASCADE`. A Postgres guardrail test fails
+  any declared relation without a foreign key.
+
+## Unreleased - Durable turns
+
+- Renew user-owned run leases with heartbeats, poll cross-replica Stop, enforce
+  hard deadlines, and finalize active runs during graceful shutdown. Recover
+  abandoned runs on replay, active discovery, or the next question.
+- Default to superseding a prior answer in the same conversation. Accept explicit
+  concurrent questions; the per-user cap supersedes the oldest run instead of
+  refusing another question. Per-minute limits and budgets still apply.
+- Add `GET /qqq/v1/assistant/turns/active`, `turn.phase` progress and `startedAt`
+  on `message.start`. Cancel is idempotent and returns HTTP 200.
+- Add the optional `AssistantRunTracker` Jobs tray SPI (no-op by default),
+  pending QQQ core job tracking (#1210).
+- Add the durable-turn schema upgrade; apply it before deploying this runtime.
+  A partial unique index fences duplicate terminal events from concurrent reapers.
+- UI API extension `assistant` 1.2.0 (additive): `turns/active`, the optional
+  `concurrency` on a new turn, 503 `SHUTTING_DOWN`, `turn.phase`,
+  `message.start.startedAt`, cancelReason `SUPERSEDED`. The 429 response stays
+  documented for budgets and per-minute limits; the "answer already in progress"
+  refusal is no longer returned. Cancel keeps 202 documented for older replicas.
+
+## Unreleased - Starter defaults
+
+- Every seed changeset's rollback is empty: a seeded row cannot be told apart from a host's own row with the same name, and Liquibase also rolls back changesets it marked ran, so a name-based undo would delete host data.
+
+- Fix the defaults changelog: every precondition is a portable `sql-check` (the formatted-SQL `table-exists` form failed to parse); the policy, budget and prices are seeded only into empty tables and the profile only when no default exists, so an existing host never changes on deploy. The test now runs the changelog through Liquibase 4.33, including an already configured host and a missing table.
+- The Setup card prices the default model the way calls are costed (registry, price rows, configured prices); "Add rows for every table" reads fresh data-access rows.
+
+- Ship `db/liquibase/qbit-assistant/assistant-defaults.changelog.sql`: insert-only starter rows for the policy, a default profile, four starter skills offered through it, a monthly instance budget (warn, downgrade, stop), current Anthropic prices and a disabled example scheduled task.
+- Add the Setup card to the Assistant home: every configuration table with its state (set up, needs setup, using defaults, optional) and the next step.
+- Add the `assistant_data_access` table action "Add rows for every table", which writes the default access out as editable rows.
+- Add `help/qbit-assistant.yaml` (QQQ help-bundle format) for the app and every assistant table, saying what each table is for and how its rows get created; applied by `AssistantHelp` until core help bundles ship in a release.
+- Guardrail tests: every table is used at runtime, seeded or explained, and has empty-state help; the changelog seeds a fresh schema and the seeded rows change the assistant's behavior.
+
+## Unreleased - X1/Y1
+
+- Add default-off `withRecordHistory(true)` host opt-in: remove only `audit*` on RC.6, or invoke core #1193 audit-read/write-deny support when available. Preserve user permissions and all other channel denials; kof22 does not opt in.
+
+- Register explicit assistant-channel denials on every assistant table, process,
+  report and widget, preserving core security patterns; fail runtime startup
+  when an assistant object is exposed.
+- Bump the assistant UI API extension to 1.1.0 for optional owned-turn attribution
+  on explain-access, and regenerate its OpenAPI contract.
+- Preserve turn attribution in knowledge discovery, RAG reads and explain-access
+  calls; confirm actions retain the original turn and scheduled runs retain the task.
+- Build audit links with the presentation filter-link builder, filtering by
+  record, table and channel, including deletes; widen audit link storage to TEXT.
+  Document the host audit migration and the QBit column widening.
+- Verify the admin denial matrix through the real invoker and Next UI, startup
+  failures, and confirmed-write human/channel attribution with decoded audit links.
+## Unreleased - Email
+
+### Changed
+
+- Switch scheduled-result email delivery to qbit-email 0.1.0-RC.2's published `com.kingsrook.qbits.email.api` package, preserving templates, categories, idempotency keys, linked records and status mapping.
+- Add optional qbit-email 0.1.0-RC.1 delivery of a scheduled task's result (`AssistantEmail.sendScheduledResult`): template `assistant_scheduled_result`, link-only secure message for results above PUBLIC using core's `DataClassification`, owner-recipient hook, opt-in and `emailExternalApproved` gates. Scheduled-task wiring remains a separate integration step.
+
+## Unreleased - Provider API extraction (#30)
+
+- **BREAKING:** move all 23 provider API types, including `ModelPricing`, to `com.kingsrook.qbits.assistant.spi`. Recompile consumers with the new imports; see UPGRADE.md. Enforce exclusive package ownership and API dependency boundaries with ArchUnit.
+
+- Extract provider SPI/value types and `ModelPricing` into `qbit-assistant-provider-api`, now exclusively in `com.kingsrook.qbits.assistant.spi`. Its only production dependency is Jackson annotations.
+- Move Anthropic, OpenAI, Bedrock and Vertex main dependencies to the API; retain runtime fixtures in test scope. Pgvector still needs runtime RAG interfaces.
+- Provider-specific validation now takes unresolved `ProviderSettings` instead of `AssistantProvider`; add an ArchUnit boundary and standalone coverage gates.
+## Unreleased - P-g
+
+- Add admin Scheduled tasks, owner-locked run history, Quartz cron/timezones,
+  and a 60-second QQQ scheduled process using the host's scheduler context.
+- Log in through the loopback UI API with a separately allow-listed credential
+  environment reference; verify the designated user before starting a normal turn.
+- Add Review/Result Approve write mode, Revoke write mode and Run now actions.
+  Approval binds the task definition; scheduled writes always await confirmation.
+- Attribute scheduled UI API requests and tool logs, apply per-run STOP caps,
+  and send optional Alerts notifications to the designated user. HIPAA summaries
+  contain only `see conversation`.
+- Add unique schedule-slot claims, fixed-clock fixture integration tests and
+  additive Postgres DDL. No API routes or provider modules change.
+
+## Unreleased - P-f
+
+- Add OpenAI-compatible embeddings (including Azure), explicit CHAT/EMBEDDING
+  model kinds, editable discovery hints, and budgeted EMBED usage.
+- Add admin Knowledge sources with streamed Review/Result Index now and Clear
+  index actions. Indexing uses the clicking admin's UI API session, chunks text,
+  skips unchanged hashes and reconciles disappeared records.
+- Add content-free in-memory and optional JDBC pgvector stores, per-instance
+  schemas, HNSW cosine search and transactional record replacement.
+- Add permission-filtered `search_knowledge`, fresh UI API reads, existing
+  masking/redaction, PHI embedding guards, classification propagation and citations.
+- Add embedding HTTP contracts, real UI API RAG security/golden tests and
+  always-on JDBC contracts; the pgvector container test skips without Docker.
+## Unreleased - Answer presentation
+
+- Add `present_results`: server-formatted metrics, tables, computed percentages,
+  charts and validated in-app filter/record/action links.
+- Persist and stream presentation parts with a multi-line GFM fallback and
+  record-data retention; add a static default presentation skill.
+- Add the owner's 81 JPEG / 20 PNG golden example, shared live eval coverage,
+  permission/formatting/input tests and strict-schema budget coverage.
+
+## Unreleased - P-e
+
+- Add per-profile heuristic/classifier model routing, with budgeted ROUTE usage.
+- Add bounded cross-provider fallback chains, PHI-safe selection, neutral history
+  rebuilding, and a 60-second connection circuit breaker with cached local probes.
+- Show provider health, fallback totals and turn routing; include additive schema
+  migration and admin record-screen controls.
+
+
+## Unreleased - P-d
+
+- Require QQQ RC.5 and send budget alerts directly through core QAlerts, with admin-visible alert type metadata and core sink tests.
+
+- Admin budgets, expiring overrides, deduplicated warning/downgrade/stop events.
+- Per-dispatch limits preserving PHI routing and existing caps.
+- Home budget cards, 30-day cost/token bars and provider breakdowns.
+
+
+## Unreleased — P-c
+
+- Add configurable table/field classification, persistent turn/conversation maxima,
+  and PHI routing checks before every model call, with a safe blocked-turn reason.
+- Add HIPAA mode, eligible-provider enforcement, AES-256-GCM conversation storage,
+  provider diagnostic redaction, and independent PHI conversation retention.
+- Add owner-locked, admin read-only data routing audits and HIPAA status on the home.
+- Classification levels are core's `DataClassification` (the qbit stand-in is removed); the default source reads core AI metadata merged with configuration.
+
 All notable changes to this project are documented here. The format follows Keep a Changelog, and versions follow semantic versioning.
 
 ## [0.1.0] - Unreleased
 
+- Add optional AWS Bedrock (Claude) and Google Vertex (Claude/Gemini) adapters using server credentials, static model discovery and allow-listed endpoint overrides. AWS IRSA/web-identity hosts supply STS themselves; no additional dependency is bundled.
+- Add the provider `cloudProject` column, cloud settings validation, injected Anthropic clients and per-request OpenAI bearer-token suppliers. Vertex Gemini prefixes model ids and omits strict tools.
+- Add localhost cloud contract tests and golden tool turns, including AWS binary event-stream framing, SigV4, token refresh and cloud HTTP error mapping.
+
+- Add named, server-only CA bundles for HTTPS providers, additive JVM trust and sanitized TLS diagnostics; tolerate repeated/missing streamed tool identities and invalid arguments, with a golden tool round-trip test.
+- Add the provider/model registry, per-model capabilities and prices, keyless local providers, discovery and health, and provider/model connection tests.
+- Add the optional JDK HTTP OpenAI-compatible adapter for OpenAI, Azure, OpenRouter, Ollama, LM Studio, vLLM and llama.cpp, with strict-schema safeguards and localhost contract tests.
+
 Phase 0/1 of the QQQ Assistant: read-only Q&A and navigation. Requires QQQ 4.1 with:
 - the AI tool kernel (`qqq-backend-core` `actions.ai`, QRun-IO/qqq#1078)
 - the developer-panel contract (QRun-IO/qqq#1076).
 
+### Changed (0.1.0-RC.7, needs QQQ with QRun-IO/qqq#1128)
+- The assistant's endpoints are spec'd `/qqq/v1` operations (UI API extension `assistant` 1.0.0, prefix `/assistant`): same URLs, bodies and statuses, now in the served OpenAPI; turns and events are `text/event-stream`. The raw routes are gone.
+- Tools call core's `UiApiInvoker` with the caller's own request credentials (`UiApiCredentials`); the loopback stand-in is removed. The assistant's own operations are never invocable by its tools.
+- The OpenAPI fragment is committed (`openapi/qqq-v1/assistant.yaml`) and contract-tested.
+
 ### Changed (0.1.0-RC.6): tools go through the UI API (owner decision 2026-10-13)
 - **Every data tool runs a spec'd `/qqq/v1` operation with the user's own session** (`UiApiGateway`, loopback HTTP with the `sessionUUID` cookie): the same authentication, permissions, record locks, validation, audit and errors as the UI. A user without a permission gets the identical denial through the assistant. `navigate` and `search_help` (no records) stay on the core kernel. `LoopbackUiApiGateway` is a stand-in for core's `UiApiInvoker` (QRun-IO/qqq#1128).
 - Tools: `list_tables`, `describe_table`, `query_records`, `count_records`, `get_record`, `search_records`, `render_widget`, `get_record_history`, and new **`create_record`, `update_record`, `delete_record`**.
 
 ### Added (0.1.0-RC.6)
-- **Profiles** (`assistant_profile`, nav "Profiles"): display name, icon, personality (≤ 2,000 chars, appended to the per-user system block), greeting, starter prompts; one default, optional app / permission scope. `/assistant/config` returns `profile`.
-- **Skills** (`assistant_skill`, nav "Skills", linked through `assistant_profile_skill`, a child list on profiles): admin-written Markdown instructions read only when relevant (keywords / apps), ≤ 6,000 chars each and 12,000 per question. Instructions only: they never grant tools, endpoints or access (ArchUnit-enforced).
+- **Profiles** (`assistant_profile`, nav "Profiles"): display name, icon, personality (≤ 2,000 chars, appended to the per-user system block), greeting, starter prompts; one default, optional app / permission scope. `/assistant/config` returns `profile`.
+- **Skills** (`assistant_skill`, nav "Skills", linked through `assistant_profile_skill`, a child list on profiles): admin-written Markdown instructions read only when relevant (keywords / apps), ≤ 6,000 chars each and 12,000 per question. Instructions only: they never grant tools, endpoints or access (ArchUnit-enforced).
 - **Explain access**: `GET /qqq/v1/assistant/access?table=&prompt=` and the `assistantAccess` home widget: per table and tool, allowed or the reason.
 - **Recent denials** card on the Assistant home.
 - `AssistantStore` refuses any table that is not `assistant_*`; ArchUnit forbids the tool / UI API / access packages from using QQQ actions, the AI kernel or the profile and skill classes.
@@ -37,7 +266,7 @@ Phase 0/1 of the QQQ Assistant: read-only Q&A and navigation. Requires QQQ 4.1 w
 
 ### Added (0.1.0-RC.4)
 - **Provider settings** (`assistant_provider`): type (registered `AssistantProviderType`s; `AnthropicProviderType` in the Anthropic module), model, enabled, default, base URL override, monthly cost cap, max output tokens per request, max concurrent requests, and the last connection test. The default enabled row is the active provider; with no rows the provider registered in code is used, so existing hosts keep working.
-- **Key handling:** the key is never stored. A row names the environment variable that holds it (`apiKeyEnvName`, allow-listed); `apiKeyStatus` is computed on read (`Set • …abcd`) and dropped on save. A pasted key, an unrelated variable or an unlisted base URL is refused. New config: `withProviderType`, `allowedApiKeyEnvNames`, `allowedBaseUrls`, `withSecretResolver`, `providerTestTimeoutSeconds`.
+- **Key handling:** the key is never stored. A row names the environment variable that holds it (`apiKeyEnvName`, allow-listed); `apiKeyStatus` is computed on read (`Set • …abcd`) and dropped on save. A pasted key, an unrelated variable or an unlisted base URL is refused. New config: `withProviderType`, `allowedApiKeyEnvNames`, `allowedBaseUrls`, `withSecretResolver`, `providerTestTimeoutSeconds`.
 - **Test connection**, a record action on providers (standard streamed ETL Review and Result lines): one short live call, result saved on the row and recorded as a `TEST` usage row.
 - **Per-call usage** (`assistant_usage`): one row per model call (turn steps and tests) with provider, model, status, error kind, HTTP status, latency, tokens and cost. Child list on conversations and providers.
 - **Model prices** (`assistant_model_price`), editable, used for every call's cost; the reference DDL seeds the Anthropic list prices of 2026-10. The built-in `pricing` defaults now cover every current Claude model.

CLAUDE.md

@@ -29,6 +29,8 @@ Always use the wrapper: Maven 3.10 cannot read the parent POM. The committed def
 
 ## Modules
 
+- `qbit-assistant-provider-api`: standalone provider SPI/value types and `ModelPricing`, all exclusively in `com.kingsrook.qbits.assistant.spi`; only Jackson annotations in production. Provider validation takes unresolved `ProviderSettings`, not an entity.
+
 - `qbit-assistant` (`com.kingsrook.qbits.assistant`):
   - `AssistantQBitProducer`, `AssistantQBitConfig` (with `AssistantModelRouting` and `AssistantBudgets`), `AssistantRuntime`, `AssistantSecurity`.
   - `metadata/`: tables, owner key type, the Assistant app (home + main tables in the nav), the retention process, the settings customizer (key-reference checks, masked key status), and the `assistant.admin` custom permission checker.
@@ -37,19 +39,29 @@ Always use the wrapper: Maven 3.10 cannot read the parent POM. The committed def
   - `persistence/AssistantStore`: the **only** code that calls QQQ data actions, and only on the QBit's own tables, under the user's session.
   - `engine/`: `TurnEngine` (the loop), `ContextBuilder` (cache-prefix order), `SystemPrompt`, `PolicyService` (policy row, budgets), `RateLimiter`, the `TurnEvent` / `TurnEventLog` stream, and `MessageParts`.
   - `api/`: `AssistantApi` (transport-free) and `AssistantRouteProvider` (Javalin, SSE).
-  - `provider/`: the provider-neutral SPI, plus `fake/ScriptedModelProvider` for tests, evals and demos.
+  - `provider/`: runtime-backed `RegistryModelProvider`, plus `fake/ScriptedModelProvider` for tests, evals and demos. The SPI lives in `qbit-assistant-provider-api`.
   - `developer/`: the record Developer-screen panel, on the core developer-panel contract.
   - `processes/`: `AssistantRetentionStep` and `TestConnectionProcess` (record action on `assistant_provider`).
   - `engine/ProviderService` (active provider from `assistant_provider` rows, key references, prices), `UsageRecorder` (one `assistant_usage` row per model call), `ConnectionTest`.
 - `qbit-assistant-provider-anthropic`: `AnthropicModelProvider` and `AnthropicMapping` (anthropic-java streaming).
+- `qbit-assistant-provider-openai`: OpenAI-compatible Chat Completions, model discovery and health using JDK HTTP and Jackson.
+- `qbit-assistant-provider-bedrock`: Claude through the Anthropic Bedrock backend, AWS default credentials and SigV4; IRSA/web-identity hosts supply STS.
+- `qbit-assistant-provider-vertex`: Claude through the Anthropic Vertex backend and Gemini through OpenAI-compatible Chat Completions, with refreshed Google ADC tokens.
+
+- `qbit-assistant-rag-pgvector`: optional host-supplied JDBC vector store, isolated by instance schema; depends on runtime RAG interfaces (`VectorStore`, `ChunkVector`), with no QQQ RDBMS internals.
 
 ## Invariants (do not break)
 
+- **Transcript redaction:** stored transcripts never contain raw PII/PHI values; tokens via `ClassifiedValueTokens`. Redact storage copies before truncation/encryption; eligible model inputs and live SSE remain unchanged.
+
 - **Sessions:**
+  - Scheduled runs log in as the designated user through `POST /qqq/v1/manageSession`; resolve only its returned UUID, verify the user id, and never construct or elevate a session. The QQQ-supplied scheduler context touches only assistant bookkeeping.
   - Never use `QSystemUserSession` or construct a `QSession` in main code (ArchUnit).
   - Every route uses `ExecutorSessionUtils.setupSession` (the user's own session).
   - `AssistantSecurity` only ever adds the user's OWN id key, or the all-access key for `assistant.admin` holders.
+- **Channel wall:** every `assistant_*` object (table, process, report and widget) is denied to the `assistant` channel; startup fails otherwise. Requests carry `assistant/<turnId>` or `assistant/scheduled/<taskId>`; administration uses `next-ui`.
 - **Data access:**
+  - The vector index stores no record content: only source/table/key/field/chunk, content hash and embedding. Retrieval re-reads every hit through the UI API as the asking user, then applies the existing get_record exposure/masking path.
   - Only `persistence/` calls QueryAction, InsertAction and the other data actions (ArchUnit).
   - Data tools run only through `UiApiToolbox` → `UiApiGateway` (spec'd `/qqq/v1` operations with the user's `sessionUUID`); never core data actions for user data. Only `navigate` and `search_help` use `AiToolKernel.execute`.
   - Data access (`DataAccessService`) and the policy only ever narrow what the UI API allows; a table whose AI exposure is NONE stays NONE.
@@ -61,9 +73,15 @@ Always use the wrapper: Maven 3.10 cannot read the parent POM. The committed def
   - Errors (DENIED, NOT_FOUND, INVALID_INPUT, ERROR) are `is_error` results.
   - Unknown tools and over-limit calls also get error results.
 - **Keys:** never stored in a table. `assistant_provider.apiKeyEnvName` holds only an allowed environment variable NAME; `apiKeyStatus` is computed on read (last 4 at most) and stripped on save.
+  - Scheduled task `credentialEnvName` is a separately allow-listed environment variable NAME. Tokens never enter rows, model context or logs. `credentialStatus` is computed and stripped on save.
+  - Scheduled write approval is invalidated by changes to prompt, run-as user, credential reference, profile or write request. Scheduled writes always require the designated user's panel confirmation.
 - **Logging:** never log message content, prompts, tool results or keys. Structured end-of-turn log only.
 - **Thinking:** thinking is never streamed or stored. The Anthropic adapter keeps the raw assistant message (with signatures) only in memory, as `providerState`, for the tool loop.
 - **Links:** only `/app` or `/app/...` hrefs are emitted (`TurnEngine.isAppHref`).
+- **PHI routing:** PHI only to `hipaaEligible` providers; checked before every model call. Conversation classification never decreases.
+- **HIPAA storage:** Conversation storage encrypted in HIPAA mode, only in `AssistantStore`; encryption keys are environment references and never logged or stored in tables.
+- **Fallback:** fallback never crosses the PHI rule; never local-to-cloud by default. No retry after partial output from that call; provider switches rebuild neutral history without providerState.
+- **Budgets:** budgets are checked before every model call; downgrade never crosses the PHI rule.
 - **Kill switch:** read fresh before every model call and every tool step.
 
 ## Tests
@@ -92,4 +110,4 @@ QQQ style:
 - `develop` publishes SNAPSHOTs.
 - `release/*` publishes RCs; the orb bumps `<revision>` in the root POM.
 - `v*` tags publish releases.
-- Both modules and the parent POM publish. The flatten plugin resolves `${revision}`.
+- All seven modules and the parent POM publish. The flatten plugin resolves `${revision}`.

README.md

@@ -4,12 +4,143 @@ An in-app AI assistant for any QQQ application. The user asks a question in a ch
 
 Design spec: `QRun-IO/qqq` `docs/specs/2026-10-11-qqq-assistant-qbit-design.md`.
 
+## Modules
+
 | Artifact | What it is |
 |---|---|
-| `com.kingsrook.qbits:qbit-assistant` | The QBit: conversation tables, turn engine, `/qqq/v1/assistant` routes (JSON + Server-Sent Events), budgets, kill switch, the provider SPI, and a scripted provider for tests and demos. |
+| `com.kingsrook.qbits:qbit-assistant-provider-api` | Provider SPI, connection settings, messages, usage and pricing types; only Jackson annotations at runtime. |
+| `com.kingsrook.qbits:qbit-assistant` | The QBit: conversation tables, turn engine, `/qqq/v1/assistant` routes (JSON + Server-Sent Events), budgets, kill switch, the provider registry, and a scripted provider for tests and demos. |
 | `com.kingsrook.qbits:qbit-assistant-provider-anthropic` | The Claude provider (`com.anthropic:anthropic-java`). Add it to use Claude. The core QBit has no LLM SDK dependency. |
+| `com.kingsrook.qbits:qbit-assistant-provider-openai` | OpenAI-compatible chat and embedding providers. |
+| `com.kingsrook.qbits:qbit-assistant-provider-bedrock` | Claude through AWS Bedrock. |
+| `com.kingsrook.qbits:qbit-assistant-provider-vertex` | Claude and Gemini through Google Vertex AI. |
+| `com.kingsrook.qbits:qbit-assistant-rag-pgvector` | JDBC vector store; retains the runtime dependency for `VectorStore` and `ChunkVector`. |
 
-The data access itself is done by the AI tool kernel in QQQ core (`com.kingsrook.qqq.backend.core.actions.ai.AiToolKernel`). The kernel checks table permissions and exposure rules, applies record security, and caps and redacts what the model sees. Every tool result reaches the model wrapped as untrusted data.
+### Implementing a provider outside qbit-assistant
+
+Depend on `com.kingsrook.qbits:qbit-assistant-provider-api` at the same version as
+QBit Assistant, and implement `AssistantModelProvider` and optionally
+`AssistantProviderType`. No assistant runtime dependency is needed. All API types, including
+`ModelPricing`, live exclusively in `com.kingsrook.qbits.assistant.spi`. External
+consumers such as qbit-marketing allow that package in their G1 guardrails;
+qbit-bom will add it to the G1 defaults. See [migration imports](UPGRADE.md#provider-api-extraction-30).
+`AssistantProviderType.validate(ProviderSettings)` receives unresolved settings
+(including `apiKeyEnvName`), without a database entity or resolved credentials.
+Hosts register providers through `AssistantQBitConfig` in `qbit-assistant`.
+
+Data tools use the QQQ UI API (`/qqq/v1`) with the signed-in user's session. The UI API enforces permissions and record locks; assistant data-access policy and field exposure can only narrow access. Only record-free navigation and help use the core AI tool kernel. Every tool result reaches the model wrapped as untrusted data.
+
+## Transcript privacy
+
+QQQ **4.1.0-RC.7** supplies the secured-data tokens and log hook (`qqq#1182`).
+Stored transcripts never contain the raw PII/PHI values read by a turn or supplied
+in classified tool criteria/fields. Messages, tool logs, replay events, knowledge
+snippets and pending payloads store `ClassifiedValueTokens` tokens; scheduled
+summaries use the redacted message. The model and live user stream retain the
+values permitted by PHI routing. History and replay show tokens instead.
+
+Content is finalized at turn completion; interrupted servers leave value-free
+placeholders. Proposals requiring redacted parameters are rejected and must be
+completed in the application. Existing transcripts are not migrated. See
+[transcript redaction](docs/DESIGN.md#transcript-redaction-secured-data-15).
+The dependency upgrade stays draft until RC.7 is published; local verification:
+
+```powershell
+.\mvnw.cmd -q verify "-Dqqq.snapshot.version=4.1.0-RC7PRE-SNAPSHOT"
+```
+
+## Host audit attribution (X1/Y1)
+
+Use QQQ **4.1.0-RC.6 or later**. The QBit explicitly denies every assistant
+configuration table, process, report and widget to the `assistant` channel;
+runtime initialization fails if an assistant object is exposed. The same human
+can still administer it through Next UI (`next-ui`). Core's security-surface
+deny patterns remain in place.
+
+Enable the audit client field in the host's core audit provider **after adding
+the backing column**:
+
+```java
+new AuditsMetaDataProvider().withClientChannelField(true)
+   .defineAll(qInstance, backendName, null);
+```
+
+Add nullable `audit.client_channel VARCHAR(100)` using the host's migration and
+column-naming conventions. For kof22 this requires a feature-named changeset
+under `changesets/features/`; this QBit does not migrate the host's audit table.
+The actor remains the signed-in human; `clientChannel` distinguishes
+`assistant/<turnId>`, `assistant/scheduled/<taskId>` and `next-ui`.
+
+Apply the X1/Y1 DDL in [UPGRADE.md](UPGRADE.md) to widen the existing
+`assistant_tool_call.audit_href` column to TEXT for encoded filters.
+Successful record writes store `assistant_tool_call.auditHref` as an `/app/audit`
+filter link over `recordId`, `auditTable.name` and `clientChannel`. The human
+opens this link with their UI permissions; the assistant cannot read audits by
+default. Without the audit channel field, the QBit leaves `auditHref` empty.
+Confirmed scheduled actions use their original turn id when the human approves.
+
+
+## RAG setup
+
+Knowledge retrieval is optional. The vector index stores **no record content**:
+only source/table/key/field/chunk identifiers, SHA-256 hashes and embeddings.
+Indexing reads through the UI API as the clicking administrator. Retrieval
+re-reads each hit through that same API as the asking user, silently filters
+403/404 results, applies `get_record` field exposure/masking/redaction and returns
+fresh snippets with `/app/...` citations. `search_knowledge` follows `allowedTools`
+and is offered only with an enabled source the user may read in the UI.
+
+1. Register the OpenAI-compatible provider module and configure the embedding
+   endpoint through the existing provider settings/URL allowlist. Discover or add
+   a model, set **Model kind = EMBEDDING** and its dimensions. Known discovery
+   defaults are `bge-m3` (1024) and `nomic-embed-text` (768); these remain editable.
+   CHAT models cannot be selected for embedding, and EMBEDDING models cannot answer
+   chat turns. Each embedding batch contains at most 64 inputs.
+2. Use the default `InMemoryVectorStore` for tests/small hosts, or add
+   `com.kingsrook.qbits:qbit-assistant-rag-pgvector` at the QBit's version for
+   persistence. The host supplies its JDBC driver and DataSource; this module
+   does not depend on QQQ RDBMS internals.
+3. For pgvector, have the DBA install the extension once in the chosen database:
+   `CREATE EXTENSION IF NOT EXISTS vector`. Give the application a distinct schema
+   per QQQ instance. Configure the store before producing the QBit:
+
+   ```java
+   PgVectorStore vectors = new PgVectorStore(dataSource, 1024)
+      .withSchema("assistant_rag_my_instance");
+   vectors.ensureSchema();
+   config.withVectorStore(vectors);
+   config.withUiApiBaseUrl("http://127.0.0.1:8000");
+   ```
+
+   The UI API URL is this server's own listening address. Configure it explicitly
+   so Index now works before any chat request has taught the runtime its local
+   port. The store creates a content-free `assistant_rag_chunk` table and an HNSW
+   cosine index. Its fixed dimension must match every source using the store;
+   different models are searched separately. No credentials go in source rows.
+   See the [pgvector installation/index documentation](https://github.com/pgvector/pgvector)
+   and the reference DDL in [schema-postgres.sql](docs/schema-postgres.sql).
+4. Open **Assistant → Knowledge sources** as an `assistant.admin`. Add the table,
+   comma-separated text fields, optional title field and QQQ query-filter JSON,
+   embedding model, and chunk size/overlap (defaults 1500/200). Tables with AI data
+   access NONE, `assistant_*` tables, and fields with NONE/METADATA_ONLY exposure
+   are refused. MASKED fields are masked before embedding and in snippets.
+5. Select **Index now**. Review makes no embedding calls; Result reports records
+   seen, chunks embedded, unchanged, removed and errors. Re-running unchanged
+   content sends no embeddings. A complete successful scan removes disappeared
+   records; failed scans preserve unvisited entries. **Clear index** removes only
+   that source's vectors. Changes after indexing are read fresh, but semantic
+   ranking becomes current only after re-indexing.
+
+Embedding usage has purpose `EMBED`, counts toward budgets, and observes the kill
+switch and provider concurrency limits. PHI sources and queries in PHI
+conversations require an eligible embedding provider; the eligibility flag is an
+operator assertion, as for chat. Automatic budget downgrades cannot change an
+embedding model's vector space, so an incompatible downgrade stops the call.
+
+Scheduling is deferred to P-g. Its designated-user runner can call
+`RagService.index` within that user's authenticated context; P-f creates no system
+session, stored admin credentials, scheduler or background content crawler.
+Data tools call the QQQ UI API through `UiApiToolbox` and `UiApiGateway` with the signed-in user's session. The UI enforces permissions and record security; the assistant further narrows access and caps and redacts returned values. Data tool results reach the model wrapped as untrusted data. Only record-free navigation and help use the core AI tool kernel.
 
 ## Requirements
 
@@ -61,6 +192,15 @@ The key never goes in config, tables or logs. It lives in the application's secr
 
 The provider's `toString` never contains the key. Its errors carry only the HTTP status and the API error type.
 
+### Starter defaults
+
+Include `db/liquibase/qbit-assistant/assistant-defaults.changelog.sql` (shipped in
+the jar) after your assistant DDL. A new installation then has a policy row, a
+default profile with four starter skills, a $50/month instance budget, current
+Anthropic prices and a disabled example scheduled task. Every row is insert-only,
+so administrators can edit them freely. The home's **Setup** card shows what is
+set up and the next step for the rest (usually: add a provider).
+
 ## Provider settings (the Providers table)
 
 Admins set up providers on the **Providers** screen (`assistant_provider`), a standard QQQ table:
@@ -80,12 +220,41 @@ Admins set up providers on the **Providers** screen (`assistant_provider`), a st
 
 **Test connection** is a record action on a provider (select one or more). It is a standard streamed ETL: Review lists what will be called and anything wrong with the row (missing key, disallowed variable or URL) before any call. Result has one line per provider: `connected to claude-sonnet-5-5 in 812 ms`, or the error with its kind and HTTP status. It makes one short live call (a 1-sentence prompt, at most 32 output tokens, effort low), saves the result on the row, and records the call in `assistant_usage` with purpose `TEST`.
 
+## Health checks
+
+The producer registers dynamic central checks in component `assistant`, category `AI`:
+
+| Name | Kind | Interval | Timeout |
+| --- | --- | --- | --- |
+| `assistant.provider.<id>` | DEPENDENCY | 300s; 60s for LOCAL providers | 10s |
+| `assistant.model.<id>` | DEPENDENCY | 21600s (6 hours) | 30s |
+
+Suppliers include enabled provider/model rows and refresh with the central registry.
+Provider checks reuse `AssistantProviderType.checkHealth`. Unsupported probes use
+circuit-breaker state only when less than ten minutes old, otherwise return UNKNOWN.
+Model checks reuse `ConnectionTest` (embeddings for embedding models), respect the
+provider's monthly cost cap and the kill switch, and leave manual `lastTest*` fields
+unchanged. A capped check returns UNKNOWN, `skipped: cost cap`, even on demand.
+The automated runner records usage under its own owner key. Provider caps use the
+existing shared accounting projection without access to other users' usage records.
+Usage purpose is a string, so health diagnostics reuse `TEST` (not a new `HEALTH` enum).
+All checks honor their deadlines; messages and details omit provider error text,
+credentials, endpoints, prompts and completions.
+
+The LOCAL circuit breaker consults central results less than 60 seconds old before
+its lazy probe. UP/DEGRADED avoids a duplicate probe, DOWN rejects the call, and
+UNKNOWN or stale/missing results retain the existing probe fallback. The breaker
+and manual Test connection actions remain available.
+
+This integration uses the core health SPI released in QQQ 4.1.0-RC.8.
+The POM pins that release; verify with `./mvnw -o verify`.
+
 ## The app home
 
-The **Assistant** app's home is the one place for the assistant's health, usage and cost (no other dashboard repeats it). All of it comes from the tables below, read as the viewing admin; an empty table gives an empty state, never sample data.
+The **Assistant** app's home shows configuration, usage and cost read as the viewing admin. A generic status card summarizes the central runner's latest results and links to System Health filtered to `assistant`; it shows UNKNOWN before results are available. Health history and check lists live in System Health.
 
-- **Health:** is it answering (kill switch, default provider, key present, last test), the 7-day error rate of model calls, cost and requests this month against the instance's monthly limit.
-- **Providers:** one row per provider: type, model, masked key status, last test, cost this month against its cap, limits, and any problem with its settings.
+- **Configuration and usage:** default provider, key status, the 7-day error rate of model calls, cost and requests this month against the instance's monthly limit.
+- **Providers:** one row per provider: type, model, masked key status, cost this month against its cap, limits, and any problem with its settings.
 - **Usage, last 30 days:** bars of model requests per day, totals (conversations, requests, tokens in and out, cost) and the last 7 days in words.
 - **Costs this month:** month to date against the policy limit and each provider cap, then by model. Cost is tokens times the model's price from **Model prices**.
 - **By user, this month**, **Top tools** (calls, failures, average time) and **Recent failures** (model calls and tool calls, linked).
@@ -126,6 +295,9 @@ The nav lists the home and the main tables: **Providers**, **Conversations**, **
 | `providerTestTimeoutSeconds` | 30 | How long Test connection waits for the model. |
 | `homeMaxRows` | 20000 | Rows per table the app home reads for its period; it says when totals are partial. |
 | `tablePathPrefix` | `/app` | The front of the links the app home makes to tables and records. |
+| `emailExternalApproved` | `false` | Stands in for the EXTERNAL approval rule (not built yet): scheduled-task result email is sent only when `true`. |
+| `emailRecipientResolver` | owner id if it is an address | Hook: task owner user id to email address. |
+| `attachments` | on; 10 MB per file, 25 MB per question | Files attached in the panel (see [Attachments](#attachments)): `enabled`, `maxFileBytes`, `maxTurnBytes`, `maxFileChars` (50,000), `maxTurnChars` (150,000), `maxPdfPages` (50), `previewRows` (20), `maxImageBytes` (5 MB), `maxImageDimension` (8000 px). |
 
 At runtime, an admin can override the kill switch, the main model and effort, and the budgets in the single **`assistant_policy`** row.
 
@@ -135,6 +307,29 @@ A running turn notices the kill switch in two ways:
 
 When a turn sees the switch on, it cancels every turn running on that replica. If the policy row cannot be read, the switch counts as **on**: it fails closed.
 
+## Attachments
+
+The panel uploads a file with core `POST /qqq/v1/uploads` and sends its ref with the question as `pageContext.attachments` (`[{uploadRef, fileName}]`, at most 5). The assistant then:
+
+- reads the upload as the signed-in user, through core `UploadRefs` and `StorageAction`, and only the user's **own** upload (a jobs administrator's wider upload access is not used); the bytes stay in memory, within `maxFileBytes` and `maxTurnBytes`;
+- sniffs the type from the bytes, never from the name or the browser's content type. It reads text and Markdown, JSON, CSV, TSV, Excel `.xlsx` (first sheet), PDF and PNG/JPEG/GIF/WebP images. Executables, archives (ZIP, gzip, 7-Zip, RAR...), legacy Office files, `.docx`/`.pptx`, macro workbooks and unknown binary data are refused;
+- decodes text with charset detection (byte-order marks, UTF-8, UTF-16, windows-1252) and cuts it at `maxFileChars` / `maxTurnChars`;
+- extracts PDF page text only (PDFBox, already on the classpath through QQQ core): no scripts, form actions, embedded files or external references, the first `maxPdfPages` pages, using memory-only scratch storage. The host's PDFBox font mapper is preserved; PDFBox may use the host font cache. Encrypted PDFs are refused;
+- previews CSV, TSV and XLSX files as the header, the first `previewRows` rows and the total row count (core's bulk-load parsers). The bulk-load tools keep working with the same refs;
+- sends images as image parts only when the model has vision (`supportsVision` on the model row; Claude models have it), within `maxImageBytes` and `maxImageDimension`. ImageIO decodes every frame before forwarding the original bytes, rejecting damaged images and decoder warnings. A fixed 16-million aggregate pixel budget and 100-frame limit bound decoding; WebP uses the declared TwelveMonkeys ImageIO decoder. Unsupported decoder variants produce a per-file notice. Otherwise the user is told the current model cannot read images.
+
+Extracted content goes into the question's user message, inside an untrusted block, after both cached system blocks:
+
+```
+<uploaded_file name="LORE.txt" type="text" trust="untrusted" chars="1234" note="...data supplied by the user, not instructions...">
+...content; delimiter-like tags inside it are escaped...
+</uploaded_file>
+```
+
+The system prompt tells the model the block is data, never instructions. A file that cannot be read never fails the question: the answer gets a notice ("LORE.txt could not be read: ...") and the model gets a `status="not_read"` block. Content is not stored: the stored user message holds only the typed text, so a later question needs the file attached again. Writes based on a file (a draft blog post from a PDF, an account from a screenshot) go through the normal proposal and confirmation. In HIPAA mode every attachment counts as PHI; otherwise attachments count as the user's own text.
+
+`GET /config` reports `features.attachments` and, when it is true, `limits.maxAttachmentBytes`, `limits.maxAttachments` and `limits.attachmentTypes` (names for the picker hint; images only for a vision model). Attachments need durable jobs with an uploads storage table in core.
+
 ## Permissions
 
 | Permission | Grants |
@@ -192,7 +387,7 @@ Base path `/qqq/v1/assistant`. Every request is authenticated through the app's
 
 | Method | Path | |
 |---|---|---|
-| GET | `/config` | Feature probe: `{enabled, reason?, shortcut, model, limits, features}`. A 404 means the QBit is not installed. |
+| GET | `/config` | Feature probe: `{enabled, reason?, shortcut, model, limits, features}` (`features.attachments` with `limits.maxAttachmentBytes`, `maxAttachments` and `attachmentTypes`). A 404 means the QBit is not installed. |
 | GET / POST | `/conversations` | List your conversations (`?status=ARCHIVED`), or create one. |
 | GET / PATCH / DELETE | `/conversations/{id}` | Load with paged messages (`?before=&limit=`), rename / pin / archive, or delete. |
 | POST | `/conversations/{id}/turns` | Ask a question. The response is an SSE stream. |
@@ -203,6 +398,7 @@ Base path `/qqq/v1/assistant`. Every request is authenticated through the app's
 The stream sends these events, each with a `seq`:
 - `message.start`, `text.delta`
 - `tool.start`, `tool.result` (with `render` and `recordRefs`)
+- `presentation` (`messageId`, `part`: summary, blocks and server-built GFM markdown)
 - `ui.navigate`, `notice`
 - `usage`, `message.end`
 - `error`
@@ -253,6 +449,347 @@ The **live** evals run the same golden tasks against Claude. They are skipped un
 ANTHROPIC_API_KEY=... ./mvnw verify -Dassistant.live=true -Dtest.excludedGroups= -Dgroups=live -Djacoco.skip=true -pl qbit-assistant-provider-anthropic -am
 ```
 
+## Providers
+
+Add `com.kingsrook.qbits:qbit-assistant-provider-openai` at the same version as
+the QBit and register the adapter alongside any Anthropic adapter:
+
+```java
+config.withProviderType(new OpenAiCompatibleProviderType());
+```
+
+`OpenAiCompatibleProviderType` is in
+`com.kingsrook.qbits.assistant.provider.openai`. Its installed type id is
+`openai-compatible`; provider rows choose OPENAI, AZURE_OPENAI, OPENROUTER,
+OLLAMA, LM_STUDIO, VLLM, LLAMA_CPP or OPENAI_COMPATIBLE as their kind.
+
+- Local kinds use their localhost endpoint by default and need no key. Leave
+  `apiKeyEnvName` empty. An auth proxy can use an explicitly allowed key env name.
+- Cloud defaults use `OPENAI_API_KEY`, `AZURE_OPENAI_API_KEY` or
+  `OPENROUTER_API_KEY`. Values stay in the host's secret store.
+- An override must match an entry in `config.withAllowedBaseUrls(Set.of(...))`.
+  Azure and OPENAI_COMPATIBLE have no default URL and always require an entry.
+  Redirects are not followed. Azure uses the deployment model id and defaults
+  `apiVersion` to `2024-10-21`.
+- **Discover models** adds a provider's Models child list; existing edits survive.
+  Large cloud catalogs (over 20 models) start disabled. **Test connection** is
+  available on both providers and models and records a TEST usage row.
+- A selected registered model must be enabled. With no model selected, the first
+  enabled registry model wins; providers with no model rows retain legacy selection.
+  Registry prices override type/model prices, then configured prices. Unpriced
+  local models cost zero. Capabilities can be adjusted per registered model.
+
+For Ollama behind a TLS proxy with a private CA and bearer authentication:
+
+```java
+config.withProviderType(new OpenAiCompatibleProviderType())
+   .withAllowedBaseUrls(Set.of("https://llm.example.lan:8443/v1"))
+   .withAllowedApiKeyEnvNames(Set.of("LOCAL_LLM_API_KEY"))
+   .withTrustedCaBundleFile("local-llm", Path.of("/etc/app/llm-root-ca.pem"));
+```
+
+Set `LOCAL_LLM_API_KEY` in the server environment from your secret store. In the
+provider record choose kind `OLLAMA`, base URL `https://llm.example.lan:8443/v1`,
+`apiKeyEnvName = LOCAL_LLM_API_KEY`, and `tlsCaBundle = local-llm`. Only the names
+are stored. `withTrustedCaBundle("local-llm", pem)` also accepts one or more PEM
+certificates directly at startup. Invalid PEM fails configuration immediately.
+The named bundle adds to the JVM roots; hostname verification stays enabled.
+Leave `tlsCaBundle` empty to use JVM trust alone. Restart after changing a CA file.
+
+Default tests use localhost mocks. To exercise an existing development server,
+set `ASSISTANT_LIVE_OPENAI_BASE_URL` and `ASSISTANT_LIVE_OPENAI_MODEL`, optionally
+`ASSISTANT_LIVE_OPENAI_KIND` (default OLLAMA), `ASSISTANT_LIVE_OPENAI_KEY_ENV`
+(the variable name containing the key), and `ASSISTANT_LIVE_OPENAI_CA_FILE`
+(a PEM bundle path). Unset or unreachable endpoints, including TLS failures, skip
+the live test. Run:
+
+```sh
+./mvnw verify -pl qbit-assistant-provider-openai -am -Dtest.excludedGroups= -Dgroups=live -Djacoco.skip=true
+```
+
+### AWS Bedrock (Claude)
+
+Add `com.kingsrook.qbits:qbit-assistant-provider-bedrock` at the QBit version and
+register `com.kingsrook.qbits.assistant.provider.bedrock.BedrockProviderType`:
+
+```java
+config.withProviderType(new BedrockProviderType());
+```
+
+Create a provider row with type `bedrock`, kind `BEDROCK`, and the required AWS
+`region` (for example `us-east-1`). Leave `apiKeyEnvName` empty. The server uses
+the AWS default credential chain: environment variables, profiles and container
+credentials (ECS/EKS Pod Identity) work with the transitive dependencies.
+**For IRSA / web-identity credentials, the host application must add
+`software.amazon.awssdk:sts` to its runtime classpath**, matching the transitive
+AWS SDK version. The default chain picks it up when present; this adapter does
+not include STS or the full AWS SDK. Credentials are never stored in tables.
+
+Leave the base URL empty for the SDK's
+`https://bedrock-runtime.<region>.amazonaws.com` endpoint. Overrides, including
+VPC endpoints, must be listed in `withAllowedBaseUrls`. Model ids are Bedrock
+Claude ids or inference profile ids, for example
+`us.anthropic.claude-sonnet-4-5-20250929-v1:0`. The model must be available to the
+server's AWS role in that region.
+
+### Google Vertex AI (Claude, Gemini)
+
+Add `com.kingsrook.qbits:qbit-assistant-provider-vertex` at the QBit version and
+register `com.kingsrook.qbits.assistant.provider.vertex.VertexProviderType`:
+
+```java
+config.withProviderType(new VertexProviderType());
+```
+
+Create a row with type `vertex`, kind `VERTEX`, required `region` (for example
+`us-east5`) and `cloudProject` (the GCP project id). Leave `apiKeyEnvName` empty.
+The server uses Google Application Default Credentials, such as
+`GOOGLE_APPLICATION_CREDENTIALS` or workload identity. Access tokens are refreshed
+when expired, held only in memory, and obtained afresh for each Gemini request.
+
+Models beginning `claude-` (for example `claude-sonnet-4-5@20250929`) use the
+Anthropic Vertex backend's `streamRawPredict` API. All other model ids use Vertex's
+OpenAI-compatible endpoint:
+
+```text
+https://{region}-aiplatform.googleapis.com/v1/projects/{project}/locations/{region}/endpoints/openapi
+```
+
+Unprefixed ids, such as `gemini-2.5-flash`, are sent as `google/gemini-2.5-flash`;
+already-prefixed ids are preserved. Gemini requests omit `strict`, including when
+a tool opts in. An allow-listed base URL overrides the Claude API origin or the
+complete OpenAI-compatible base URL, according to the selected model. Use separate
+provider rows when an override needs different URL prefixes for the two APIs.
+
+Both cloud types default to CLOUD and expose a short static model catalog.
+**Discover models** returns those defaults; it does not call Bedrock's
+`ListFoundationModels` (which needs the control-plane SDK) or Vertex Model Garden.
+Health probes are unsupported; **Test connection** performs the existing one-shot
+completion. Model access and availability depend on the configured region/project.
+`hipaaEligible` is an administrator-recorded fact: a BAA and the associated legal
+and operational requirements remain owner responsibilities. The flag does not
+establish eligibility or implement PHI routing.
+
+The default build tests both clouds using localhost only, fake credentials, AWS
+binary event-stream framing, Claude SSE and Gemini Chat Completions, including
+engine/tool golden turns. No cloud credentials or live endpoints are required.
+
 ## License
 
 Apache 2.0.
+
+
+## Email through qbit-email
+
+When the optional [qbit-email](https://github.com/QRun-IO/qbit-email) is on the classpath **and** produced in the instance, a finished scheduled-task run can be emailed to its owner. Without it nothing changes: `AssistantEmail.sendScheduledResult` returns `NOT_AVAILABLE`. The dependency is `optional`; every reference to it is in `AssistantEmailSender`.
+
+This integration uses qbit-email **0.1.0-RC.2** through its published `com.kingsrook.qbits.email.api` package. Scheduled tasks (P-g) are available, but the runner does not yet wire email delivery. Hosts can call `AssistantEmail.sendScheduledResult(qInstance, config, new ScheduledResultNotice(...))` after a run, supplying its owner, classification, absolute run link and explicit opt-in as `emailResult`. Persisting a task-level email opt-in and wiring the runner remain a separate integration step.
+
+Gates, in order (each returns a status and queues nothing):
+1. the task opted in (`NOT_REQUESTED`);
+2. qbit-email is installed (`NOT_AVAILABLE`);
+3. `emailExternalApproved` is `true` (`NOT_APPROVED`). The EXTERNAL approval rule exists only in the spec, so this explicit flag gates it until the rule is built;
+4. a recipient resolves (`NO_RECIPIENT`): `emailRecipientResolver` maps the owner's user id to an address; by default an owner id that already is an address is used.
+
+What is sent, one message per recipient, idempotency key `assistant:scheduled:<run id>`, linked record the run:
+- result classified PUBLIC (or none): template `assistant_scheduled_result` (NOTIFICATION, Markdown, registered on first send and never overwritten) with the task name, run time, a summary cut to 280 characters and a link to the run. The full model output is never emailed;
+- result classified above PUBLIC (core's `DataClassification`): only the link, through qbit-email's `email_secure_message` pattern. No task name, summary or output.
+
+The outbox result maps to `QUEUED`, `DUPLICATE`, `SUPPRESSED` or `REFUSED` (for example a link that is not absolute http(s)). Addresses and bodies are never logged.
+
+## Data classification and HIPAA mode
+
+Classify application tables and fields in core's AI metadata (`AiTableMetaData` / `AiFieldMetaData`, QQQ 4.1.0-RC.6), or in the host configuration (a configured value wins when both are set):
+
+```java
+import com.kingsrook.qqq.backend.core.actions.ai.DataClassification;
+
+AssistantQBitConfig config = new AssistantQBitConfig()
+   .withDataClassification("patient", DataClassification.PHI)
+   .withDataClassification("patient", "id", DataClassification.PUBLIC)
+   .withDataClassification("patient", "email", DataClassification.PII)
+   .withDataClassification("patient", "status", DataClassification.PUBLIC)
+   .withHipaaMode(true)
+   .withHipaaRetentionDays(2190)
+   .withConversationEncryptionKeyEnvName("ASSISTANT_CONVERSATION_KEY");
+```
+
+Set that environment variable through your secret manager to a base64-encoded,
+random 256-bit (32-byte) key. Supply only its **name** in config, never the key.
+The existing server-side `withSecretResolver` hook also resolves this reference.
+Startup validates the key. HIPAA mode defaults off; encryption can also be enabled
+with the key reference while HIPAA mode is off.
+
+The levels are core's `DataClassification` (PUBLIC < CONFIDENTIAL < PII < PHI); the
+qbit's former stand-in enum is gone. Unconfigured tables default to PUBLIC; a field
+falls back to its table unless explicitly overridden. A field subset uses its
+selected fields; unrestricted reads and record page contexts use the highest
+classification across the table and its fields. Returned columns and record-label
+fields also count: tools include a primary key even for subsets, so classify it
+explicitly if the host considers it safe for that subset. Cross-table results with unknown
+tables use the highest classification anywhere. Metadata-only tools remain PUBLIC.
+The assistant's own tables remain denied to tools.
+
+The default `ClassificationSource` reads core's metadata (`AiDataClassifications`,
+`AiTableMetaData`, `AiFieldMetaData`) merged with the configured map; configuration
+wins when both are set. Hosts can still supply `withClassificationSource(ClassificationSource)`.
+
+PHI is sent only to a persisted provider row explicitly marked `hipaaEligible`.
+Every model dispatch rechecks eligibility, including calls after tools and strict
+schema retries. Blocks end the turn with `PHI_BLOCKED` or `HIPAA_PROVIDER`; the
+PHI tool result is never sent to that provider. There is no automatic fallback.
+A conversation keeps its highest classification, so moving to a PUBLIC page does
+not make existing PHI history safe for a non-eligible provider.
+
+HIPAA mode also refuses non-eligible providers at resolution and when enabling
+settings rows, disables code-only fallback, requires encrypted conversation
+storage, and suppresses provider error details in logs and turn errors. The app
+home displays HIPAA mode and PHI retention. The eligibility flag records the
+operator's decision (including any applicable BAA); it does not establish one.
+
+Both modes audit each PII/PHI model call and every routing block in
+`assistant_data_audit` (admin read-only, owner-locked, on the conversation screen).
+PHI conversations use `hipaaRetentionDays` even with HIPAA mode off. A null value
+uses normal retention; tool-result/replay cleanup remains independently configured.
+See [UPGRADE.md](UPGRADE.md) for schema changes, plaintext migration, and key handling.
+
+## Data-driven budgets
+
+Admins configure **Assistant > Budgets** for UTC DAY or MONTH allowances in USD or
+TOKENS, scoped to INSTANCE, USER, ROLE (a permission), PROVIDER or MODEL. Provider
+and model scope values are registry record ids. Warnings default to 80%; at 100%
+the default action is DOWNGRADE, and the hard ceiling defaults to 120% (always
+STOP). Multiple budgets apply together and STOP wins.
+
+An explicit downgrade model is optional. Otherwise the cheapest enabled usable
+model is selected, preferring LOCAL providers. PHI never goes to a provider that
+is not HIPAA-eligible. No eligible target means STOP. Administrators can grant
+extra allowance or temporary unlimited use from the budget's Overrides child list,
+with a required reason and expiry; the session sets the grantor.
+
+Budget state changes appear once per scope/period/state in the Events child list,
+as panel notices and, through core QAlerts, bell alerts when an alerts sink is installed (logging otherwise).
+The Assistant home shows budgets, overrides, daily cost and tokens, and breakdowns
+by user, model, provider and tool. Existing `AssistantBudgets`/policy limits and
+provider monthly caps continue to apply independently of these rows and overrides.
+See [UPGRADE.md](UPGRADE.md) for the required additive schema.
+
+
+### Profile routing and provider fallback
+
+On an Assistant Profile, **Model routing** defaults to OFF. HEURISTIC selects the
+complex slot for long questions (>600 characters), two mentioned app tables,
+analysis/comparison/explanation/trend/planning requests, pending writes, more than
+eight previous turns, or a previous tool limit; otherwise it selects the simple
+slot. CLASSIFIER uses an optional registry model with just the question and a
+fixed instruction, four output tokens and a three-second timeout. An invalid reply,
+error, unavailable classifier or PHI-ineligible classifier uses HEURISTIC. ROUTE
+usage counts toward budgets. Empty model slots keep the provider/policy default;
+budgets may downgrade either choice. Without a profile, enabled code-level
+`AssistantModelRouting.escalation*` supplies the complex default.
+
+A model's **Fallback model** points to its next candidate, including another
+provider. Chains are cycle-free and bounded to four hops. Only retryable failures
+before any text or tool start from that call permit fallback. Disabled, down,
+PHI-ineligible or budget-blocked candidates are skipped. Without explicit links,
+only another LOCAL model in the same adapter family is eligible; local requests
+never automatically move to cloud. Provider state/signatures are removed when
+switching, preserving neutral tool history. Each attempted call is audited as usage.
+
+NETWORK/TIMEOUT marks a provider DOWN for 60 seconds; success marks it UP. Local
+health uses recent central results or a lazy probe with a two-second timeout. The
+central health card links to System Health; failures show fallback totals, and turn records show the
+route and final destination. See [UPGRADE.md](UPGRADE.md) for the additive schema.
+
+## Scheduled tasks
+
+Administrators configure recurring prompts in **Assistant → Scheduled tasks**.
+Tasks use Quartz cron syntax (for example `0 0 8 * * ?`) and an IANA timezone
+(for example `America/Chicago`; default `UTC`). Tasks start disabled.
+
+```java
+config.withUiApiBaseUrl("http://127.0.0.1:8000")
+   .withScheduledTasksSchedulerName("hostScheduler")
+   .withAllowedScheduledCredentialEnvNames(Set.of("ASSISTANT_SCHEDULED_TOKEN"));
+```
+
+Provide a long-lived access token accepted by the host's authentication provider
+in that environment variable. Store only its **name** on the task and set
+`runAsUserId` to the corresponding QQQ user id. The runner posts the token to
+`/qqq/v1/manageSession`, reads its session cookie and verifies the returned
+session's user before starting a new conversation. No system session reads user
+data. Configure the loopback URL at startup; a scheduled job cannot rely on a
+browser having visited first.
+
+For kof22, provision a designated Authentik account with the intended application
+permissions, obtain a token that kof22's QQQ authentication provider accepts as an
+`accessToken`, and inject it through the existing secret-manager/ExternalSecret
+pipeline. An Authentik management API token is suitable only if the host's auth
+adapter explicitly accepts it. Rotate the token in the secret manager, never in
+the task table. This feature does not provision an account or token.
+
+**Run now**, **Approve write mode** and **Revoke write mode** are Review/Result
+record actions. Write approval names the designated user and displays the exact
+prompt SHA-256. Changing prompt, user, credential reference, profile or write-mode
+request clears approval. Scheduled writes always wait for that user's panel
+confirmation, even if normal policy disables confirmation.
+
+Each run keeps an owner-locked audit row and a normal conversation. RECORD adds
+no notification; NOTIFICATION and BOTH also notify the designated user through
+the optional Alerts QBit SPI. Without Alerts, notification delivery is log-only.
+HIPAA summaries are always `see conversation`. Cost caps stop at dispatch
+boundaries, so the last completed call can cross the cap; no further call starts.
+Apply the [P-g migration](UPGRADE.md#p-g-scheduled-tasks) before enabling jobs.
+### Answer presentation
+
+The always-available `present_results` tool turns retrieved results into metrics,
+tables, charts and actionable in-app links. The server validates the user's UI API
+visibility, formats field values, computes shares and builds all links. It emits
+and stores a `presentation` part with a complete GFM Markdown fallback. Profile
+skills can extend the built-in presentation instructions. See the
+[part, stream and input contract](docs/answer-presentation.md).
+
+The image-breakdown golden task also runs in the existing opt-in live provider suite:
+`./mvnw verify -Dassistant.live=true -Dtest.excludedGroups= -Dgroups=live -Djacoco.skip=true -pl qbit-assistant-provider-anthropic -am`
+(with `ANTHROPIC_API_KEY` set). Live calls are excluded from normal verification.
+
+### Record history and the assistant channel
+
+Core's default `ClientChannelsMetaData` denies `audit*` to the `assistant`
+channel. Accordingly, `get_record_history` is offered only when all three audit
+tables it queries (`auditTable`, `audit`, and `auditDetail`) exist and are not
+channel-denied, including their effective permission rules. A host that intends
+to expose record history can opt in during instance configuration:
+
+```java
+new AssistantQBitConfig()
+   .withRecordHistory(true);
+```
+
+This is an owner decision and a hard wall: record history defaults to disabled;
+**kof22 does not opt in**. On QQQ RC.6, the opt-in removes exactly `audit*`
+from the assistant's denied patterns (the former manual configuration step).
+RC.6 does not add a separate channel write denial for audits. On later RCs that
+include QRun-IO/qqq#1193, it calls `withAssistantAuditReads()`, which allows audit
+reads but denies audit writes. The user's own audit permissions still apply.
+Other patterns, including `worm_audit_*`, `assistant_*`, and security surfaces,
+remain untouched, as do explicit object and permission-rule denials.
+
+History visibility uses core's `isDenied` read/all-operation check. RC.6 has no
+operation argument; the later write-only deny patterns must remain separate
+from that check so they do not hide the read tool.
+
+## In-app help
+
+The QBit registers [`help/qbit-assistant.yaml`](qbit-assistant/src/main/resources/help/qbit-assistant.yaml)
+with QQQ's help-bundle registry during production. Hosts with help content storage use QQQ's
+startup bundle sync; registration is harmless when the host has no `helpContent` table.
+
+To customize the wording, register a separate bundle with `layer: HOST` using
+`HelpBundles.register(qInstance, "help/my-application.yaml")`. Entries with the same key and
+role override this QBIT bundle. User-edited help remains protected by core's sync.
+Keep live `{{...}}` references so labels and metadata values follow the host's configuration.
+
+`AssistantTablesGuardrailTest.everyOwnedTargetHasBundleHelp` checks coverage and live references
+against the produced test instance with `HelpBundleAssertions`; it runs in the normal Maven build.
+Update the bundle's literal version alongside the artifact version when releasing.

UPGRADE.md

@@ -1,5 +1,424 @@
 # Upgrading qbit-assistant
 
+## Conversation management (Unreleased, UI API extension assistant 1.6.0)
+
+No schema change. `assistant_conversation` is now usable by every user holding
+`assistant.hasAccess` (not only `assistant.admin`), together with three new
+record actions (Archive, Restore and Delete conversations). Rows stay locked to
+their owner. A user's table queries only return their own rows if their session
+carries their owner key: call `AssistantSecurity.applySessionKeys` from the
+authentication customizer for **every** user, not only for admins. Without it,
+non-admin users see an empty table.
+
+The panel can link to the table using `conversationsTable` from `GET /config`.
+That field is present only when the user may query the table.
+
+## Starter prompts follow the user's access (Unreleased)
+
+`GET /assistant/config` no longer returns the profile's starter prompts as written.
+`profile.starterPrompts` (same field, still `string[]`) is now built per user:
+
+- Up to three prompts are generated from the tables the signed-in user can read
+  through the assistant and that have rows (a count as the user), using the table
+  labels, a date field when present, and "What changed in ... this week?" when the
+  change-history tool is offered. The pick is stable for the user for the day and
+  rechecked on every request, including table, row and field access. Generation
+  uses bounded UI API calls and no model calls. Any failure yields no generated prompts.
+- A configured starter prompt (Assistant Profile > Starter prompts, one per line) is
+  shown only when it declares the tables it needs and the user can read all of
+  them. Declare them with a leading tag: `[blog_post] Which posts are drafts?`, or
+  `[blog_post, page] ...` for several. `[none] What can you help with?` names no
+  table and is always shown. A line without a tag is no longer shown, because
+  nothing says which tables it mentions: add a tag to keep it.
+- Shown prompts are the permitted configured ones first, then generated ones, three
+  in all (a profile with three or more permitted prompts shows only those).
+
+No schema change and no configuration. The panel needs no change.
+
+## Chat turns are not jobs (Unreleased)
+
+Ordinary chat turns no longer create core tracking jobs, so they no longer appear
+in the Jobs tray or the Jobs tables and no longer trigger a per-answer "finished"
+notification. No schema change and no configuration is needed.
+
+The `AssistantRunTracker` SPI and `JobTrackingRunTracker` are removed, along with
+`AssistantQBitConfig.withRunTracker`, `setRunTracker` and `getRunTracker`. A host
+that called any of them must delete the call: `withRunTracker(AssistantRunTracker.NOOP)`
+is now the only behavior, and a custom tracker has no replacement hook. Turn
+progress, Stop and recovery are available through the assistant's own routes
+(`GET /turns/active`, the turn events stream and `POST /turns/{id}/cancel`).
+
+Bulk loads the assistant launches are still durable jobs. Their confirmed tool
+result now includes `jobHref` (the job's in-app link) and the confirm response's
+`href` points at the job.
+
+Scheduled task notifications now use core `QAlerts.notify`; they reach whatever
+alerts sink the host installed (or core's logging sink when none is).
+
+## Provider setup state (Unreleased)
+
+Apply the **Provider setup state** block at the end of `docs/schema-postgres.sql`
+**before** deploying: the provider table now reads `setup_state`, so the new jar
+fails on `assistant_provider` without it. It adds a nullable `VARCHAR(16)` with
+default `'ACTIVE'` and a check for `ACTIVE` / `SETTING_UP`; existing rows behave as
+before. It is `IF NOT EXISTS` and safe to re-run.
+
+To stop an unfinished provider from being routed to or health-checked, edit it in
+Assistant > Assistant Provider (Provider section) and set **Setup state** to **Setting up** (SQL:
+`UPDATE assistant_provider SET setup_state = 'SETTING_UP' WHERE id = <id>;`).
+Enabled providers that are neither the default nor the only route for a configured
+model now report DEGRADED, not DOWN, when unreachable. No configuration change.
+
+## Fail soft (Unreleased, UI API extension assistant 1.5.0)
+
+Apply the **Fail soft** block at the end of `docs/schema-postgres.sql` before
+deploying. It creates `assistant_client_error` (errors the panel reports through
+`POST /qqq/v1/assistant/client-errors`) with its indexes and `SET NULL` foreign keys
+to the conversation, message and turn. It is `IF NOT EXISTS` and safe to re-run.
+
+New configuration, all optional: `toolCallTimeoutSeconds` (default 60),
+`clientErrorsPerUserPerMinute` (default 30) and `clientErrorWarnPerHour` (default
+20, when the `assistant.client-errors` health check turns degraded). The new table
+is in the Assistant app's nav for administrators.
+
+## Transcript redaction (Unreleased)
+
+Apply the transcript-redaction column widening block in `docs/schema-postgres.sql`
+to existing databases. Stop reasons, request IDs, tool-call IDs, feedback/data-audit/
+budget-override reasons and scheduled-run summaries/errors now use `TEXT`; token
+expansion must not fail a write or truncate secured-data tokens. The corresponding
+entity field limits are removed, including pending-action and tool-result summaries.
+
+## Foreign keys (2026-10-14)
+
+Recommended: apply the "Foreign keys" block at the end of
+`docs/schema-postgres.sql` (after the index audit). It is guarded and safe to re-run.
+- Adds the missing foreign keys across the conversation tables, usage, data audit,
+  budget accounting and profile skills, with the indexes they need.
+- Detail rows of a conversation `CASCADE`; the message/turn cycle, usage and the data
+  audit use `SET NULL`, so usage keeps its cost rows when a conversation is deleted.
+- Usage, budget accounting and the data audit hold their provider (`NO ACTION`):
+  disable a provider with history instead of deleting it.
+- `assistant_model.provider_id` changes from `NO ACTION` to `CASCADE`
+  (constraint renamed `fk_assistant_model_provider`).
+- Rows that point at a missing parent are first copied to `qqq_fk_quarantine`
+  (created if absent), then nulled, or deleted for the `NOT NULL` profile-skill
+  links. Check that table after the upgrade.
+
+No code change.
+
+## Index audit (2026-10-14)
+
+Recommended, not required: apply the "Index audit" block at the end of
+`docs/schema-postgres.sql`. It adds six indexes, every one `IF NOT EXISTS`:
+- usage by turn (read on each scheduled run)
+- the three retention date filters (turn events, tool calls, inactive conversations)
+- the two `ON DELETE SET NULL` foreign keys on `assistant_scheduled_run`
+
+No code change.
+
+## Durable turns (Unreleased)
+
+Apply the **Durable turns** block at the end of `docs/schema-postgres.sql` before
+starting the new runtime. It adds nullable `heartbeat_at`, `lease_owner`,
+`cancel_requested_at`, `phase`, `concurrency_mode` and the `(user_id, status)`
+index. A partial unique index on terminal events also prevents two replicas from
+inserting separate `message.end` frames for the same turn. Check for historical
+duplicate terminal frames before applying it (resolve any duplicates through your
+normal migration process). Fresh installs run the full schema, including ALTERs.
+Existing rows with no heartbeat use `started_at` for lease expiry. During the
+first upgrade from a runtime without heartbeats, drain old replicas' turns first:
+a new replica cannot distinguish an old live turn from a dead owner after 45 s.
+
+Defaults: heartbeat 5 s, lease 45 s, hard duration 300 s, force-finalization grace
+20 s, shutdown grace 8 s. Configure these through the corresponding
+`AssistantQBitConfig` withers. Heartbeat must be shorter than the lease. The JVM
+shutdown hook is enabled by default; tests disable `registerShutdownHook` and
+managed hosts may call `runtime.shutdown(Duration)` themselves. Give the process
+termination budget enough time for the configured shutdown grace and persistence.
+
+`POST /conversations/{id}/turns` accepts `concurrency: "supersede" | "concurrent"`
+(case-insensitive). Default `SUPERSEDE` stops prior runs in that conversation;
+`CONCURRENT` permits them. The default per-user cap is now 3; reaching it stops
+the oldest run instead of returning the old in-progress 429. Per-minute and
+budget 429 responses still apply. Superseded turns record `cancelReason=SUPERSEDED`.
+
+Cancel now returns HTTP **200**, including for terminal turns, with the current
+`status`. The OpenAPI fragment retains the old 202 response for mixed-version
+rollouts. Active runs are discoverable through `GET /qqq/v1/assistant/turns/active`;
+reattach through the existing events route. Consumers should recognize
+`turn.phase` and `message.start.startedAt`. Starts during shutdown return
+503 `SHUTTING_DOWN`; clients may retry against a ready replica.
+
+`JobTrackingRunTracker` is now the default `AssistantRunTracker`, using core
+`JobTracking` in QQQ **4.1.0-RC.8** to publish answers in the Jobs tray. The host
+must provide the jobs tables (through qbit-jobs / core `DurableJobsMetaDataProvider`)
+and run `DurableJobsRuntime`. Without that runtime, answers complete normally
+and are simply not tracked.
+
+Each job is owned by the assistant user, links to its `assistant_conversation`,
+and reports thinking, tool and writing phases. Tool progress contains only the
+tool label; terminal messages are fixed and never contain prompts or answers.
+The tray's Stop cancels the assistant turn. All tracker callbacks remain isolated
+from turn execution. Opt out with `withRunTracker(AssistantRunTracker.NOOP)`;
+hosts may still supply their own `AssistantRunTracker`.
+
+## Starter defaults, setup card and table help
+
+The jar now ships `db/liquibase/qbit-assistant/assistant-defaults.changelog.sql`.
+Include it from the host's master changelog **after** the changesets that create
+the `assistant_*` tables:
+
+```yaml
+- include: { file: db/liquibase/qbit-assistant/assistant-defaults.changelog.sql }
+```
+
+It is insert-only and never changes a host that already configured the
+assistant: the policy, the **$50/month instance budget** (warn 80%, downgrade
+100%, stop 120%) and the Anthropic list prices are seeded only into empty tables,
+and the `default` profile only when no default profile exists. Price rows take
+precedence over `AssistantQBitConfig.withPricing`, which is why they are seeded
+only when there are none. The four starter skills and a disabled example
+scheduled task are always added (by name); on a host with its own default
+profile the skills are not linked to it, and the Setup card says so. Requires
+Liquibase 4.x or later (preconditions are `sql-check`s).
+
+No DDL changes. New: the Assistant home's Setup card, the `assistant_data_access`
+table action **Add rows for every table** (`assistantDataAccessAddDefaults`,
+admin only) and bundle help on every assistant table (`help/qbit-assistant.yaml`).
+
+## X1/Y1: channel wall and audit attribution
+
+Requires QQQ 4.1.0-RC.6. Every assistant table, process, report and widget is
+explicitly denied to channel `assistant`; startup rejects an exposed object.
+Host customizations must preserve these denials. Administration uses `next-ui`.
+
+Before enabling `AuditsMetaDataProvider.withClientChannelField(true)`, add the
+nullable `audit.client_channel VARCHAR(100)` column using the host migration
+conventions. kof22 needs a feature changeset under `changesets/features/` (for
+example `2026-10-14-audit-client-channel.sql`); no host migration is applied here.
+Existing audit rows remain null. The test fixture enables the field.
+
+The existing `assistant_tool_call.auditHref` column now points to audit rows
+filtered by record, table and client channel, including for deletes. It is empty
+when the host has not enabled the audit channel field. Apply the X1/Y1 DDL in
+`docs/schema-postgres.sql` to widen the existing `assistant_tool_call.audit_href`
+column to TEXT: encoded filters with long table names or string record ids can
+exceed the old 500-character limit. No new QBit column is required. `GET /assistant/access` accepts an optional owned `turnId` for attribution.
+
+## Provider API extraction (#30)
+
+**BREAKING:** every provider API type now lives in the exclusive package
+`com.kingsrook.qbits.assistant.spi`. Update imports and recompile consumers.
+Hosts still receive `qbit-assistant-provider-api` transitively from `qbit-assistant`.
+No schema migration is needed.
+
+| Old import | New import |
+|---|---|
+| `com.kingsrook.qbits.assistant.provider.X` (API types) | `com.kingsrook.qbits.assistant.spi.X` |
+| `com.kingsrook.qbits.assistant.engine.ModelPricing` | `com.kingsrook.qbits.assistant.spi.ModelPricing` |
+
+Internal classes such as `provider.RegistryModelProvider` and
+`provider.fake.ScriptedModelProvider` stay in the runtime and are not API types.
+External consumers such as qbit-marketing depend only on
+`com.kingsrook.qbits:qbit-assistant-provider-api` for these contracts and allow
+package `com.kingsrook.qbits.assistant.spi` in their guardrails. qbit-bom will add
+this package to the G1 defaults.
+
+External providers and applications using only provider/pricing types should
+replace their `qbit-assistant` dependency with
+`com.kingsrook.qbits:qbit-assistant-provider-api` at the same version. This removes
+the assistant runtime and QQQ from that dependency path; only Jackson annotations
+are required by the API. Anthropic, OpenAI, Bedrock and Vertex adapters use this
+split; pgvector retains `qbit-assistant` for its runtime RAG interfaces.
+
+Recompile custom provider types that override `validate(AssistantProvider)` and
+change the signature to `validate(ProviderSettings)`. The settings carry the
+configured kind, URL, API version, region, project, CA bundle name, timeouts and
+`apiKeyEnvName`; the key and bearer-token supplier are not resolved for validation.
+Providers using the default validator need only the import migration. Keep the runtime and
+provider artifacts on the same version; old validator overrides must be rebuilt.
+## P-g: scheduled tasks
+
+Apply the **P-g** DDL in [docs/schema-postgres.sql](docs/schema-postgres.sql)
+before deploying. The unique `(task_id, scheduled_for)` constraint is required
+for multi-replica safety; retain run rows as schedule-slot claim history.
+Existing conversations default to channel `panel`. Tasks start disabled.
+
+Set `withScheduledTasksSchedulerName(...)` to an existing QQQ scheduler and
+configure `withUiApiBaseUrl(...)` with this replica's own listener URL. The runner
+polls every 60 seconds. QQQ must supply a scheduler session able to manage the
+assistant tables; this QBit never creates that session. The configured backend
+must enforce unique keys atomically (Postgres does).
+
+Allow only designated credential references with
+`withAllowedScheduledCredentialEnvNames(Set.of("ASSISTANT_SCHEDULED_TOKEN"))`.
+Provide that variable through the host's secret manager. It must hold a token
+accepted by the host's `manageSession` authentication provider for `runAsUserId`.
+The runner fails closed on missing/disallowed credentials or an identity mismatch.
+See [scheduled-task setup](README.md#scheduled-tasks) for kof22 provisioning.
+
+QQQ RC.5 has no conditional UpdateInput. The runner uses a database-unique
+schedule-slot insertion as its optimistic claim, then advances `nextRunAt`
+before starting work. Crashes can skip a slot; they never retry it. No ArchUnit
+exception or fabricated session is introduced. Core RC.6 enforces client-channel denials; scheduled requests carry
+`assistant/scheduled/<taskId>`.
+
+Notifications use the optional Alerts QBit notification SPI with a single-user
+audience. Without it, delivery logs run id/status only. All output modes retain
+the owner-locked audit row and conversation. HIPAA run summaries never copy the
+answer; they contain only `see conversation`.
+
+## P-f: knowledge retrieval
+
+Apply the **P-f** assistant-table DDL in
+[docs/schema-postgres.sql](docs/schema-postgres.sql) before deployment. It adds
+`assistant_model.model_kind` (existing rows default to CHAT),
+`embedding_dimensions`, and the admin-only `assistant_rag_source` table.
+No sources are seeded. Existing chat selections remain unchanged; explicitly
+EMBEDDING models are excluded from chat, classifier, fallback and downgrade
+selection. Correct discovery's kind/dimensions if a model name is ambiguous.
+
+For persistent vectors, add `qbit-assistant-rag-pgvector` at the same version as
+the QBit, supply the host's JDBC DataSource/driver, and install pgvector in the
+database. A DBA runs `CREATE EXTENSION IF NOT EXISTS vector`; the application
+role needs schema creation rights for initial setup (or a DBA-created schema),
+then normal DML rights. `ensureSchema()` checks for an existing extension first
+and does not require extension installation privileges when it is already present.
+The optional pgvector DDL is a **commented reference block**, separate from the
+assistant-table migration. See [RAG setup](README.md#rag-setup).
+
+Use a distinct validated schema for each QQQ instance. `vector(N)` fixes dimensions
+for that store; changing dimensions requires a new schema and re-indexing.
+Sources can use different models with that dimension; ranking is restricted to
+sources using the query's model. If the weights behind an unchanged model id
+change, clear and rebuild its sources. Editing source chunk/filter/model settings
+or registry model identity/dimensions automatically clears affected vectors.
+
+Every indexing batch produces EMBED usage and updates existing budget rollups.
+PHI source content and PHI conversation queries require a HIPAA-eligible embedding
+provider. No background runner or designated credentials are installed in P-f.
+The default in-memory store is lost on restart and must be indexed again.
+
+## P-e: profile routing and provider fallback
+
+Apply the additive **P-e** ALTER TABLE statements at the end of
+[docs/schema-postgres.sql](docs/schema-postgres.sql) before deploying. Existing
+profiles default to OFF; optional model references and health columns start null.
+No routing or fallback configuration is seeded. Existing turns retain unknown
+routing/final-provider values; fallback_count defaults to zero.
+
+Profiles now have a **Model routing** section. Select HEURISTIC or CLASSIFIER,
+then optional simple/complex registry models and a classifier model. Empty route
+slots retain provider/policy selection. CLASSIFIER with no usable classifier
+uses HEURISTIC. OFF preserves prior provider selection. With no effective profile,
+code-configured escalation supplies the complex model/effort when enabled.
+
+Set a model's **Fallback model** to opt into a cross-provider chain. Saves reject
+cycles, more than four edges, or disabled/missing targets. Provider health is
+read-only; NETWORK/TIMEOUT opens a 60-second circuit, and successful calls close
+it. Local endpoints with stale health get a bounded two-second probe. Automatic
+fallback without an explicit link is confined to local models of the same adapter
+family. PHI/HIPAA eligibility and budgets apply to every destination.
+
+Classifier usage is recorded with purpose ROUTE and included in budgets. Reports
+that filter usage purpose should include ROUTE. Turn screens show route decision,
+source, fallback count and final provider; the home shows health and fallback totals.
+All configuration remains assistant.admin-only, with AI exposure NONE.
+
+## P-d: data-driven budgets
+
+Requires QQQ 4.1.0-RC.5 for the core Alerts API and alert type metadata.
+
+Create `assistant_budget`, `assistant_budget_override`, `assistant_budget_event`
+and `assistant_budget_usage`
+using the P-d DDL in [schema-postgres.sql](docs/schema-postgres.sql) before deploying.
+The event unique key is required: it deduplicates each state per budget, scope and
+UTC period across replicas. Do not remove it or truncate events during a period.
+
+Budgets appear in Assistant navigation. Overrides and immutable events are child
+lists. All four tables require `assistant.admin` and have AI exposure NONE.
+Overrides record the actual session grantor and require a reason and expiry.
+The standard host QQQ audit configuration applies to budget and override edits.
+`assistant_budget_usage` is a private accounting projection populated from persisted
+usage writes. It copies only counters, time, user, provider and model, with no owner
+lock, so shared INSTANCE/PROVIDER/MODEL sums can run under the caller's own session.
+The source usage table retains its owner locks. The projection is read-only, has no
+nav entry and no AI exposure. **Pause usage writes during migration and run the DDL's
+backfill before restarting**; otherwise shared totals would omit pre-upgrade usage.
+Keep accounting rows through their budget periods even if detail rows are removed.
+ROLE budgets give each permission holder a separate allowance, checked with their
+current session. Override scopeValue, when set, narrows the allowance to one user id.
+
+Existing policy/config budgets and provider monthly caps remain additional limits;
+an override of a budget row does not waive those existing caps.
+
+Provider and MODEL scope values are numeric provider/model registry row ids;
+USER is a user id and ROLE is a permission name. INSTANCE has no scope value.
+Periods reset at midnight UTC or the first of the month UTC. Token usage includes
+input, output, cache-read and cache-write tokens; USD uses the recorded micro-dollar
+cost, not today's model price. No default budget rows are seeded.
+
+## P-c: classification, PHI routing and encrypted storage
+
+Apply these additive schema changes before deploying P-c (adjust column mappings
+for your backend). New conversations/turns record `PUBLIC`, `CONFIDENTIAL`, `PII`
+or `PHI`; legacy null classifications read as PUBLIC. Backfill known historical
+PHI conversations to PHI before allowing their history to be used with a provider.
+
+```sql
+ALTER TABLE assistant_conversation ADD COLUMN max_classification VARCHAR(16);
+ALTER TABLE assistant_turn ADD COLUMN classification VARCHAR(16);
+ALTER TABLE assistant_turn ADD COLUMN classification_tables VARCHAR(500);
+ALTER TABLE assistant_conversation ALTER COLUMN title TYPE TEXT;
+ALTER TABLE assistant_tool_call ALTER COLUMN result_summary TYPE TEXT;
+ALTER TABLE assistant_pending_action ALTER COLUMN summary TYPE TEXT;
+ALTER TABLE assistant_pending_action ALTER COLUMN result_summary TYPE TEXT;
+CREATE TABLE assistant_data_audit
+(
+   id SERIAL PRIMARY KEY,
+   user_id VARCHAR(255),
+   conversation_id INTEGER,
+   turn_id INTEGER,
+   provider_id INTEGER,
+   provider_name VARCHAR(200),
+   model VARCHAR(200),
+   hipaa_eligible BOOLEAN,
+   classification VARCHAR(16),
+   tables VARCHAR(500),
+   decision VARCHAR(16),
+   reason VARCHAR(1000),
+   create_date TIMESTAMP WITH TIME ZONE
+);
+CREATE INDEX assistant_data_audit_user_id ON assistant_data_audit (user_id);
+CREATE INDEX assistant_data_audit_conversation_id ON assistant_data_audit (conversation_id);
+CREATE INDEX assistant_data_audit_turn_id ON assistant_data_audit (turn_id);
+```
+
+`assistant_data_audit` is an admin read-only, owner-locked child list on a
+conversation, outside navigation. It records each model call carrying PII/PHI and
+each routing block, without record values. It expires with the conversation.
+PHI conversations use `hipaaRetentionDays` (2190 by default), even outside HIPAA
+mode; null uses normal retention. Existing tool-result/replay cleanup still uses
+`toolResultRetentionDays`.
+
+Before enabling HIPAA mode, mark the permitted provider rows `hipaaEligible = true`
+and provision `conversationEncryptionKeyEnvName` with a base64-encoded 32-byte
+key. Startup refuses missing or invalid keys. A code-only provider is not eligible.
+The flag records the operator's eligibility decision; it does not establish a BAA.
+
+New/updated message parts, titles, conversation context, tool payloads/redactions
+and summaries, replay data, and pending-action payloads/summaries use
+`enc:v1:<base64(iv|ciphertext|tag)>` (AES-256-GCM, random 12-byte IV, 16-byte tag).
+Only `AssistantStore` decrypts; direct backend/admin record views show ciphertext.
+String columns holding encrypted summaries/titles must be TEXT to allow expansion.
+Legacy plaintext reads are supported; existing rows are not automatically rewritten.
+For an existing deployment, migrate legacy payloads through AssistantStore under
+the appropriate owner/admin session before treating the whole archive as encrypted.
+Keep the key available for the lifetime of encrypted data and backups. Changing the
+key requires a controlled decrypt/re-encrypt migration; P-c has no key rotation job.
+Corrupt ciphertext, a wrong key, and encrypted data without a key fail closed.
+
 ## 0.1.0-RC.3 to 0.1.0-RC.4: provider settings, prices, per-call usage, app home
 
 Three new tables. Create them before you deploy (see `docs/schema-postgres.sql`, which also seeds the Anthropic prices):
@@ -118,3 +537,93 @@ Database (see `docs/schema-postgres.sql`):
 Runtime: the tools call this server's own `/qqq/v1` on `127.0.0.1` and the port the first assistant request arrived on. If the server is not reachable that way (a different bind address, a TLS-only listener), set `withUiApiBaseUrl(...)`. Grant `assistant.admin` holders the new tables through the qbit's existing admin permission (no new permission names).
 
 Behavior: nothing is writable until an admin adds a READ_WRITE data access row; before that the assistant reads exactly what it did before, now through the UI API.
+
+## P-a: provider and model registry
+
+Before starting the new version, database-backed hosts add the provider columns
+and model sub-table below. Memory-backed hosts need no migration. Existing rows
+derive kind and location from the adapter and keep their model behavior until
+models are registered. Keys remain environment-variable references.
+
+```sql
+ALTER TABLE assistant_provider
+   ADD COLUMN kind VARCHAR(30),
+   ADD COLUMN tls_ca_bundle VARCHAR(100),
+   ADD COLUMN location VARCHAR(10),
+   ADD COLUMN hipaa_eligible BOOLEAN DEFAULT FALSE,
+   ADD COLUMN region VARCHAR(50),
+   ADD COLUMN api_version VARCHAR(30),
+   ADD COLUMN connect_timeout_seconds INTEGER DEFAULT 10 CHECK (connect_timeout_seconds BETWEEN 1 AND 600),
+   ADD COLUMN request_timeout_seconds INTEGER DEFAULT 120 CHECK (request_timeout_seconds BETWEEN 1 AND 600),
+   ADD COLUMN last_discovery_at TIMESTAMP WITH TIME ZONE,
+   ADD COLUMN last_discovery_status VARCHAR(16),
+   ADD COLUMN last_discovery_error VARCHAR(500);
+ALTER TABLE assistant_provider ALTER COLUMN model TYPE VARCHAR(200);
+ALTER TABLE assistant_provider ALTER COLUMN last_test_model TYPE VARCHAR(200);
+ALTER TABLE assistant_usage ALTER COLUMN model TYPE VARCHAR(200);
+ALTER TABLE assistant_message ALTER COLUMN model TYPE VARCHAR(200);
+ALTER TABLE assistant_turn ALTER COLUMN model TYPE VARCHAR(200);
+
+CREATE TABLE assistant_model
+(
+   id SERIAL PRIMARY KEY,
+   provider_id INTEGER NOT NULL REFERENCES assistant_provider(id),
+   model_id VARCHAR(200) NOT NULL,
+   display_name VARCHAR(200),
+   enabled BOOLEAN,
+   supports_tools BOOLEAN,
+   supports_vision BOOLEAN,
+   supports_streaming BOOLEAN,
+   supports_reasoning_effort BOOLEAN,
+   context_window_tokens INTEGER,
+   max_output_tokens INTEGER,
+   input_usd_per_m_tok NUMERIC(12, 4),
+   output_usd_per_m_tok NUMERIC(12, 4),
+   source VARCHAR(16),
+   discovered_at TIMESTAMP WITH TIME ZONE,
+   last_test_at TIMESTAMP WITH TIME ZONE,
+   last_test_status VARCHAR(16),
+   last_test_latency_ms INTEGER,
+   last_test_error VARCHAR(500),
+   create_date TIMESTAMP WITH TIME ZONE,
+   modify_date TIMESTAMP WITH TIME ZONE,
+   UNIQUE (provider_id, model_id)
+);
+```
+
+Register the optional `qbit-assistant-provider-openai` module and
+`OpenAiCompatibleProviderType` to offer its kinds. Azure and generic endpoints
+require an explicit `allowedBaseUrls` entry; local defaults may be keyless.
+Discover models preserves existing rows. Cloud catalogs larger than 20 are added
+disabled; enable the models to offer before leaving the provider's model empty.
+HIPAA eligibility records an administrator's fact; P-a does not implement PHI routing.
+
+Custom CA bundles are server configuration, never database content. Register them
+with `withTrustedCaBundle(name, pem)` or `withTrustedCaBundleFile(name, path)` at
+startup, then set the HTTPS provider row's `tlsCaBundle` to that name. Empty
+references retain JVM default trust. The bundle adds trust without replacing JVM
+roots; hostname verification remains enabled. If the P-a columns were already
+applied, add only `tls_ca_bundle VARCHAR(100)` to `assistant_provider`.
+
+
+## P-b: AWS Bedrock and Google Vertex
+
+Before starting this version, database-backed hosts that already applied P-a add:
+
+```sql
+ALTER TABLE assistant_provider ADD COLUMN cloud_project VARCHAR(100);
+```
+
+Fresh installations use `docs/schema-postgres.sql`; memory-backed hosts need no
+migration. Existing providers leave the new column null. Vertex requires the GCP
+project id in `cloudProject`; Bedrock and Vertex both require `region` and reject
+`apiKeyEnvName`. They default to CLOUD; `hipaaEligible` remains a manual admin fact.
+
+Add the optional `qbit-assistant-provider-bedrock` and/or
+`qbit-assistant-provider-vertex` module at the QBit version and register
+`BedrockProviderType` / `VertexProviderType`. Credentials come from the server's
+AWS default chain / Google Application Default Credentials. No credentials are
+stored in provider rows. Hosts using AWS IRSA or web identity supply
+`software.amazon.awssdk:sts` on their own runtime classpath (matching the
+transitive AWS SDK version); this QBit does not add it. See README Providers for
+configuration, endpoint overrides and static discovery limitations.

docs/DESIGN.md

@@ -16,6 +16,13 @@ All of it is in standard QQQ tables with full record screens (D6), prefixed `ass
 
 `assistant_turn` keeps the per-turn totals and `assistant_usage_daily` the budget rollups, as before. `assistant_usage` adds the per-call detail the home needs: the provider, the failures and latency.
 
+## Provider SPI boundary
+
+All provider contracts and value types, including `ModelPricing`, belong exclusively
+to `com.kingsrook.qbits.assistant.spi` in `qbit-assistant-provider-api`. Consumers
+can depend on this artifact alone and allow its package in G1. Runtime provider
+registry and fake implementations remain in their existing internal packages.
+
 ## API keys
 
 Decision: **reference, not storage.** A provider row holds the NAME of an environment variable (`apiKeyEnvName`); `ProviderService` resolves it through `config.getSecretResolver()` (default `System::getenv`) when it builds a client.
@@ -59,7 +66,7 @@ The result goes on the row (`lastTest*`) and into `assistant_usage` (`TEST`), so
 
 ## Cost
 
-`cost = input × in + output × out + cacheRead × read + cacheWrite5m × w5 + cacheWrite1h × w1`, in micro-dollars, rounded up (`ModelPricing.costMicros`).
+`cost = input × in + output × out + cacheRead × read + cacheWrite5m × w5 + cacheWrite1h × w1`, in micro-dollars, rounded up (`com.kingsrook.qbits.assistant.spi.ModelPricing.costMicros`).
 
 Prices come from the `assistant_model_price` row for (type, model). Empty cache prices are 0.1x, 1.25x and 2x the input price. A model without a row uses the `pricing` config map, else costs 0. A price change affects later calls only; each usage row keeps the cost it was recorded with.
 
@@ -117,7 +124,7 @@ Owner: *"the agent should have to go through the same API that the UIUX does. th
 4. **Persona and skills, never more access** (owner, 2026-10-13): *"in the config for the AI settings, we should be able to set a name and personality and extra skills etc for the agent - and again - the agent should be limited to only using our UIUX API and being able to only do the things that the currently logged in user could do with the same UIUX API via the UIUX"*.
    - **Profiles** (`assistant_profile`, admin-edited): display name, icon, personality (tone instructions, at most 2,000 characters), greeting and up to 6 starter prompts.
      - One profile is the default. Others are scoped to an app, to users holding a permission (a role), or to both. The most specific profile wins.
-     - `/assistant/config` returns the profile for the panel header, the greeting and the starter prompts.
+     - `/assistant/config` returns the profile for the panel header, the greeting and the starter prompts (built per user from the tables the user can read; configured ones need a `[table]` tag, see UPGRADE.md).
    - **Skills** (`assistant_skill`, linked to profiles through `assistant_profile_skill`): named Markdown instruction packs of at most 6,000 characters, with a description, an enabled flag, trigger keywords and apps.
      - A skill is read only when relevant: a keyword appears in the question, the user is in one of its apps, or it has neither, in which case it is always read.
      - All skills read for one question total at most 12,000 characters.
@@ -143,7 +150,7 @@ Owner: *"the agent should have to go through the same API that the UIUX does. th
 - A request to the server's own port runs the identical pipeline by construction. It costs one local hop, which is milliseconds next to a model call.
 
 This matches core's design (`docs/UI-API-EXTENSIONS.md` §5, `UiApiInvoker`, QRun-IO/qqq#1128).
-- `LoopbackUiApiGateway` is the stand-in until a QQQ release has the invoker. Then an adapter over `UiApiInvoker.forServer(server)` replaces it (or a host injects one with `withUiApiGateway`), and nothing else changes.
+- `CoreUiApiGateway` adapts core's `UiApiInvoker` (the loopback stand-in is deleted). It labels calls with the client channel `assistant`, plus the turn id as detail (`assistant/<turnId>`). Form params go to the invoker's `withFormParam`; extra headers (the bulk-load tools' `X-QQQ-AI-Route`) go through `HeaderedUiApiInvoker`, a small subclass in core's package because core's request has no `withHeader` yet. A host can still inject its own gateway with `withUiApiGateway`.
 - The base URL is `uiApiBaseUrl` if configured. Otherwise it is `127.0.0.1` plus the local port the first assistant request arrived on, so in a multi-replica deployment the call stays on the replica that holds the session's process state.
 
 ### The tools
@@ -228,6 +235,18 @@ The golden and red-team evals now run through the UI API too.
   - Choosing *another* user would need that user's permissions without their session. QQQ core has no API to evaluate another user's permissions, and the assistant never builds or borrows a session. That part waits for a core API, so the report is always computed with the requester's own session.
 - **Recent denials:** the home's "Recent denials" card lists the newest tool calls the UI API, data access or the policy refused, with who, the table, the operation and the HTTP status, or the assistant setting that refused it.
 
+## Spec'd assistant endpoints and the core invoker (phase d, QQQ 4.1.0-RC.6)
+
+- **The endpoints are spec'd `/qqq/v1` operations.** `api/specs/AssistantSpecs` registers the UI API extension `assistant` (semver 1.0.0, established prefix `/assistant`) through `MiddlewareSpecExtensionsMetaData`.
+  - The URLs, bodies and statuses stay the same (201 create, 202 cancel, 204 delete and feedback, and the assistant's `{"error","code"}` errors), so Next needs no change.
+  - They appear in the served `/qqq/v1/openapi.yaml`. The turn and events streams are declared as `text/event-stream`, with `AssistantTurnEventV1` describing the events.
+  - The fragment is committed as `qbit-assistant/src/main/resources/openapi/qqq-v1/assistant.yaml`. `AssistantSpecsContractTest` checks it against the code, and the release baseline in test resources, with core's `UiApiContract`.
+- **No raw routes.** `AssistantRouteProvider` keeps only a before-handler that learns the server's local port from the first `/qqq/v1` request.
+- **Tools call core's `UiApiInvoker`** (`CoreUiApiGateway`), and the loopback stand-in is removed.
+  - The request's credentials (`UiApiCredentials.fromContext`: session cookies, Authorization, API key, exactly as they came in) are captured by the spec that starts the turn, confirms an action or explains access. They are passed to the tools, so OAuth2, table auth and API-key sessions all work. They are never logged.
+  - The gateway also refuses the assistant's own operations, so a turn can never start a turn.
+- QQQ 4.1.0-RC.6 (the default `qqq.snapshot.version`) contains #1128, so no local build is needed.
+
 ## Owner decisions (2026-10-13), continued: write mode, the hard wall, audit attribution, providers
 
 These were added on the same day. All recommendations below are accepted; we adjust once they can be seen working.
@@ -275,6 +294,14 @@ AI exposure NONE is not enough, because the assistant acts as the user and an ad
 - **Tests:** an assistant write produces audit rows with the human actor and `via=assistant/<turnId>`; the same write from the UI produces `via=next-ui`.
 - kof22 needs a feature-named changeset (`changesets/features/...`) for the audit column.
 
+### X1/Y1 as built
+- Record history is an explicit, default-off host opt-in (`withRecordHistory(true)`); kof22 does not opt in. RC.6 removes only `audit*`; later core #1193 support allows audit reads with a write-only denial. Other walls and user audit permissions remain intact.
+- RC.6's invoker fixes the `assistant` channel server-side and ignores spoofed client headers. Turn context survives knowledge discovery, RAG reads, confirm actions and owned-turn explain-access; scheduled calls retain `scheduled/<taskId>`.
+- The producer enumerates assistant tables, processes, reports and widgets (including source-QBit metadata), adds explicit denied-client rules without replacing user permissions, and registers `assistant_*` idempotently. Runtime construction independently validates the wall with core's `isDenied` and fails on exposed objects.
+- The fixture enables core's audit channel field. Hosts must migrate the nullable audit column before enabling it; kof22 needs its own feature changeset.
+- Successful insert/update/delete tool calls link to `/app/audit` with `recordId`, `auditTable.name` and `clientChannel` criteria, using the same encoder as `present_results`. Hosts without the channel field get no audit link. Existing audit link storage widens to TEXT for long encoded filters.
+- HTTP tests enumerate the configuration denial matrix for an admin, contrast Next UI access, reject broken startup metadata, and verify confirmed-write actor/channel plus the decoded audit filter.
+
 ### P. Providers, local models, HIPAA routing, budgets
 1. **Providers and models as data, any number, each with an enabled toggle.**
    - Kinds:
@@ -309,6 +336,250 @@ AI exposure NONE is not enough, because the assistant acts as the user and an ad
    - **scheduled assistant tasks**: recurring prompts that run as a designated user (with that user's stored credentials through the UI API, never a system session) and post results as notifications or records.
 6. Everything goes through the `/qqq/v1` UI API, as the user, with the guarantees above.
 
+### P-a as built
+
+- Per-provider `tlsCaBundle` references startup-parsed, transient server CA bundles. OpenAI-compatible chat, health and discovery trust JVM roots plus the bundle, retain hostname verification, and report sanitized NETWORK errors with a trust hint.
+- `assistant_provider` records kind, location, HIPAA eligibility, region, API
+  version, timeouts and discovery status. `assistant_model` is its admin-only
+  child list: enablement, capabilities, prices and test status, unique per provider/model.
+- `ProviderSettings`, discovery and health extend the provider SPI through default
+  methods. Legacy `create(apiKey, baseUrl)` implementations keep working.
+- The OpenAI-compatible module uses JDK HTTP and Jackson, Chat Completions with
+  SSE or single JSON replies, Azure deployment URLs and api-key auth, and keyless
+  local endpoints. Keys and URL overrides pass the existing allowlists first.
+- Strict tools require explicit opt-in, OpenAI or Azure, and recursively strict
+  object schemas. A strict/schema/grammar 400 signals the existing one-retry fallback.
+- Discovery only adds missing models; it preserves edits and disables catalogs
+  larger than 20 for cloud providers. Health uses a short models request. Provider
+  tests probe health then complete; model tests can probe a disabled model before
+  enabling it. Completion tests record TEST usage.
+- Registry prices and capabilities override adapter/type defaults. Empty provider
+  model selects the first enabled registry model; an explicitly disabled selection
+  is a setup error. Rows without models retain the prior behavior.
+- Localhost contract tests cover dialects, fragmented parallel tool calls, usage,
+  errors, timeouts, cancellation, discovery and a golden tool round trip. The live
+  smoke is environment-driven and excluded by default.
+
+### P-b as built
+
+- Optional Bedrock and Vertex modules reuse the Anthropic mapping and streaming
+  adapter through an injected SDK client. Bedrock retains SDK SigV4 and binary
+  event-stream decoding; a small Backend delegate supplies allow-listed endpoints
+  because SDK 2.71.0 has no Bedrock endpoint setter.
+- Bedrock uses the server's AWS default credential chain; IRSA/web-identity hosts
+  supply STS on their runtime classpath. No STS or control-plane SDK is bundled.
+- Vertex uses scoped Google ADC. `claude-*` routes to the Anthropic backend; other
+  ids route to the OpenAI-compatible endpoint with a per-request token supplier,
+  `google/` for unprefixed ids, and no strict tools.
+- Both types require region, reject key references and default to CLOUD. Vertex
+  additionally requires `cloudProject` (`cloud_project VARCHAR(100)`); it is part
+  of resolved settings and the provider cache key. Type hooks own validation.
+- Discovery is a static catalog, health is unsupported, and Test connection uses
+  the existing completion. HIPAA eligibility remains an admin fact, not a BAA.
+- Localhost contract tests cover wire paths, authentication, text/tools/usage,
+  expired-token refresh, errors, allowlists and golden turns for all three routes.
+
+### P-c as built
+
+- The qbit classification stand-in is gone: the levels are core's `actions.ai.DataClassification` (QQQ 4.1.0-RC.6, core #1142).
+  The default `ClassificationSource` reads core metadata (`AiDataClassifications`, `AiTableMetaData`, `AiFieldMetaData`) merged with the configured table/field map; configuration wins when both are set. Hosts can still supply their own source with `withClassificationSource`.
+- Turn/page/tool classification is monotonic, persisted on the turn and retained
+  on the conversation. Field subsets use overrides; unknown cross-table results
+  conservatively use the highest configured level. Metadata tools stay PUBLIC.
+- Small engine hooks check a fresh provider row before every model dispatch,
+  including strict retries. PHI requires explicit row eligibility; HIPAA mode
+  requires it for all calls. Blocks withhold results, explain the rule without
+  values, and write an audit. `ProviderService.eligibleAlternative` is an empty
+  seam for P-e; P-c never changes providers automatically.
+- HIPAA mode refuses non-eligible settings/selection and requires a valid key
+  reference at startup. AssistantStore alone encrypts/decrypts conversation
+  payloads using AES-256-GCM; legacy plaintext reads remain supported and corrupt
+  ciphertext fails closed. No key is persisted. Provider diagnostic text is
+  suppressed in HIPAA logs and turn errors.
+- Admin read-only, owner-locked `assistant_data_audit` records each PII/PHI model
+  dispatch and each block, outside navigation. PHI conversation retention defaults
+  to 2190 days in either mode; shorter tool-result/replay cleanup is unchanged.
+  The app home shows HIPAA mode and PHI retention.
+
+### P-d as built
+
+- ROLE allowances are per permission holder. Shared scopes sum a private immutable
+  accounting projection of usage counters; owner-locked source rows stay locked.
+  Migration backfills existing usage before writes resume. No sessions are elevated.
+
+- Standard admin budget rows add daily/monthly cost or token allowances above the
+  existing config/policy budgets and provider monthly caps. Overrides carry a
+  reason, session grantor and expiry; they never waive the other limit layers.
+- Start-turn checks use the existing 429 BUDGET path through PolicyService.
+  Every dispatch, including strict retries, evaluates current usage and overrides.
+  Events deduplicate WARNED, DOWNGRADED and STOPPED.
+- QQQ RC.5 core QAlerts sends budget signals alongside panel notices, with three
+  admin-visible alert types and a default logging sink. Resolution awaits active
+  alert/recurrence tracking so overrides cannot clear shared alerts incorrectly.
+- Explicit registry model selection leaves provider defaults untouched. Automatic
+  downgrades prefer LOCAL, then price. PHI eligibility and destination provider caps
+  still apply; a missing eligible target stops the turn.
+- The home owns the budget cards and 30-day cost/token bars, with user, model,
+  provider and tool breakdowns, inherited colors and empty states.
+
+### P-e as built
+
+- Profiles select OFF (the migration default), HEURISTIC or CLASSIFIER and optional
+  simple/complex/classifier registry models. Selection uses ProfileService's existing
+  specificity. Without a profile, enabled escalation config supplies the complex
+  model and effort. Empty slots retain provider row/default/policy selection.
+- The documented heuristic is a pure rule table: >600 characters, two distinct app
+  table names, complexity keywords, pending write context, >8 previous turns or a
+  previous tool limit. This branch has no conversation write-mode field.
+- Classifier transport is non-streaming, bounded to four output tokens/three seconds,
+  and contains only the fixed instruction and user question. PHI guards apply before
+  dispatch. Errors/unexpected replies use the heuristic. ROUTE usage enters budget
+  accounting; normal dispatch budgets may override the selected route.
+- FallbackChain follows at most four edges on retryable failures, only before any
+  text/tool start of that call. Candidates are checked for enablement, health,
+  PHI/HIPAA eligibility and budgets. Without explicit links only the same LOCAL
+  adapter family is considered. Provider switches rebuild neutral messages and
+  discard providerState; failed attempts remain visible in usage.
+- ProviderHealth persists UP/DOWN, checked-at and a 60-second connection-failure
+  circuit. Local stale/unknown health uses a bounded two-second probe. Successful
+  completions close the breaker. Turn rows persist route/source, fallback count and
+  final provider/model; notices name only the unavailable and answering providers.
+- Admin record screens, additive Postgres DDL and the flow-layout home expose these
+  settings and counters without granting AI access to assistant configuration.
+
+### P-f as built
+
+- `AssistantModelProvider.embed` is optional and unsupported by default. The
+  OpenAI-compatible implementation shares chat's JDK HTTP authentication, TLS,
+  Azure deployment paths, timeout and sanitized error mapping. A request accepts
+  1–64 inputs; `EmbeddingService` batches larger jobs and records each call as
+  EMBED, including daily rollups and provider/model budget accounting.
+- Registry rows have CHAT/EMBEDDING kinds and embedding dimensions. Legacy rows
+  remain CHAT. Discovery suggests EMBEDDING for ids containing embed, bge, e5,
+  gte or nomic; administrators can correct it. Chat routing/fallback/downgrades
+  cannot select an embedding model. Embedding resolution is explicit and checks
+  fresh provider enablement and HIPAA eligibility before dispatch.
+- `assistant_rag_source` is an admin-only navigation table. Its text fields must
+  exist and allow VALUES/MASKED exposure; application data access must allow READ.
+  Index now and Clear index are standard streamed ETL record actions with Review
+  and Result, never navigation entries. Indexing pages the UI API as the clicking
+  admin, reuses get_record's masking path, chunks deterministically and compares
+  hashes. Complete scans alone prune disappeared records; per-record replacement
+  also removes obsolete field chunks. Configuration/model identity changes clear
+  stale vectors. No source text is saved on a source or vector row.
+- `VectorStore` supplies upsert/delete/search/count plus content-free chunk
+  reconciliation and atomic record replacement. The in-memory implementation uses
+  exact cosine; the optional pgvector module uses host JDBC, a validated instance
+  schema, bound values and an HNSW cosine index. Sources from other embedding
+  models are excluded before ranking. The DBA installs pgvector; existing
+  installations do not require extension-installation privileges on startup.
+- `KnowledgeTool` is separate from the unchanged `UiApiToolbox`. A small
+  ContextBuilder hook adds it only for an enabled source, policy permission and
+  UI-readable source table. Search embeds the question, requests 4× the result
+  limit, then re-reads each hit through get_record with the asking user's session.
+  403/404 hits contribute only to the filtered count. Safe current values produce
+  snippets and `/app` citations; record refs propagate touched tables into P-c
+  classification and the normal tool-call log. The citation instruction is in
+  the static rules block. The result limit is capped at eight.
+- PHI source content and PHI conversation queries only reach eligible embedding
+  providers. Embedding budgets, kill switch and provider concurrency checks apply
+  to each batch. A budget downgrade into another vector space stops embedding.
+- Tests exercise real fixture UI API reads, denials, record locks, field masking,
+  PHI refusal, classification, reconciliation, embedding wire contracts and a
+  golden cited answer. JDBC shape/transaction tests always run; a pgvector:pg16
+  Testcontainers test skips on hosts without Docker.
+- P-g may invoke the manual service within a designated user's authenticated
+  context. P-f supplies no scheduled runner or stored/elevated session. Multiple
+  replicas should serialize manual re-indexing of a source at the host level;
+  per-record pgvector replacement is transactional, while scan reconciliation is
+  not a snapshot of concurrently changing application data.
+
+### P-g as built
+
+- `assistant_scheduled_task` is admin-only, AI exposure NONE, and appears as
+  Scheduled tasks. The owner-locked, read-only `assistant_scheduled_run` child
+  list retains run status, accounting and a bounded summary. Conversations gain
+  read-only `scheduledTaskId` and `channel` (`panel` or `assistant/scheduled`).
+  Task and run timestamps use the runtime clock; cron uses Quartz and a validated
+  ZoneId, including DST. Enablement and schedule edits recompute `nextRunAt`.
+- Credentials are references, never stored tokens. `credentialEnvName` must
+  match `[A-Z_][A-Z0-9_]*` and the dedicated
+  `allowedScheduledCredentialEnvNames` allowlist. The existing secret resolver
+  supplies its value. Read-only `credentialStatus` reports presence without
+  exposing token characters and is stripped on every save.
+- A run sends JSON `{accessToken: ...}` to the same loopback base URL's
+  `POST /qqq/v1/manageSession`. RC.5 with HTTP-only cookies returns the UUID in
+  `Set-Cookie: sessionUUID`; legacy JSON `uuid` is also accepted. Only then does
+  the runner resolve that UUID through the host authentication module, exactly
+  the UUID lookup used by the UI request pipeline. No direct token authentication,
+  automated-user session or constructed QSession exists in assistant code.
+  The resolved user id must equal `runAsUserId` before any model call. MOCK in
+  the integration fixture maps test tokens to the existing user-prefix sessions;
+  that token adapter is test code only.
+- kof22 provisions an Authentik designated account with normal QQQ permissions
+  and injects an accepted long-lived token through its secret manager and
+  ExternalSecret into an allow-listed environment variable. The task holds the
+  variable name and QQQ user id. Host authentication must accept that token type
+  as `accessToken`; an Authentik management API token is not automatically an
+  application access token. Neither account nor credential is provisioned here.
+- `assistantScheduledTasksRunner` registers a 60-second QScheduleMetaData when
+  `scheduledTasksSchedulerName` names a host scheduler. QQQ supplies its normal
+  scheduler context for assistant-table bookkeeping; no ArchUnit exception is
+  necessary. Configure `uiApiBaseUrl` at startup. No browser visit is required.
+- **Claim compatibility:** RC.5 UpdateInput cannot express a conditional
+  `WHERE next_run_at = expected`. AssistantStore therefore claims the expected
+  schedule slot using the database-enforced unique `(taskId, scheduledFor)` run
+  key and advances `nextRunAt` before login/dispatch. This is a unique-insert
+  optimistic claim rather than a conditional update. The memory fixture also
+  serializes claim operations on its instance. The database constraint, not
+  that monitor, prevents cross-replica duplicate execution. Do not remove claim
+  history or deploy to a backend without atomic unique keys. A crash can lose a
+  run; it never retries a claimed slot. A later tick advances an already-claimed
+  slot left behind by a crash between claim and schedule update.
+- The unchanged AssistantApi starts a new normal turn under the logged-in
+  designated user, preserving start gates, rate limiting, P-c classification,
+  P-d budgets and P-e routing/fallback. An internal context supplies the task's
+  selected profile and additional cost cap. Cost includes chat, classifier,
+  failed calls and knowledge-query embeddings. STOP is checked at dispatch
+  boundaries; an in-flight call can exceed the cap, and no next call is sent.
+- Every scheduled UI API request, including metadata and knowledge retrieval,
+  carries `X-QQQ-Client: assistant/scheduled/<taskId>`. The only uiapi change is
+  additive `LoopbackUiApiGateway.invokeWithClient`; custom gateways currently
+  fail closed for scheduled requests because their channel contract is unknown.
+  Tool-call rows also record `clientChannel`. Core channel deny enforcement
+  remains pending the client-channel RC; existing AI exposure/data-access
+  restrictions continue to apply on RC.5.
+- Approve write mode, Revoke write mode and Run now are admin record actions
+  using standard streamed ETL Review/Result. Review shows the exact prompt's
+  SHA-256 and run-as user. Result rereads and compares the complete reviewed
+  definition before recording the actual administrator's user id and time.
+  A persisted approval hash additionally binds prompt, run-as user, credential
+  reference, profile and requested mode. Editing any of these clears approval;
+  ordinary saves cannot set approval or computed bookkeeping fields.
+- This base has create/update/delete tools, but no W1 conversation mode/policy
+  switch. Scheduled runs explicitly narrow the existing tool policy: write tools
+  require both request and matching approval, a READ_WRITE table and the policy's
+  allowed-tools list. All scheduled writes require panel confirmation, including
+  when normal policy allows immediate writes. A pending proposal adds a waiting
+  notice to the run summary; the scheduler never confirms it.
+- RECORD keeps the run and conversation; NOTIFICATION and BOTH also submit an
+  Alerts notification with `NotificationAudience.user(runAsUserId)` and an
+  `/app/...` conversation link. Reflection targets the installed Alerts QBit's
+  RC.5 notification SPI/sink, following WebhooksAlerts' optional-dependency
+  pattern. Without it, a log contains run id and status only. Notification text
+  contains no answer data. In HIPAA mode run summaries contain exactly
+  `see conversation`; conversation payloads retain the existing encryption.
+    The existing record URL is an admin-screen link. Non-admin owners can read
+    their scheduled conversations in the panel's conversation list; opening a
+    particular existing conversation from a notification still needs a frontend
+    deep-link contract (the current panel only supports open/new-prompt links).
+    This phase does not broaden existing conversation record-screen permissions.
+- Failures close the run as FAILED or BLOCKED with sanitized errors and wait
+  until the next schedule. All output modes retain their audit record. Tests
+  exercise real manageSession and UI API requests with a fixed clock, designated
+  permissions and owner locks, headers, competing runners, approval invalidation,
+  notification modes, PHI refusal, encrypted HIPAA storage and cost STOP.
+
 ### Phases (each a green PR)
 | | Scope | Depends on |
 |---|---|---|
@@ -333,3 +604,65 @@ AI exposure NONE is not enough, because the assistant acts as the user and an ad
   - an "Explain access" action (for a user, and a table or a prompt, which operations the assistant could call and which it would be denied, with the reason);
   - a recent-denials widget on the app home.
 - **(d) Spec'd assistant endpoints:** move `/qqq/v1/assistant/...` (conversations, turns, events, feedback, cancel, config, actions) onto `AbstractEndpointSpec`s through the qbit spec extension point (`MiddlewareSpecExtension`, established prefix `/assistant`, QRun-IO/qqq#1128). The SSE turn and events streams stay raw routes until the spec layer can describe a stream.
+
+## Answer presentation (owner priority 2026-10-13)
+
+`present_results` is always offered and reads no records. It takes a direct answer,
+metrics, a table, an optional table-derived chart, filtered list links, record links
+and next-step actions. The server validates metadata and the user's UI API table
+visibility once per turn, formats values using QQQ field types/display formats,
+computes percentages and builds every `/app` href. Unknown or denied items are
+dropped with an explanation. The assistant must still retrieve every fact through
+data tools before presenting it.
+
+The [presentation part and SSE contract](answer-presentation.md) defines `summary`,
+`blocks` and the complete server-built GFM `markdown` fallback. Each successful
+call emits `presentation` with `{messageId, part}` and persists that part; the tool
+response tells the model not to repeat its tables or links. Audit rows contain
+only accepted presentation data. Normal record-data retention removes these parts.
+
+The built-in Presentation skill is compact static prompt text in the cached rules
+block. It asks for a one-sentence answer first, metrics for single numbers, tables
+for breakdowns/comparisons, charts for useful shares/trends and actual filter links
+whenever offering a list. Administrator profile skills append after it as before
+and extend it; there is no replacement boolean or extra permission surface.
+
+The owner's one-line table was a frontend parsing defect: Next's `AssistantMarkdown`
+used react-markdown without `remark-gfm`, so table lines became a paragraph.
+The renderer fix belongs to `qqq-frontend-next`; this worktree preserves real
+newlines and provides structured blocks plus a proper multi-line GFM fallback.
+The frontend change is maintained separately and is not verified by this build.
+
+The shared golden task asks "How many images do I have by type?": five UI count
+calls establish 81 JPEG, 20 PNG and zero other configured types, then a presentation
+with two rows, 80.2%/19.8% shares, two pie points and working MIME filter links.
+The same task is included in the opt-in `live` Anthropic eval suite.
+
+
+## Transcript redaction (secured data §15)
+
+`TranscriptRedactor` collects classified values from tools using `ClassificationSource`,
+including core table/field metadata. Stored record fields use
+`ClassifiedValueTokens.forRecordField`; criteria/proposals without a record use
+`forContext`. Core selects `shred:v1`, `hmac:v1`, or `changed:v1`. Knowledge snippets
+retain their source field's token. Matching is case-sensitive and includes canonical,
+displayed, escaped, encoded and explicitly truncated variants.
+
+`AssistantStore` stages content in turn memory and writes placeholders until
+finalization, protecting backend writes and their audits. It redacts before truncation
+and encryption. This covers messages, tool/bulk logs, replay events, pending payloads
+and audit reasons; scheduled summaries derive from redacted messages. Model requests
+and live SSE remain unchanged under PHI routing. Persisted text deltas are joined
+before redaction, with the text in the first delta and remaining deltas empty;
+sequence numbers remain stable.
+
+Crashes or unfinished tools at timeout leave placeholders. Proposals remain
+non-executable (`PREPARING`) until finalization; redacted proposals are rejected and
+must be completed in the application. A core `LogRedactorInterface` hook covers all
+threads until the turn and its tool workers finish, then releases the raw values.
+
+History stays redacted; later turns re-read records. Existing transcripts are not
+migrated, and arbitrary text is not inferred to be classified without a matching
+observed value or classified criterion/field. Canary tests scan every assistant table,
+core audits and captured logs, while proving eligible models receive original values.
+Requires QQQ 4.1.0-RC.7 (`qqq#1182`); keep the PR draft until publication.

docs/answer-presentation.md

@@ -0,0 +1,56 @@
+# Assistant answer presentation contract (v1)
+
+Owner priority (2026-10-13): answers must ALWAYS be easy to read and act on. Bad example the owner saw, rendered on ONE line:
+"| Type | Count | |---|---| | JPEG (image/jpeg) | 81 | | PNG (image/png) | 20 | | WebP, GIF, SVG | 0 |" followed by "You can open the lists filtered by JPEG or PNG" with NO links.
+
+Root cause found in Next: `AssistantMarkdown` uses react-markdown WITHOUT `remark-gfm`, so GFM tables are not parsed and the table's lines collapse into one paragraph (soft line breaks). Backend streaming preserves `\n` (events are JSON).
+
+## New message part: `presentation`
+
+An assistant message's `parts` (persisted in `assistant_message.parts_json`, streamed as an SSE event, returned by the conversation API) may contain, besides `text`, `notice`, `tool`/`render` parts etc., ONE part per `present_results` call:
+
+```json
+{
+  "type": "presentation",
+  "summary": "101 media files are images: 81 JPEG and 20 PNG.",
+  "markdown": "<server-built GFM fallback of the whole presentation, for clients that do not render blocks (CLI/TUI)>",
+  "blocks": [
+    { "kind": "metrics", "items": [ { "label": "Images", "value": 101, "display": "101", "href": "/app/media?filter=..." } ] },
+    { "kind": "table", "title": "Media by type",
+      "columns": [ { "key": "type", "label": "Type", "align": "left" },
+                   { "key": "count", "label": "Count", "align": "right" },
+                   { "key": "share", "label": "Share", "align": "right" } ],
+      "rows": [ { "cells": { "type": "JPEG (image/jpeg)", "count": 81, "share": 0.802 },
+                  "display": { "type": "JPEG (image/jpeg)", "count": "81", "share": "80.2%" },
+                  "href": "/app/media?filter=..." } ] },
+    { "kind": "chart", "chartType": "pie", "title": "Share by type",
+      "points": [ { "label": "JPEG", "value": 81, "display": "81", "href": "/app/media?filter=..." },
+                  { "label": "PNG", "value": 20, "display": "20", "href": "/app/media?filter=..." } ] },
+    { "kind": "filterLinks", "items": [ { "label": "Open JPEG media (81)", "tableName": "media", "href": "/app/media?filter=..." } ] },
+    { "kind": "recordLinks", "items": [ { "label": "Sunset.jpg", "tableName": "media", "recordId": "12", "href": "/app/media/12" } ] },
+    { "kind": "actions", "items": [ { "label": "Show the PNG files", "prompt": "Show me the PNG media files" },
+                                    { "label": "Open media", "href": "/app/media" } ] }
+  ]
+}
+```
+
+Rules:
+- `summary` is required, one sentence, the direct answer first.
+- `chartType` ∈ `bar`, `pie`, `line`; ≤ 12 points; values are numbers.
+- Every `href` is built SERVER-SIDE from metadata and is an `/app` path (same rules as `TurnEngine.isAppHref`). Filtered list links are `/app/<tableName>?filter=<URL-encoded JSON {"criteria":[{"fieldName":..,"operator":..,"values":[..]}],"booleanOperator":"AND"}>`, which Next's `deserializeFilter` accepts (JSON starting with `{`). The model never writes URLs.
+- `display` strings are formatted server-side from field metadata (`displayFormat`, e.g. `%,d`, `$%,.2f`; percent columns as `80.2%`); clients show `display` when present, else the raw value.
+- `actions` items have either `prompt` (send as the user's next message) or `href` (navigate), never both.
+- Unknown `kind`s must be ignored by clients (forward compatible); clients that do not render blocks render `markdown`.
+- The SSE event is `presentation` with `{ "messageId": <id>, "part": <the part above> }`; Next's reducer appends it to the assistant message's parts.
+
+## Tool input and implementation
+
+The input schema is [present-results.schema.json](../qbit-assistant/src/main/resources/present-results.schema.json). `table.rowKeys` supplies one raw filter value per row; `table.rowFilter` names the table, field and optional operator (EQUALS by default). Columns receive stable server keys `c0`, `c1`, etc. Input cells remain raw scalars; each row has a parallel display map. The example keys above are illustrative.
+
+`PresentResultsTool` is instantiated per turn. It caches `GET /metaData` with that turn's session, checks table read visibility and instance fields, validates QQQ criteria operators and builds paths using RC.5 `AiLinkBuilder`. Filter links use URL-encoded JSON accepted by Next. Record ids are encoded as opaque path segments. Metadata denial or invalid item drops that item (an invalid table drops its table/chart), with a short explanation to the model; other items survive. No data query or permission elevation happens here.
+
+Limits: summary 300 characters, display text 2,000 characters, table 20 columns/200 rows, chart 12 points, item lists 100 entries, filters 20 criteria/200 values. Chart truncation is reported to the model. Percent columns reference a raw numeric column; a zero total yields 0.0%. Numbers still must originate in earlier data tool results; presentation is formatting, not a new source of facts.
+
+The schema uses small named, nonrecursive definitions to avoid deeply inlined structures. Each object component is at most two levels of inline containers; the resolved table/criteria structure necessarily has the nesting shown in the owner contract. Strict is off by default. Opting `present_results` into strict mode requires all properties (empty arrays/strings, empty table and -1 for unused percentage indexes), removes provider-unsupported length constraints, and retains server validation. This has zero optional parameters and one shared scalar union in the existing strict-budget test.
+
+Presentation parts are persisted with the assistant message and replayed as `presentation` events with `{messageId, part}` (plus the standard event sequence). They are removed by record-data retention along with tool renders. Model history and text-only consumers can use the server-built Markdown. Unknown block kinds should be ignored. Plain labels must be rendered as text, never parsed as links or HTML; fallback Markdown escapes them. Tool audit input records the accepted presentation only, excluding dropped values.

docs/schema-postgres.sql

@@ -6,7 +6,8 @@ CREATE TABLE assistant_conversation
 (
    id SERIAL PRIMARY KEY,
    user_id VARCHAR(255),
-   title VARCHAR(255),
+   title TEXT,
+   max_classification VARCHAR(16),
    status VARCHAR(16),
    pinned BOOLEAN,
    last_message_at TIMESTAMP WITH TIME ZONE,
@@ -30,7 +31,7 @@ CREATE TABLE assistant_message
    status VARCHAR(16),
    turn_id INTEGER,
    seq INTEGER,
-   model VARCHAR(64),
+   model VARCHAR(200),
    parts_json TEXT,
    create_date TIMESTAMP WITH TIME ZONE,
    modify_date TIMESTAMP WITH TIME ZONE
@@ -46,10 +47,12 @@ CREATE TABLE assistant_turn
    user_message_id INTEGER,
    assistant_message_id INTEGER,
    status VARCHAR(16),
-   stop_reason VARCHAR(64),
+   classification VARCHAR(16),
+   classification_tables VARCHAR(500),
+   stop_reason TEXT,
    error_code VARCHAR(32),
    cancel_reason VARCHAR(64),
-   model VARCHAR(64),
+   model VARCHAR(200),
    started_at TIMESTAMP WITH TIME ZONE,
    ended_at TIMESTAMP WITH TIME ZONE,
    tool_call_count INTEGER,
@@ -85,7 +88,7 @@ CREATE TABLE assistant_tool_call
    turn_id INTEGER,
    conversation_id INTEGER,
    user_id VARCHAR(255),
-   tool_call_id VARCHAR(128),
+   tool_call_id TEXT,
    tool_name VARCHAR(64),
    input_json TEXT,
    outcome VARCHAR(16),
@@ -95,12 +98,12 @@ CREATE TABLE assistant_tool_call
    widget_name VARCHAR(128),
    row_count INTEGER,
    duration_ms BIGINT,
-   result_summary VARCHAR(500),
+   result_summary TEXT,
    result_json TEXT,
    redactions_json TEXT,
    ui_api_operation VARCHAR(255),
    http_status INTEGER,
-   audit_href VARCHAR(500),
+   audit_href TEXT,
    pending_action_id INTEGER,
    create_date TIMESTAMP WITH TIME ZONE
 );
@@ -115,7 +118,7 @@ CREATE TABLE assistant_feedback
    conversation_id INTEGER,
    user_id VARCHAR(255),
    rating INTEGER,
-   reason VARCHAR(64),
+   reason TEXT,
    comment TEXT,
    create_date TIMESTAMP WITH TIME ZONE
 );
@@ -173,10 +176,22 @@ CREATE TABLE assistant_provider
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL UNIQUE,
    provider_type VARCHAR(50) NOT NULL,
-   model VARCHAR(100),
+   kind VARCHAR(30),
+   location VARCHAR(10),
+   hipaa_eligible BOOLEAN DEFAULT FALSE,
+   region VARCHAR(50),
+   cloud_project VARCHAR(100),
+   api_version VARCHAR(30),
+   connect_timeout_seconds INTEGER DEFAULT 10 CHECK (connect_timeout_seconds BETWEEN 1 AND 600),
+   request_timeout_seconds INTEGER DEFAULT 120 CHECK (request_timeout_seconds BETWEEN 1 AND 600),
+   last_discovery_at TIMESTAMP WITH TIME ZONE,
+   last_discovery_status VARCHAR(16),
+   last_discovery_error VARCHAR(500),
+   model VARCHAR(200),
    enabled BOOLEAN,
    is_default BOOLEAN,
    base_url VARCHAR(255),
+   tls_ca_bundle VARCHAR(100),
    api_key_env_name VARCHAR(100),
    api_key_status VARCHAR(200),
    monthly_cost_cap_usd NUMERIC(12, 2),
@@ -185,12 +200,38 @@ CREATE TABLE assistant_provider
    last_test_at TIMESTAMP WITH TIME ZONE,
    last_test_status VARCHAR(16),
    last_test_latency_ms INTEGER,
-   last_test_model VARCHAR(100),
+   last_test_model VARCHAR(200),
    last_test_error VARCHAR(500),
    create_date TIMESTAMP WITH TIME ZONE,
    modify_date TIMESTAMP WITH TIME ZONE
 );
 
+CREATE TABLE assistant_model
+(
+   id SERIAL PRIMARY KEY,
+   provider_id INTEGER NOT NULL REFERENCES assistant_provider(id),
+   model_id VARCHAR(200) NOT NULL,
+   display_name VARCHAR(200),
+   enabled BOOLEAN,
+   supports_tools BOOLEAN,
+   supports_vision BOOLEAN,
+   supports_streaming BOOLEAN,
+   supports_reasoning_effort BOOLEAN,
+   context_window_tokens INTEGER,
+   max_output_tokens INTEGER,
+   input_usd_per_m_tok NUMERIC(12, 4),
+   output_usd_per_m_tok NUMERIC(12, 4),
+   source VARCHAR(16),
+   discovered_at TIMESTAMP WITH TIME ZONE,
+   last_test_at TIMESTAMP WITH TIME ZONE,
+   last_test_status VARCHAR(16),
+   last_test_latency_ms INTEGER,
+   last_test_error VARCHAR(500),
+   create_date TIMESTAMP WITH TIME ZONE,
+   modify_date TIMESTAMP WITH TIME ZONE,
+   UNIQUE (provider_id, model_id)
+);
+
 CREATE TABLE assistant_model_price
 (
    id SERIAL PRIMARY KEY,
@@ -215,7 +256,7 @@ CREATE TABLE assistant_usage
    turn_id INTEGER,
    provider_id INTEGER,
    provider_type VARCHAR(50),
-   model VARCHAR(100),
+   model VARCHAR(200),
    purpose VARCHAR(16),
    status VARCHAR(16),
    error_kind VARCHAR(32),
@@ -226,7 +267,7 @@ CREATE TABLE assistant_usage
    cache_read_tokens BIGINT,
    cache_write_tokens BIGINT,
    cost_micros BIGINT,
-   request_id VARCHAR(100),
+   request_id TEXT,
    create_date TIMESTAMP WITH TIME ZONE
 );
 CREATE INDEX assistant_usage_create_date ON assistant_usage (create_date);
@@ -269,16 +310,16 @@ CREATE TABLE assistant_pending_action
    conversation_id INTEGER,
    turn_id INTEGER,
    user_id VARCHAR(255),
-   tool_call_id VARCHAR(128),
+   tool_call_id TEXT,
    tool_name VARCHAR(64),
    ui_api_operation VARCHAR(255),
    table_name VARCHAR(128),
    record_id VARCHAR(128),
    params_json TEXT,
-   summary VARCHAR(500),
+   summary TEXT,
    status VARCHAR(16),
    http_status INTEGER,
-   result_summary VARCHAR(500),
+   result_summary TEXT,
    expires_at TIMESTAMP WITH TIME ZONE,
    decided_at TIMESTAMP WITH TIME ZONE,
    create_date TIMESTAMP WITH TIME ZONE,
@@ -327,3 +368,385 @@ CREATE TABLE assistant_profile_skill
    modify_date TIMESTAMP WITH TIME ZONE,
    CONSTRAINT assistant_profile_skill_pair UNIQUE (profile_id, skill_id)
 );
+
+CREATE TABLE assistant_data_audit
+(
+   id SERIAL PRIMARY KEY,
+   user_id VARCHAR(255),
+   conversation_id INTEGER,
+   turn_id INTEGER,
+   provider_id INTEGER,
+   provider_name VARCHAR(200),
+   model VARCHAR(200),
+   hipaa_eligible BOOLEAN,
+   classification VARCHAR(16),
+   tables VARCHAR(500),
+   decision VARCHAR(16),
+   reason TEXT,
+   create_date TIMESTAMP WITH TIME ZONE
+);
+CREATE INDEX assistant_data_audit_user_id ON assistant_data_audit (user_id);
+CREATE INDEX assistant_data_audit_conversation_id ON assistant_data_audit (conversation_id);
+CREATE INDEX assistant_data_audit_turn_id ON assistant_data_audit (turn_id);
+
+-- P-d: data-driven budgets (UTC periods, USD or whole-token allowances).
+CREATE TABLE assistant_budget
+(
+   id SERIAL PRIMARY KEY,
+   name VARCHAR(200) NOT NULL,
+   enabled BOOLEAN DEFAULT TRUE,
+   scope_type VARCHAR(16) NOT NULL,
+   scope_value VARCHAR(200),
+   period VARCHAR(16) NOT NULL,
+   metric VARCHAR(16) NOT NULL,
+   limit_value NUMERIC NOT NULL CHECK (limit_value > 0),
+   warn_percent INTEGER DEFAULT 80 CHECK (warn_percent >= 0 AND warn_percent < 100),
+   at_limit_action VARCHAR(16) DEFAULT 'DOWNGRADE',
+   downgrade_model_id INTEGER REFERENCES assistant_model(id),
+   hard_ceiling_percent INTEGER DEFAULT 120 CHECK (hard_ceiling_percent >= 100),
+   notes VARCHAR(2000),
+   create_date TIMESTAMP WITH TIME ZONE,
+   modify_date TIMESTAMP WITH TIME ZONE
+);
+CREATE TABLE assistant_budget_override
+(
+   id SERIAL PRIMARY KEY,
+   budget_id INTEGER NOT NULL REFERENCES assistant_budget(id),
+   scope_value VARCHAR(200),
+   extra_value NUMERIC,
+   unlimited_until TIMESTAMP WITH TIME ZONE,
+   reason TEXT NOT NULL,
+   granted_by VARCHAR(200),
+   expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
+   create_date TIMESTAMP WITH TIME ZONE,
+   modify_date TIMESTAMP WITH TIME ZONE,
+   CHECK ((extra_value > 0 AND unlimited_until IS NULL) OR (extra_value IS NULL AND unlimited_until IS NOT NULL))
+);
+CREATE INDEX assistant_budget_override_budget_id ON assistant_budget_override(budget_id);
+CREATE TABLE assistant_budget_event
+(
+   id SERIAL PRIMARY KEY,
+   budget_id INTEGER NOT NULL REFERENCES assistant_budget(id),
+   scope_key VARCHAR(400) NOT NULL,
+   period_start TIMESTAMP WITH TIME ZONE NOT NULL,
+   state VARCHAR(16) NOT NULL,
+   used_value NUMERIC,
+   limit_value NUMERIC,
+   user_id VARCHAR(200),
+   create_date TIMESTAMP WITH TIME ZONE,
+   UNIQUE (budget_id, scope_key, period_start, state)
+);
+CREATE INDEX assistant_usage_budget_period ON assistant_usage(create_date, user_id, provider_id, model);
+
+-- Private projection: standard admin permissions, AI NONE, no owner lock.
+-- No conversation identifiers, text, request ids or credentials are copied.
+CREATE TABLE assistant_budget_usage
+(
+   id SERIAL PRIMARY KEY,
+   usage_id INTEGER NOT NULL UNIQUE,
+   user_id VARCHAR(255),
+   provider_id INTEGER,
+   model VARCHAR(200),
+   occurred_at TIMESTAMP WITH TIME ZONE NOT NULL,
+   cost_micros BIGINT,
+   input_tokens BIGINT,
+   output_tokens BIGINT,
+   cache_read_tokens BIGINT,
+   cache_write_tokens BIGINT
+);
+CREATE INDEX assistant_budget_usage_period ON assistant_budget_usage(occurred_at, provider_id, model);
+-- Run once before enabling P-d, with writes paused, to include existing usage.
+INSERT INTO assistant_budget_usage
+   (usage_id, user_id, provider_id, model, occurred_at, cost_micros, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens)
+SELECT id, user_id, provider_id, model, create_date, cost_micros, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens
+FROM assistant_usage
+ON CONFLICT (usage_id) DO NOTHING;
+
+
+-- P-e: profile routing, bounded fallback chains, provider health and turn outcome.
+ALTER TABLE assistant_profile ADD COLUMN routing_mode VARCHAR(16) DEFAULT 'OFF'
+   CHECK (routing_mode IN ('OFF', 'HEURISTIC', 'CLASSIFIER'));
+ALTER TABLE assistant_profile ADD COLUMN simple_model_id INTEGER REFERENCES assistant_model(id);
+ALTER TABLE assistant_profile ADD COLUMN complex_model_id INTEGER REFERENCES assistant_model(id);
+ALTER TABLE assistant_profile ADD COLUMN classifier_model_id INTEGER REFERENCES assistant_model(id);
+ALTER TABLE assistant_model ADD COLUMN fallback_model_id INTEGER REFERENCES assistant_model(id);
+ALTER TABLE assistant_provider ADD COLUMN health_state VARCHAR(8) CHECK (health_state IN ('UP', 'DOWN'));
+ALTER TABLE assistant_provider ADD COLUMN health_checked_at TIMESTAMP WITH TIME ZONE;
+ALTER TABLE assistant_provider ADD COLUMN down_until TIMESTAMP WITH TIME ZONE;
+ALTER TABLE assistant_turn ADD COLUMN route_decision VARCHAR(16);
+ALTER TABLE assistant_turn ADD COLUMN route_source VARCHAR(16);
+ALTER TABLE assistant_turn ADD COLUMN fallback_count INTEGER DEFAULT 0;
+ALTER TABLE assistant_turn ADD COLUMN provider_id INTEGER REFERENCES assistant_provider(id);
+
+
+-- P-f: embedding registry and admin-only knowledge-source configuration.
+ALTER TABLE assistant_model ADD COLUMN model_kind VARCHAR(16) DEFAULT 'CHAT'
+   CHECK (model_kind IN ('CHAT', 'EMBEDDING'));
+ALTER TABLE assistant_model ADD COLUMN embedding_dimensions INTEGER
+   CHECK (embedding_dimensions > 0);
+
+CREATE TABLE assistant_rag_source (
+   id SERIAL PRIMARY KEY,
+   name VARCHAR(200) NOT NULL,
+   enabled BOOLEAN DEFAULT TRUE,
+   table_name VARCHAR(200) NOT NULL,
+   field_names VARCHAR(500) NOT NULL,
+   title_field_name VARCHAR(200),
+   filter_json TEXT,
+   embedding_model_id INTEGER NOT NULL REFERENCES assistant_model(id),
+   chunk_chars INTEGER DEFAULT 1500 CHECK (chunk_chars BETWEEN 100 AND 16000),
+   chunk_overlap_chars INTEGER DEFAULT 200 CHECK (chunk_overlap_chars >= 0 AND chunk_overlap_chars < chunk_chars),
+   last_indexed_at TIMESTAMPTZ,
+   last_index_status VARCHAR(200),
+   last_index_error VARCHAR(500),
+   indexed_record_count INTEGER,
+   indexed_chunk_count INTEGER,
+   create_date TIMESTAMPTZ,
+   modify_date TIMESTAMPTZ
+);
+
+-- Optional pgvector part: reference only. Run the extension step as a DBA.
+-- PgVectorStore.ensureSchema() performs the remainder for the host's schema/N.
+-- Use a distinct schema per QQQ instance; match N to the embedding model.
+-- CREATE EXTENSION IF NOT EXISTS vector;
+-- CREATE SCHEMA IF NOT EXISTS assistant_rag;
+-- CREATE TABLE IF NOT EXISTS assistant_rag.assistant_rag_chunk (
+--    id BIGSERIAL PRIMARY KEY,
+--    source_id INT NOT NULL,
+--    table_name TEXT NOT NULL,
+--    record_pk TEXT NOT NULL,
+--    field_name TEXT NOT NULL,
+--    chunk_index INT NOT NULL,
+--    content_hash CHAR(64) NOT NULL,
+--    embedding vector(1024) NOT NULL,
+--    indexed_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+--    UNIQUE(source_id, table_name, record_pk, field_name, chunk_index)
+-- );
+-- CREATE INDEX IF NOT EXISTS assistant_rag_chunk_cosine
+--    ON assistant_rag.assistant_rag_chunk USING hnsw (embedding vector_cosine_ops);
+
+-- P-g: designated-user scheduled assistant tasks. Install before enabling jobs.
+CREATE TABLE assistant_scheduled_task (
+   id SERIAL PRIMARY KEY,
+   name VARCHAR(200) NOT NULL,
+   enabled BOOLEAN NOT NULL DEFAULT FALSE,
+   prompt TEXT NOT NULL CHECK (char_length(prompt) BETWEEN 1 AND 4000),
+   run_as_user_id VARCHAR(200) NOT NULL,
+   credential_env_name VARCHAR(200) NOT NULL,
+   credential_status VARCHAR(200), -- computed; always NULL in stored rows
+   profile_id INTEGER REFERENCES assistant_profile(id),
+   cron_expression VARCHAR(200) NOT NULL,
+   timezone VARCHAR(100) NOT NULL DEFAULT 'UTC',
+   next_run_at TIMESTAMPTZ,
+   output_mode VARCHAR(20) NOT NULL DEFAULT 'RECORD' CHECK (output_mode IN ('RECORD', 'NOTIFICATION', 'BOTH')),
+   write_mode_requested BOOLEAN NOT NULL DEFAULT FALSE,
+   write_mode_approved_by VARCHAR(200),
+   write_mode_approved_at TIMESTAMPTZ,
+   write_mode_approval_hash VARCHAR(64),
+   max_cost_usd_per_run NUMERIC(18,6) CHECK (max_cost_usd_per_run >= 0),
+   last_run_at TIMESTAMPTZ,
+   last_run_status VARCHAR(20),
+   last_run_error VARCHAR(500),
+   create_date TIMESTAMPTZ,
+   modify_date TIMESTAMPTZ
+);
+CREATE INDEX assistant_scheduled_task_due ON assistant_scheduled_task(next_run_at) WHERE enabled;
+
+ALTER TABLE assistant_conversation ADD COLUMN scheduled_task_id INTEGER REFERENCES assistant_scheduled_task(id);
+ALTER TABLE assistant_conversation ADD COLUMN channel VARCHAR(64) NOT NULL DEFAULT 'panel';
+ALTER TABLE assistant_tool_call ADD COLUMN client_channel VARCHAR(64);
+
+CREATE TABLE assistant_scheduled_run (
+   id SERIAL PRIMARY KEY,
+   task_id INTEGER NOT NULL REFERENCES assistant_scheduled_task(id),
+   user_id VARCHAR(200) NOT NULL,
+   scheduled_for TIMESTAMPTZ NOT NULL,
+   started_at TIMESTAMPTZ,
+   ended_at TIMESTAMPTZ,
+   status VARCHAR(20) NOT NULL CHECK (status IN ('RUNNING', 'OK', 'FAILED', 'SKIPPED', 'BLOCKED')),
+   conversation_id INTEGER REFERENCES assistant_conversation(id) ON DELETE SET NULL,
+   turn_id INTEGER REFERENCES assistant_turn(id) ON DELETE SET NULL,
+   summary TEXT,
+   cost_micros BIGINT,
+   error TEXT,
+   create_date TIMESTAMPTZ,
+   modify_date TIMESTAMPTZ,
+   UNIQUE (task_id, scheduled_for)
+);
+CREATE INDEX assistant_scheduled_run_owner ON assistant_scheduled_run(user_id, started_at);
+
+-- X1/Y1: encoded audit filters can exceed the old 500-character record links.
+ALTER TABLE assistant_tool_call ALTER COLUMN audit_href TYPE TEXT;
+
+
+-- Durable turns: apply this additive block before deploying the new runtime.
+-- Like earlier additions, fresh installs run the CREATEs followed by ALTERs.
+ALTER TABLE assistant_turn ADD COLUMN heartbeat_at TIMESTAMP;
+ALTER TABLE assistant_turn ADD COLUMN lease_owner VARCHAR(100);
+ALTER TABLE assistant_turn ADD COLUMN cancel_requested_at TIMESTAMP;
+ALTER TABLE assistant_turn ADD COLUMN phase VARCHAR(64);
+ALTER TABLE assistant_turn ADD COLUMN concurrency_mode VARCHAR(16);
+CREATE INDEX assistant_turn_user_status ON assistant_turn (user_id, status);
+
+-- Fence concurrent orphan reapers at the database boundary. A turn ends once.
+-- Check for pre-existing duplicate message.end rows before applying this index.
+CREATE UNIQUE INDEX assistant_turn_event_terminal ON assistant_turn_event (turn_id)
+   WHERE event_type = 'message.end';
+
+-- Index audit (2026-10-14): lookup, retention and FK paths with no leading index.
+-- ScheduledTurn.cost reads usage by turn on every scheduled run.
+CREATE INDEX IF NOT EXISTS assistant_usage_turn ON assistant_usage (turn_id);
+-- Retention: deleteTurnEventsBefore, clearToolResultsBefore and listConversationsInactiveSince filter by date.
+CREATE INDEX IF NOT EXISTS assistant_turn_event_create_date ON assistant_turn_event (create_date);
+CREATE INDEX IF NOT EXISTS assistant_tool_call_create_date ON assistant_tool_call (create_date);
+CREATE INDEX IF NOT EXISTS assistant_conversation_modify_date ON assistant_conversation (modify_date);
+-- ON DELETE SET NULL children: deleting a conversation or turn would scan scheduled runs without these.
+CREATE INDEX IF NOT EXISTS assistant_scheduled_run_conversation ON assistant_scheduled_run (conversation_id);
+CREATE INDEX IF NOT EXISTS assistant_scheduled_run_turn ON assistant_scheduled_run (turn_id);
+
+-- Foreign keys (2026-10-14). Run on new and existing databases; every step is guarded
+-- and re-runnable. The rules follow how the qbit deletes:
+-- * AssistantStore.deleteConversation (also the retention purge) deletes turn events,
+--   tool calls, feedback, messages, turns, data audit and pending actions, then the
+--   conversation. The conversation's own detail rows CASCADE, so an admin delete of a
+--   conversation cleans up the same way.
+-- * The message <-> turn cycle (turn.user_message_id / assistant_message_id and
+--   message.turn_id) and the other optional pointers are SET NULL. Rows are inserted
+--   parent first, so nothing is deferred.
+-- * assistant_usage keeps its cost rows when a conversation goes (SET NULL), and the
+--   data audit trail is never cascaded into (SET NULL).
+-- * Provider references from usage, budget accounting and the data audit are NO ACTION
+--   (like assistant_turn.provider_id): disable a provider with history, do not delete
+--   it. A provider's model rows are its own (CASCADE).
+-- * assistant_budget_usage.usage_id has no foreign key on purpose: the projection
+--   outlives its usage row so budgets keep counting the spend.
+-- Rows that already point at a missing parent are recorded in qqq_fk_quarantine first,
+-- then nulled (nullable columns) or deleted with the full row recorded (NOT NULL).
+CREATE INDEX IF NOT EXISTS assistant_message_parent_message ON assistant_message (parent_message_id);
+CREATE INDEX IF NOT EXISTS assistant_message_turn ON assistant_message (turn_id);
+CREATE INDEX IF NOT EXISTS assistant_turn_user_message ON assistant_turn (user_message_id);
+CREATE INDEX IF NOT EXISTS assistant_turn_assistant_message ON assistant_turn (assistant_message_id);
+CREATE INDEX IF NOT EXISTS assistant_turn_provider ON assistant_turn (provider_id);
+CREATE INDEX IF NOT EXISTS assistant_tool_call_pending_action ON assistant_tool_call (pending_action_id);
+CREATE INDEX IF NOT EXISTS assistant_feedback_message ON assistant_feedback (message_id);
+CREATE INDEX IF NOT EXISTS assistant_pending_action_turn ON assistant_pending_action (turn_id);
+CREATE INDEX IF NOT EXISTS assistant_data_audit_provider ON assistant_data_audit (provider_id);
+CREATE INDEX IF NOT EXISTS assistant_budget_usage_provider ON assistant_budget_usage (provider_id);
+CREATE INDEX IF NOT EXISTS assistant_profile_skill_skill ON assistant_profile_skill (skill_id);
+CREATE INDEX IF NOT EXISTS assistant_budget_downgrade_model ON assistant_budget (downgrade_model_id);
+CREATE INDEX IF NOT EXISTS assistant_conversation_scheduled_task ON assistant_conversation (scheduled_task_id);
+CREATE INDEX IF NOT EXISTS assistant_model_fallback_model ON assistant_model (fallback_model_id);
+CREATE INDEX IF NOT EXISTS assistant_profile_simple_model ON assistant_profile (simple_model_id);
+CREATE INDEX IF NOT EXISTS assistant_profile_complex_model ON assistant_profile (complex_model_id);
+CREATE INDEX IF NOT EXISTS assistant_profile_classifier_model ON assistant_profile (classifier_model_id);
+CREATE INDEX IF NOT EXISTS assistant_rag_source_embedding_model ON assistant_rag_source (embedding_model_id);
+CREATE INDEX IF NOT EXISTS assistant_scheduled_task_profile ON assistant_scheduled_task (profile_id);
+
+CREATE TABLE IF NOT EXISTS qqq_fk_quarantine (id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, table_name VARCHAR(100) NOT NULL, column_name VARCHAR(100) NOT NULL, row_id VARCHAR(100), missing_parent_id VARCHAR(100), action VARCHAR(20) NOT NULL, row_data TEXT, changeset VARCHAR(200), quarantined_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP);
+
+DO $$
+DECLARE
+   r   RECORD;
+   old TEXT;
+BEGIN
+   FOR r IN SELECT * FROM (VALUES
+      ('assistant_message',        'conversation_id',      'assistant_conversation',   'CASCADE',   TRUE),
+      ('assistant_message',        'parent_message_id',    'assistant_message',        'SET NULL',  TRUE),
+      ('assistant_message',        'turn_id',              'assistant_turn',           'SET NULL',  TRUE),
+      ('assistant_turn',           'conversation_id',      'assistant_conversation',   'CASCADE',   TRUE),
+      ('assistant_turn',           'user_message_id',      'assistant_message',        'SET NULL',  TRUE),
+      ('assistant_turn',           'assistant_message_id', 'assistant_message',        'SET NULL',  TRUE),
+      ('assistant_turn_event',     'turn_id',              'assistant_turn',           'CASCADE',   TRUE),
+      ('assistant_tool_call',      'conversation_id',      'assistant_conversation',   'CASCADE',   TRUE),
+      ('assistant_tool_call',      'turn_id',              'assistant_turn',           'CASCADE',   TRUE),
+      ('assistant_tool_call',      'pending_action_id',    'assistant_pending_action', 'SET NULL',  TRUE),
+      ('assistant_feedback',       'conversation_id',      'assistant_conversation',   'CASCADE',   TRUE),
+      ('assistant_feedback',       'message_id',           'assistant_message',        'CASCADE',   TRUE),
+      ('assistant_pending_action', 'conversation_id',      'assistant_conversation',   'CASCADE',   TRUE),
+      ('assistant_pending_action', 'turn_id',              'assistant_turn',           'SET NULL',  TRUE),
+      ('assistant_data_audit',     'conversation_id',      'assistant_conversation',   'SET NULL',  TRUE),
+      ('assistant_data_audit',     'turn_id',              'assistant_turn',           'SET NULL',  TRUE),
+      ('assistant_usage',          'conversation_id',      'assistant_conversation',   'SET NULL',  TRUE),
+      ('assistant_usage',          'turn_id',              'assistant_turn',           'SET NULL',  TRUE),
+      ('assistant_usage',          'provider_id',          'assistant_provider',       'NO ACTION', TRUE),
+      ('assistant_data_audit',     'provider_id',          'assistant_provider',       'NO ACTION', TRUE),
+      ('assistant_budget_usage',   'provider_id',          'assistant_provider',       'NO ACTION', TRUE),
+      ('assistant_profile_skill',  'profile_id',           'assistant_profile',        'CASCADE',   FALSE),
+      ('assistant_profile_skill',  'skill_id',             'assistant_skill',          'CASCADE',   FALSE)
+   ) AS v(child, col, parent, rule, nullable)
+   LOOP
+      IF NOT EXISTS (SELECT 1 FROM information_schema.table_constraints WHERE constraint_schema = current_schema() AND LOWER(constraint_name) = 'fk_' || r.child || '_' || r.col) THEN
+         IF r.nullable THEN
+            EXECUTE format('INSERT INTO qqq_fk_quarantine (table_name, column_name, row_id, missing_parent_id, action, changeset) '
+               || 'SELECT %L, %L, c.id::text, c.%I::text, ''NULLED'', ''qbit-assistant 2026-10-14 foreign keys'' FROM %I c '
+               || 'WHERE c.%I IS NOT NULL AND NOT EXISTS (SELECT 1 FROM %I p WHERE p.id = c.%I)', r.child, r.col, r.col, r.child, r.col, r.parent, r.col);
+            EXECUTE format('UPDATE %I c SET %I = NULL WHERE c.%I IS NOT NULL AND NOT EXISTS (SELECT 1 FROM %I p WHERE p.id = c.%I)', r.child, r.col, r.col, r.parent, r.col);
+         ELSE
+            EXECUTE format('INSERT INTO qqq_fk_quarantine (table_name, column_name, row_id, missing_parent_id, action, row_data, changeset) '
+               || 'SELECT %L, %L, c.id::text, c.%I::text, ''DELETED'', row_to_json(c)::text, ''qbit-assistant 2026-10-14 foreign keys'' FROM %I c '
+               || 'WHERE NOT EXISTS (SELECT 1 FROM %I p WHERE p.id = c.%I)', r.child, r.col, r.col, r.child, r.parent, r.col);
+            EXECUTE format('DELETE FROM %I c WHERE NOT EXISTS (SELECT 1 FROM %I p WHERE p.id = c.%I)', r.child, r.parent, r.col);
+         END IF;
+         EXECUTE format('ALTER TABLE %I ADD CONSTRAINT %I FOREIGN KEY (%I) REFERENCES %I (id) ON DELETE %s', r.child, 'fk_' || r.child || '_' || r.col, r.col, r.parent, r.rule);
+      END IF;
+   END LOOP;
+
+   -- assistant_model.provider_id: the inline NO ACTION key becomes CASCADE, named as on kof22.
+   IF NOT EXISTS (SELECT 1 FROM information_schema.table_constraints WHERE constraint_schema = current_schema() AND LOWER(constraint_name) = 'fk_assistant_model_provider') THEN
+      FOR old IN SELECT conname FROM pg_constraint
+         WHERE contype = 'f' AND conrelid = 'assistant_model'::regclass AND confrelid = 'assistant_provider'::regclass
+      LOOP
+         EXECUTE format('ALTER TABLE assistant_model DROP CONSTRAINT %I', old);
+      END LOOP;
+      ALTER TABLE assistant_model ADD CONSTRAINT fk_assistant_model_provider FOREIGN KEY (provider_id) REFERENCES assistant_provider (id) ON DELETE CASCADE;
+   END IF;
+END $$;
+
+-- Transcript redaction: tokens can expand beyond the original payload bounds.
+-- Apply to existing databases as well; SET DATA TYPE is also valid in H2.
+ALTER TABLE assistant_turn ALTER COLUMN stop_reason SET DATA TYPE TEXT;
+ALTER TABLE assistant_tool_call ALTER COLUMN tool_call_id SET DATA TYPE TEXT;
+ALTER TABLE assistant_feedback ALTER COLUMN reason SET DATA TYPE TEXT;
+ALTER TABLE assistant_usage ALTER COLUMN request_id SET DATA TYPE TEXT;
+ALTER TABLE assistant_pending_action ALTER COLUMN tool_call_id SET DATA TYPE TEXT;
+ALTER TABLE assistant_data_audit ALTER COLUMN reason SET DATA TYPE TEXT;
+ALTER TABLE assistant_budget_override ALTER COLUMN reason SET DATA TYPE TEXT;
+ALTER TABLE assistant_scheduled_run ALTER COLUMN summary SET DATA TYPE TEXT;
+ALTER TABLE assistant_scheduled_run ALTER COLUMN error SET DATA TYPE TEXT;
+
+-- Fail soft (UI API extension assistant 1.5.0): errors the panel reports through
+-- POST /qqq/v1/assistant/client-errors. Owner-locked like the other user rows; the
+-- message and stacks are scrubbed and bounded before they are stored. The ids are
+-- kept only when they are the reporting user's own rows, and SET NULL when those go.
+-- Retention deletes rows older than toolResultRetentionDays. Safe to re-run.
+CREATE TABLE IF NOT EXISTS assistant_client_error
+(
+   id SERIAL PRIMARY KEY,
+   user_id VARCHAR(255),
+   scope VARCHAR(64),
+   message TEXT,
+   error_name VARCHAR(100),
+   stack TEXT,
+   component_stack TEXT,
+   request_id VARCHAR(128),
+   route VARCHAR(300),
+   conversation_id INTEGER CONSTRAINT fk_assistant_client_error_conversation_id REFERENCES assistant_conversation (id) ON DELETE SET NULL,
+   message_id INTEGER CONSTRAINT fk_assistant_client_error_message_id REFERENCES assistant_message (id) ON DELETE SET NULL,
+   turn_id INTEGER CONSTRAINT fk_assistant_client_error_turn_id REFERENCES assistant_turn (id) ON DELETE SET NULL,
+   part_type VARCHAR(64),
+   render_type VARCHAR(64),
+   app_version VARCHAR(64),
+   occurred_at TIMESTAMP WITH TIME ZONE,
+   create_date TIMESTAMP WITH TIME ZONE
+);
+CREATE INDEX IF NOT EXISTS assistant_client_error_user_id ON assistant_client_error (user_id);
+CREATE INDEX IF NOT EXISTS assistant_client_error_create_date ON assistant_client_error (create_date);
+CREATE INDEX IF NOT EXISTS assistant_client_error_conversation ON assistant_client_error (conversation_id);
+CREATE INDEX IF NOT EXISTS assistant_client_error_message ON assistant_client_error (message_id);
+CREATE INDEX IF NOT EXISTS assistant_client_error_turn ON assistant_client_error (turn_id);
+
+-- Provider setup state: SETTING_UP marks a provider an admin is still building. The
+-- assistant never routes to it and its provider and model health checks do not run.
+-- Existing rows (and NULL) behave as ACTIVE, exactly as before. Safe to re-run.
+ALTER TABLE assistant_provider ADD COLUMN IF NOT EXISTS setup_state VARCHAR(16) DEFAULT 'ACTIVE'
+   CONSTRAINT ck_assistant_provider_setup_state CHECK (setup_state IN ('ACTIVE', 'SETTING_UP'));

docs/screenshots/README.md

@@ -23,3 +23,20 @@ Light and dark, 390 and 1440 px:
 - `panel-persona-*`: the panel with the configured persona. This is the Next UI build of qqq-frontend-next#94; the demo's admin matches the permission-scoped "Ada (analytics)" profile.
 - `panel-pending-*`: the assistant proposed `update_record` on page 12, which is READ_WRITE. The card shows the change with Save and Cancel; nothing is saved yet.
 - `panel-confirmed-*`: after Save, the write ran once through `PATCH /qqq/v1/table/page/12` with the user's session. The card says Done, and the record screen behind the panel shows the new value.
+
+Planned P-a provider registry additions, taken against `OpenAiDemoServer` in the
+OpenAI provider's test sources with the Next UI **1.0.0-RC.18** jar. See that
+[demo's run instructions](../../qbit-assistant-provider-openai/src/test/java/com/kingsrook/qbits/assistant/provider/openai/demo/README.md).
+Discovery and connection-test status, TEST usage and the assistant turn are real
+executions against the localhost mock; replies/token counts are synthetic, not
+live GPU measurements. No screenshots in this group have been added yet.
+
+Light and dark, 390 and 1440 px:
+- `p-provider-local-*`: Local GPU (Ollama), keyless LOCAL settings, discovery/test results and discovered models.
+- `p-model-*`: a discovered model's capabilities, compute prices and connection-test result.
+- `p-home-providers-*`: the home's provider summary and usage from the executed demo calls, including disabled OpenRouter with its key Not set.
+
+Answer presentation (owner priority, 2026-10-13), taken against `OpenAiDemoServer` with the Next UI build of QRun-IO/qqq-frontend-next#111 (`next dev` proxied to the demo). The demo's OpenAI-compatible mock answers "How many images do I have by type?" the way a model would through the real adapter: five `count_records` calls through the UI API, then `present_results`.
+
+Light and dark, 390 and 1440 px:
+- `panel-presentation-*`: the summary line, an Images metric, the "Media by type" table (counts and the server-computed 80.2% and 19.8%, each row a filtered-list link), the pie chart, two filter links (Open JPEG media, Open PNG media) and a follow-up action.

pom.xml

@@ -28,6 +28,8 @@
       <anthropic.version>2.71.0</anthropic.version>
       <archunit.version>1.5.1</archunit.version>
       <jackson.version>2.21.7</jackson.version>
+      <!-- optional email delivery; qbit-email from Maven Central -->
+      <qbit-email.version>0.1.0-RC.2</qbit-email.version>
       <!-- live evals call the real API; run them with -Dtest.excludedGroups= -Dgroups=live -->
       <test.excludedGroups>live</test.excludedGroups>
    </properties>
@@ -35,7 +37,7 @@
    <parent>
       <groupId>com.kingsrook</groupId>
       <artifactId>qbit-build-parent</artifactId>
-      <version>2.0.0</version>
+      <version>2.1.1</version>
    </parent>
 
    <groupId>com.kingsrook.qbits</groupId>
@@ -50,8 +52,13 @@
    <modelVersion>4.0.0</modelVersion>
 
    <modules>
+      <module>qbit-assistant-provider-api</module>
       <module>qbit-assistant</module>
       <module>qbit-assistant-provider-anthropic</module>
+      <module>qbit-assistant-provider-openai</module>
+      <module>qbit-assistant-provider-bedrock</module>
+      <module>qbit-assistant-provider-vertex</module>
+      <module>qbit-assistant-rag-pgvector</module>
    </modules>
 
    <licenses>
@@ -81,6 +88,26 @@
 
    <dependencyManagement>
       <dependencies>
+         <dependency>
+            <groupId>com.kingsrook.qbits</groupId>
+            <artifactId>qbit-assistant-provider-api</artifactId>
+            <version>${revision}</version>
+         </dependency>
+         <dependency>
+            <groupId>com.kingsrook.qbits</groupId>
+            <artifactId>qbit-assistant-provider-anthropic</artifactId>
+            <version>${revision}</version>
+         </dependency>
+         <dependency>
+            <groupId>com.anthropic</groupId>
+            <artifactId>anthropic-java-bedrock</artifactId>
+            <version>${anthropic.version}</version>
+         </dependency>
+         <dependency>
+            <groupId>com.anthropic</groupId>
+            <artifactId>anthropic-java-vertex</artifactId>
+            <version>${anthropic.version}</version>
+         </dependency>
          <!-- QQQ 4.1 is built on Jackson 2.21; the Anthropic SDK asks for 2.19. -->
          <!-- Pin the newer one so both resolve to the same line.               -->
          <dependency>
@@ -101,6 +128,11 @@
             <version>${revision}</version>
             <type>test-jar</type>
          </dependency>
+         <dependency>
+            <groupId>com.kingsrook.qbits</groupId>
+            <artifactId>qbit-assistant-provider-openai</artifactId>
+            <version>${revision}</version>
+         </dependency>
          <dependency>
             <groupId>com.anthropic</groupId>
             <artifactId>anthropic-java</artifactId>
@@ -170,8 +202,9 @@
    </build>
 
    <profiles>
-      <!-- The assistant needs QQQ 4.1.0-RC.4: the AI tool kernel (package        -->
-      <!-- actions.ai, qqq#1078) and the developer panels (qqq#1076). Until        -->
+      <!-- The assistant needs QQQ 4.1.0-RC.7: the AI tool kernel (qqq#1078), the  -->
+      <!-- developer panels (qqq#1076) and the UI API extension point, invoker   -->
+      <!-- and credentials (qqq#1128). Until                                      -->
       <!-- qbit-build-parent imports the 4.1 BOM, this                              -->
       <!-- profile is active by default and imports qqq-bom-pom ahead of the        -->
       <!-- parent's 4.0.0 BOM, as in qbit-quick-search (ADR-0007). Override with    -->
@@ -182,7 +215,9 @@
             <activeByDefault>true</activeByDefault>
          </activation>
          <properties>
-            <qqq.snapshot.version>4.1.0-RC.4</qqq.snapshot.version>
+            <!-- RC.7 provides classified-value tokens, log redaction and native help bundles; -->
+            <!-- RC.8 provides core job tracking (JobTracking, the Jobs tray).                   -->
+            <qqq.snapshot.version>4.1.0-RC.15</qqq.snapshot.version>
          </properties>
          <dependencyManagement>
             <dependencies>

qbit-assistant-provider-anthropic/pom.xml

@@ -32,9 +32,14 @@
    <url>https://github.com/QRun-IO/qbit-assistant</url>
 
    <dependencies>
+      <dependency>
+         <groupId>com.kingsrook.qbits</groupId>
+         <artifactId>qbit-assistant-provider-api</artifactId>
+      </dependency>
       <dependency>
          <groupId>com.kingsrook.qbits</groupId>
          <artifactId>qbit-assistant</artifactId>
+         <scope>test</scope>
       </dependency>
       <dependency>
          <groupId>com.kingsrook.qqq</groupId>

qbit-assistant-provider-anthropic/src/main/java/com/kingsrook/qbits/assistant/provider/anthropic/AnthropicMapping.java

@@ -24,9 +24,11 @@ import java.util.Map;
 import com.anthropic.core.JsonValue;
 import com.anthropic.errors.AnthropicIoException;
 import com.anthropic.errors.AnthropicServiceException;
+import com.anthropic.models.messages.Base64ImageSource;
 import com.anthropic.models.messages.CacheControlEphemeral;
 import com.anthropic.models.messages.ContentBlock;
 import com.anthropic.models.messages.ContentBlockParam;
+import com.anthropic.models.messages.ImageBlockParam;
 import com.anthropic.models.messages.Message;
 import com.anthropic.models.messages.MessageCreateParams;
 import com.anthropic.models.messages.MessageParam;
@@ -40,15 +42,15 @@ import com.anthropic.models.messages.ToolUseBlock;
 import com.anthropic.models.messages.ToolUseBlockParam;
 import com.anthropic.models.messages.Usage;
 import com.fasterxml.jackson.core.type.TypeReference;
-import com.kingsrook.qbits.assistant.provider.CacheHint;
-import com.kingsrook.qbits.assistant.provider.ModelMessage;
-import com.kingsrook.qbits.assistant.provider.ModelPart;
-import com.kingsrook.qbits.assistant.provider.ModelProviderException;
-import com.kingsrook.qbits.assistant.provider.ModelRequest;
-import com.kingsrook.qbits.assistant.provider.ModelResponse;
-import com.kingsrook.qbits.assistant.provider.ModelToolDefinition;
-import com.kingsrook.qbits.assistant.provider.ModelUsage;
-import com.kingsrook.qbits.assistant.provider.SystemBlock;
+import com.kingsrook.qbits.assistant.spi.CacheHint;
+import com.kingsrook.qbits.assistant.spi.ModelMessage;
+import com.kingsrook.qbits.assistant.spi.ModelPart;
+import com.kingsrook.qbits.assistant.spi.ModelProviderException;
+import com.kingsrook.qbits.assistant.spi.ModelRequest;
+import com.kingsrook.qbits.assistant.spi.ModelResponse;
+import com.kingsrook.qbits.assistant.spi.ModelToolDefinition;
+import com.kingsrook.qbits.assistant.spi.ModelUsage;
+import com.kingsrook.qbits.assistant.spi.SystemBlock;
 
 
 /*******************************************************************************
@@ -223,6 +225,18 @@ public class AnthropicMapping
                }
                blocks.add(ContentBlockParam.ofToolResult(result.build()));
             }
+            case IMAGE ->
+            {
+               ImageBlockParam.Builder image = ImageBlockParam.builder().source(Base64ImageSource.builder()
+                  .mediaType(Base64ImageSource.MediaType.of(part.getMediaType()))
+                  .data(part.getData() == null ? "" : part.getData())
+                  .build());
+               if(cache != null)
+               {
+                  image.cacheControl(cache);
+               }
+               blocks.add(ContentBlockParam.ofImage(image.build()));
+            }
             default -> throw (new IllegalStateException("Unknown part type"));
          }
       }

qbit-assistant-provider-anthropic/src/main/java/com/kingsrook/qbits/assistant/provider/anthropic/AnthropicModelProvider.java

@@ -29,14 +29,14 @@ import com.anthropic.core.http.StreamResponse;
 import com.anthropic.helpers.MessageAccumulator;
 import com.anthropic.models.messages.MessageCreateParams;
 import com.anthropic.models.messages.RawMessageStreamEvent;
-import com.kingsrook.qbits.assistant.provider.AssistantModelProvider;
-import com.kingsrook.qbits.assistant.provider.CompletableStreamHandle;
-import com.kingsrook.qbits.assistant.provider.ModelCapabilities;
-import com.kingsrook.qbits.assistant.provider.ModelEventListener;
-import com.kingsrook.qbits.assistant.provider.ModelProviderException;
-import com.kingsrook.qbits.assistant.provider.ModelRequest;
-import com.kingsrook.qbits.assistant.provider.ModelUsage;
-import com.kingsrook.qbits.assistant.provider.StreamHandle;
+import com.kingsrook.qbits.assistant.spi.AssistantModelProvider;
+import com.kingsrook.qbits.assistant.spi.CompletableStreamHandle;
+import com.kingsrook.qbits.assistant.spi.ModelCapabilities;
+import com.kingsrook.qbits.assistant.spi.ModelEventListener;
+import com.kingsrook.qbits.assistant.spi.ModelProviderException;
+import com.kingsrook.qbits.assistant.spi.ModelRequest;
+import com.kingsrook.qbits.assistant.spi.ModelUsage;
+import com.kingsrook.qbits.assistant.spi.StreamHandle;
 import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.utils.StringUtils;
 import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
@@ -98,15 +98,16 @@ public class AnthropicModelProvider implements AssistantModelProvider
 
 
    /*******************************************************************************
-    ** Builds the provider. apiKey is required (a literal from a secret store,
-    ** or "${env.NAME}").
+    ** Builds the provider. Unless a client is supplied, apiKey is required
+    ** (a literal from a secret store, or "${env.NAME}").
     *******************************************************************************/
    public static class Builder
    {
-      private String   apiKey;
-      private String   baseUrl;
-      private Duration timeout    = Duration.ofMinutes(10);
-      private Integer  maxRetries = 2;
+      private String          apiKey;
+      private AnthropicClient client;
+      private String          baseUrl;
+      private Duration        timeout    = Duration.ofMinutes(10);
+      private Integer         maxRetries = 2;
 
 
 
@@ -121,6 +122,19 @@ public class AnthropicModelProvider implements AssistantModelProvider
 
 
 
+      /*******************************************************************************
+       ** Use an already configured client, including a cloud backend. The provider
+       ** owns and closes this client; key, URL, timeout and retry builder options
+       ** apply only when the builder creates its own client.
+       *******************************************************************************/
+      public Builder client(AnthropicClient client)
+      {
+         this.client = client;
+         return (this);
+      }
+
+
+
       /*******************************************************************************
        ** Another API base URL (a gateway, or a test server).
        *******************************************************************************/
@@ -159,6 +173,10 @@ public class AnthropicModelProvider implements AssistantModelProvider
        *******************************************************************************/
       public AnthropicModelProvider build()
       {
+         if(client != null)
+         {
+            return (new AnthropicModelProvider(client, baseUrl));
+         }
          String key = resolveSecret(apiKey);
          if(!StringUtils.hasContent(key))
          {
@@ -227,7 +245,7 @@ public class AnthropicModelProvider implements AssistantModelProvider
 
    /*******************************************************************************
     ** Claude 5.5 models: tools, parallel tools, prompt caching, (adaptive)
-    ** thinking.
+    ** thinking and vision (image input).
     *******************************************************************************/
    @Override
    public ModelCapabilities getCapabilities(String modelId)
@@ -237,6 +255,7 @@ public class AnthropicModelProvider implements AssistantModelProvider
          .withParallelToolCalls(true)
          .withPromptCaching(true)
          .withThinking(true)
+         .withVision(true)
          .withMaxContextTokens(200_000));
    }
 
@@ -260,6 +279,26 @@ public class AnthropicModelProvider implements AssistantModelProvider
          return (handle);
       }
 
+      if(Boolean.FALSE.equals(request.getStreaming()))
+      {
+         java.util.concurrent.Future<?> completion = executor.submit(() ->
+         {
+            try
+            {
+               handle.complete(AnthropicMapping.toResponse(client.messages().create(params)));
+            }
+            catch(Throwable error)
+            {
+               if(!handle.isCancelled())
+               {
+                  handle.fail(AnthropicMapping.toProviderException(error));
+               }
+            }
+         });
+         handle.setOnCancel(() -> completion.cancel(true));
+         return (handle);
+      }
+
       AtomicReference<ModelUsage> seen = new AtomicReference<>();
       handle.setPartialUsage(seen::get);
 

qbit-assistant-provider-anthropic/src/main/java/com/kingsrook/qbits/assistant/provider/anthropic/AnthropicProviderType.java

@@ -18,8 +18,8 @@ package com.kingsrook.qbits.assistant.provider.anthropic;
 
 
 import java.util.List;
-import com.kingsrook.qbits.assistant.provider.AssistantModelProvider;
-import com.kingsrook.qbits.assistant.provider.AssistantProviderType;
+import com.kingsrook.qbits.assistant.spi.AssistantModelProvider;
+import com.kingsrook.qbits.assistant.spi.AssistantProviderType;
 
 
 /*******************************************************************************

qbit-assistant-provider-anthropic/src/test/java/com/kingsrook/qbits/assistant/provider/anthropic/AnthropicModelProviderTest.java

@@ -24,16 +24,16 @@ import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import com.fasterxml.jackson.core.type.TypeReference;
-import com.kingsrook.qbits.assistant.provider.CacheHint;
-import com.kingsrook.qbits.assistant.provider.ModelEventListener;
-import com.kingsrook.qbits.assistant.provider.ModelMessage;
-import com.kingsrook.qbits.assistant.provider.ModelPart;
-import com.kingsrook.qbits.assistant.provider.ModelProviderException;
-import com.kingsrook.qbits.assistant.provider.ModelRequest;
-import com.kingsrook.qbits.assistant.provider.ModelResponse;
-import com.kingsrook.qbits.assistant.provider.ModelToolDefinition;
-import com.kingsrook.qbits.assistant.provider.StreamHandle;
-import com.kingsrook.qbits.assistant.provider.SystemBlock;
+import com.kingsrook.qbits.assistant.spi.CacheHint;
+import com.kingsrook.qbits.assistant.spi.ModelEventListener;
+import com.kingsrook.qbits.assistant.spi.ModelMessage;
+import com.kingsrook.qbits.assistant.spi.ModelPart;
+import com.kingsrook.qbits.assistant.spi.ModelProviderException;
+import com.kingsrook.qbits.assistant.spi.ModelRequest;
+import com.kingsrook.qbits.assistant.spi.ModelResponse;
+import com.kingsrook.qbits.assistant.spi.ModelToolDefinition;
+import com.kingsrook.qbits.assistant.spi.StreamHandle;
+import com.kingsrook.qbits.assistant.spi.SystemBlock;
 import com.kingsrook.qqq.backend.core.utils.JsonUtils;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
@@ -51,6 +51,39 @@ import static org.assertj.core.api.Assertions.assertThatThrownBy;
  *******************************************************************************/
 class AnthropicModelProviderTest
 {
+   /*******************************************************************************
+    ** Routing requests use a single JSON reply without text deltas.
+    *******************************************************************************/
+   @Test
+   void nonStreamingClassifier() throws Exception
+   {
+      server.thenError(200, "classifier-response.json");
+      ModelRequest request = new ModelRequest().withModel("claude-sonnet-5-5").withMaxTokens(4).withStreaming(false)
+         .withMessages(List.of(ModelMessage.user("hello")));
+      List<String> deltas = new ArrayList<>();
+      ModelResponse response = provider.stream(request, deltas::add).await(Duration.ofSeconds(3));
+      assertThat(response.getText()).isEqualTo("SIMPLE");
+      assertThat(response.getUsage().getOutputTokens()).isEqualTo(1L);
+      assertThat(deltas).isEmpty();
+      assertThat(sentBody(0).get("stream")).isIn(null, false);
+      assertThat(sentBody(0).get("max_tokens")).isEqualTo(4);
+   }
+
+
+
+   /*******************************************************************************
+    ** Non-streaming errors retain the normal exception mapping.
+    *******************************************************************************/
+   @Test
+   void nonStreamingError() throws Exception
+   {
+      server.thenError(401, "unauthorized.json");
+      assertThatThrownBy(() -> provider.stream(request().withStreaming(false), new StringBuilder()::append).await(Duration.ofSeconds(3)))
+         .isInstanceOfSatisfying(ModelProviderException.class, error -> assertThat(error.getKind()).isEqualTo(ModelProviderException.Kind.AUTHENTICATION));
+   }
+
+
+
    private static final String TEST_KEY = "sk-ant-test-0000000000000000000000";
 
    private RecordedAnthropicServer server;
@@ -342,4 +375,28 @@ class AnthropicModelProviderTest
          .hasMessageContaining("ANTHROPIC_API_KEY");
    }
 
+
+
+
+   /*******************************************************************************
+    ** An injected cloud-capable client wins over the key and HTTP builder options.
+    *******************************************************************************/
+   @Test
+   void injectedClientTakesPrecedence() throws Exception
+   {
+      server.thenStream("text-with-thinking.sse", 0);
+      var client = com.anthropic.client.okhttp.AnthropicOkHttpClient.builder().apiKey(TEST_KEY).baseUrl(server.baseUrl()).maxRetries(0).build();
+      var injected = AnthropicModelProvider.builder().client(client).apiKey(null).baseUrl("https://unused.invalid").build();
+      try
+      {
+         var response = injected.stream(request(), delta -> {}).await(Duration.ofSeconds(10));
+         assertThat(response.getText()).isEqualTo("There are 4 published posts.");
+         assertThat(server.getRequests()).hasSize(1);
+         assertThat(server.getRequests().getFirst().get("apiKey")).isEqualTo(TEST_KEY);
+      }
+      finally
+      {
+         injected.close();
+      }
+   }
 }

qbit-assistant-provider-anthropic/src/test/java/com/kingsrook/qbits/assistant/provider/anthropic/AnthropicRequestContractTest.java

@@ -26,10 +26,13 @@ import java.util.Set;
 import com.anthropic.core.ObjectMappers;
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.kingsrook.qbits.assistant.AssistantQBitConfig;
-import com.kingsrook.qbits.assistant.provider.ModelProviderException;
-import com.kingsrook.qbits.assistant.provider.ModelRequest;
-import com.kingsrook.qbits.assistant.provider.ModelToolDefinition;
 import com.kingsrook.qbits.assistant.provider.fake.ScriptedModelProvider;
+import com.kingsrook.qbits.assistant.spi.CacheHint;
+import com.kingsrook.qbits.assistant.spi.ModelMessage;
+import com.kingsrook.qbits.assistant.spi.ModelPart;
+import com.kingsrook.qbits.assistant.spi.ModelProviderException;
+import com.kingsrook.qbits.assistant.spi.ModelRequest;
+import com.kingsrook.qbits.assistant.spi.ModelToolDefinition;
 import com.kingsrook.qbits.assistant.testing.AssistantTestFixture;
 import com.kingsrook.qbits.assistant.testing.TurnRunner;
 import com.kingsrook.qqq.backend.core.context.QContext;
@@ -94,6 +97,27 @@ class AnthropicRequestContractTest
 
 
 
+   /*******************************************************************************
+    ** An image part becomes a base64 image block; as the last block of the
+    ** newest message it carries the cache hint.
+    *******************************************************************************/
+   @Test
+   @SuppressWarnings("unchecked")
+   void testImagePartMapping() throws Exception
+   {
+      ModelRequest request = new ModelRequest().withModel("claude-test").withMaxTokens(64).withMessages(List.of(new ModelMessage().withRole(ModelMessage.Role.USER)
+         .withPart(ModelPart.text("Describe it")).withPart(ModelPart.image("image/webp", "UklGRg==")).withCacheHint(CacheHint.SHORT)));
+      String              json  = ObjectMappers.jsonMapper().writeValueAsString(AnthropicMapping.toParams(request)._body());
+      Map<String, Object> body  = JsonUtils.toObject(json, new TypeReference<Map<String, Object>>() {});
+      List<Object>        content = (List<Object>) ((Map<String, Object>) ((List<Object>) body.get("messages")).get(0)).get("content");
+      Map<String, Object> image = (Map<String, Object>) content.get(1);
+      assertThat(image).containsEntry("type", "image").containsKey("cache_control");
+      assertThat((Map<String, Object>) image.get("source")).containsEntry("type", "base64").containsEntry("media_type", "image/webp").containsEntry("data", "UklGRg==");
+      assertThat((Map<String, Object>) content.get(0)).doesNotContainKey("cache_control");
+   }
+
+
+
    /*******************************************************************************
     ** The default request meets every documented constraint and the budget.
     *******************************************************************************/
@@ -108,6 +132,24 @@ class AnthropicRequestContractTest
 
 
 
+   /*******************************************************************************
+    ** Presentation remains inside the actual serialized strict request budget.
+    *******************************************************************************/
+   @Test
+   void testPresentationStrictOptIn() throws Exception
+   {
+      Map<String, Object> body = requestBody(new AssistantQBitConfig().withModelProvider(new ScriptedModelProvider()).withStrictToolNames(Set.of("present_results")));
+      assertThat(violations(body)).isEmpty();
+      assertThat(strictBudgetViolations(body)).isEmpty();
+      assertThat(tools(body)).anySatisfy(tool ->
+      {
+         assertThat(tool.get("name")).isEqualTo("present_results");
+         assertThat(tool.get("strict")).isEqualTo(true);
+      });
+   }
+
+
+
    /*******************************************************************************
     ** The RC.3 shape (every tool strict) is recognized as over budget, and a
     ** host can still opt a few tools in.

qbit-assistant-provider-anthropic/src/test/java/com/kingsrook/qbits/assistant/provider/anthropic/LiveGoldenEvalTest.java

@@ -24,6 +24,7 @@ import com.kingsrook.qbits.assistant.testing.GoldenTasks;
 import com.kingsrook.qbits.assistant.testing.TurnRunner;
 import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.permissions.ClientChannelsMetaData;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Tag;
@@ -102,6 +103,10 @@ class LiveGoldenEvalTest
    @MethodSource("tasks")
    void live(GoldenTasks.Task task) throws Exception
    {
+      if("D-page-12-this-week".equals(task.id()))
+      {
+         ClientChannelsMetaData.ofOrWithNew(qInstance).getDeniedPatterns().get("assistant").remove("audit*");
+      }
       TurnRunner.Outcome outcome = new TurnRunner(qInstance, config).run(task.userId(), task.prompt());
       assertThat(outcome.errorCode()).as("error").isNull();
       task.liveCheck().accept(outcome);

qbit-assistant-provider-anthropic/src/test/java/com/kingsrook/qbits/assistant/provider/anthropic/demo/AssistantDemoServer.java

@@ -24,7 +24,6 @@ import java.util.Map;
 import java.util.Set;
 import com.kingsrook.qbits.assistant.AssistantQBitConfig;
 import com.kingsrook.qbits.assistant.engine.ConnectionTest;
-import com.kingsrook.qbits.assistant.engine.ModelPricing;
 import com.kingsrook.qbits.assistant.metadata.AssistantMetaDataBuilder;
 import com.kingsrook.qbits.assistant.model.AssistantModelPrice;
 import com.kingsrook.qbits.assistant.model.AssistantProvider;
@@ -32,6 +31,7 @@ import com.kingsrook.qbits.assistant.provider.anthropic.AnthropicModelProvider;
 import com.kingsrook.qbits.assistant.provider.anthropic.AnthropicProviderType;
 import com.kingsrook.qbits.assistant.provider.anthropic.RecordedAnthropicServer;
 import com.kingsrook.qbits.assistant.provider.fake.ScriptedModelProvider;
+import com.kingsrook.qbits.assistant.spi.ModelPricing;
 import com.kingsrook.qbits.assistant.testing.AssistantTestFixture;
 import com.kingsrook.qbits.assistant.testing.TurnRunner;
 import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;

qbit-assistant-provider-anthropic/src/test/resources/fixtures/classifier-response.json

@@ -0,0 +1 @@
+{"id":"msg_classify","type":"message","role":"assistant","model":"claude-sonnet-5-5","content":[{"type":"text","text":"SIMPLE"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":18,"output_tokens":1}}

qbit-assistant-provider-api/pom.xml

@@ -0,0 +1,116 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Copyright 2026 Kingsrook, LLC
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+   <modelVersion>4.0.0</modelVersion>
+
+   <parent>
+      <groupId>com.kingsrook.qbits</groupId>
+      <artifactId>qbit-assistant-parent</artifactId>
+      <version>${revision}</version>
+   </parent>
+
+   <artifactId>qbit-assistant-provider-api</artifactId>
+   <packaging>jar</packaging>
+
+   <name>QBit Assistant - Provider API</name>
+   <description>Provider SPI and pricing value types, independent of the assistant runtime</description>
+   <url>https://github.com/QRun-IO/qbit-assistant</url>
+
+   <dependencies>
+      <dependency>
+         <groupId>com.fasterxml.jackson.core</groupId>
+         <artifactId>jackson-annotations</artifactId>
+      </dependency>
+      <dependency>
+         <groupId>com.fasterxml.jackson.core</groupId>
+         <artifactId>jackson-databind</artifactId>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>org.junit.jupiter</groupId>
+         <artifactId>junit-jupiter</artifactId>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>org.assertj</groupId>
+         <artifactId>assertj-core</artifactId>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>com.tngtech.archunit</groupId>
+         <artifactId>archunit-junit5</artifactId>
+         <scope>test</scope>
+      </dependency>
+   </dependencies>
+
+   <build>
+      <plugins>
+         <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-surefire-plugin</artifactId>
+            <configuration>
+               <redirectTestOutputToFile>true</redirectTestOutputToFile>
+            </configuration>
+         </plugin>
+         <plugin>
+            <groupId>org.jacoco</groupId>
+            <artifactId>jacoco-maven-plugin</artifactId>
+            <executions>
+               <execution>
+                  <id>prepare-agent</id>
+                  <goals>
+                     <goal>prepare-agent</goal>
+                  </goals>
+               </execution>
+               <execution>
+                  <id>report</id>
+                  <phase>verify</phase>
+                  <goals>
+                     <goal>report</goal>
+                  </goals>
+               </execution>
+               <execution>
+                  <id>check</id>
+                  <goals>
+                     <goal>check</goal>
+                  </goals>
+                  <configuration>
+                     <rules>
+                        <rule>
+                           <element>BUNDLE</element>
+                           <limits>
+                              <limit>
+                                 <counter>INSTRUCTION</counter>
+                                 <value>COVEREDRATIO</value>
+                                 <minimum>0.70</minimum>
+                              </limit>
+                              <limit>
+                                 <counter>CLASS</counter>
+                                 <value>COVEREDRATIO</value>
+                                 <minimum>0.90</minimum>
+                              </limit>
+                           </limits>
+                        </rule>
+                     </rules>
+                  </configuration>
+               </execution>
+            </executions>
+         </plugin>
+      </plugins>
+   </build>
+</project>

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/AssistantModelProvider.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package com.kingsrook.qbits.assistant.provider;
+package com.kingsrook.qbits.assistant.spi;
 
 
 /*******************************************************************************
@@ -58,4 +58,14 @@ public interface AssistantModelProvider
       return (null);
    }
 
+
+
+   /*******************************************************************************
+    ** Optional embedding capability. Unsupported adapters fail before transport.
+    *******************************************************************************/
+   default EmbeddingResponse embed(EmbeddingRequest request) throws ModelProviderException
+   {
+      throw (new ModelProviderException(ModelProviderException.Kind.INVALID_REQUEST, null, "Embeddings are unsupported by this provider."));
+   }
+
 }

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/AssistantProviderType.java

@@ -0,0 +1,161 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.spi;
+
+
+import java.util.List;
+
+
+/*******************************************************************************
+ ** A kind of model provider an admin can configure in the assistant_provider
+ ** table (Anthropic now; OpenAI-compatible, Bedrock and others plug in the
+ ** same way). Hosts register types with AssistantQBitConfig.withProviderType;
+ ** the provider settings screen offers the registered types and their models.
+ **
+ ** create() receives the API key already resolved from its reference; it must
+ ** never log the key or put it in toString or exception messages.
+ *******************************************************************************/
+public interface AssistantProviderType
+{
+
+   /*******************************************************************************
+    ** The type's id, stored in assistant_provider.providerType (e.g. "anthropic").
+    *******************************************************************************/
+   String getType();
+
+   /*******************************************************************************
+    ** A label for the settings screen.
+    *******************************************************************************/
+   String getLabel();
+
+   /*******************************************************************************
+    ** The models offered for this type, best default first.
+    *******************************************************************************/
+   List<String> getModels();
+
+   /*******************************************************************************
+    ** The environment variable that holds the key by default (e.g.
+    ** ANTHROPIC_API_KEY).
+    *******************************************************************************/
+   String getDefaultApiKeyEnvName();
+
+   /*******************************************************************************
+    ** The provider's own API base URL (shown when no override is set).
+    *******************************************************************************/
+   String getDefaultBaseUrl();
+
+   /*******************************************************************************
+    ** Build a provider. apiKey is the resolved secret (never null or empty);
+    ** baseUrl is null for the type's default.
+    *******************************************************************************/
+   AssistantModelProvider create(String apiKey, String baseUrl);
+
+
+
+
+   /*******************************************************************************
+    ** Backward-compatible provider registry extension.
+    *******************************************************************************/
+   default List<String> getKinds()
+   {
+      return (List.of(getType().toUpperCase(java.util.Locale.ROOT).replace('-', '_')));
+   }
+
+
+
+   /*******************************************************************************
+    ** Backward-compatible provider registry extension.
+    *******************************************************************************/
+   default String getDefaultBaseUrl(String kind)
+   {
+      return (getDefaultBaseUrl());
+   }
+
+
+
+   /*******************************************************************************
+    ** Backward-compatible provider registry extension.
+    *******************************************************************************/
+   default String getDefaultApiKeyEnvName(String kind)
+   {
+      return (getDefaultApiKeyEnvName());
+   }
+
+
+
+   /*******************************************************************************
+    ** Backward-compatible provider registry extension.
+    *******************************************************************************/
+   default String getDefaultLocation(String kind)
+   {
+      return ("CLOUD");
+   }
+
+
+
+   /*******************************************************************************
+    ** Backward-compatible provider registry extension.
+    *******************************************************************************/
+   default AssistantModelProvider create(ProviderSettings settings)
+   {
+      return (create(settings.getApiKey(), settings.getBaseUrl()));
+   }
+
+
+
+   /*******************************************************************************
+    ** Backward-compatible provider registry extension.
+    *******************************************************************************/
+   default List<DiscoveredModel> discoverModels(ProviderSettings settings) throws ModelProviderException
+   {
+      return (getModels().stream().map(id -> new DiscoveredModel(id, id, null, null)).toList());
+   }
+
+
+
+   /*******************************************************************************
+    ** Backward-compatible provider registry extension.
+    *******************************************************************************/
+   default HealthResult checkHealth(ProviderSettings settings)
+   {
+      return (new HealthResult(null, null, "Health check not supported"));
+   }
+
+
+
+   /*******************************************************************************
+    ** Additional settings errors, without resolving credentials or doing I/O.
+    ** Settings contain configured values and apiKeyEnvName; apiKey, the bearer
+    ** token supplier and SSLContext are not resolved for validation.
+    *******************************************************************************/
+   default List<String> validate(ProviderSettings settings)
+   {
+      return (List.of());
+   }
+
+
+
+   /*******************************************************************************
+    ** Whether this kind needs an explicit URL when it has no fixed default.
+    ** Cloud SDKs can instead derive their endpoint from region and project.
+    *******************************************************************************/
+   default boolean requiresBaseUrl(String kind)
+   {
+      return (getDefaultBaseUrl(kind) == null);
+   }
+
+}

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/CacheHint.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package com.kingsrook.qbits.assistant.provider;
+package com.kingsrook.qbits.assistant.spi;
 
 
 /*******************************************************************************

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/CompletableStreamHandle.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package com.kingsrook.qbits.assistant.provider;
+package com.kingsrook.qbits.assistant.spi;
 
 
 import java.time.Duration;
@@ -79,20 +79,29 @@ public class CompletableStreamHandle implements StreamHandle
 
 
    /*******************************************************************************
-    ** Finish with a response.
+    ** Finish with a response (ignored once cancelled: cancel() answers with a
+    ** cancelled response, and closing the stream may wake the worker first).
     *******************************************************************************/
    public void complete(ModelResponse response)
    {
+      if(cancelled.get())
+      {
+         return;
+      }
       future.complete(response);
    }
 
 
 
    /*******************************************************************************
-    ** Finish with an error.
+    ** Finish with an error (ignored once cancelled, see complete()).
     *******************************************************************************/
    public void fail(ModelProviderException exception)
    {
+      if(cancelled.get())
+      {
+         return;
+      }
       future.completeExceptionally(exception);
    }
 

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/DiscoveredModel.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.spi;
+
+
+/*******************************************************************************
+ ** A model advertised by the provider, without inferred capabilities.
+ *******************************************************************************/
+public record DiscoveredModel(String modelId, String displayName, Integer contextWindowTokens, String ownedBy)
+{
+}

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/EmbeddingRequest.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.spi;
+
+
+import java.util.List;
+
+
+/*******************************************************************************
+ ** One embedding batch. Providers accept at most 64 inputs per request.
+ *******************************************************************************/
+public record EmbeddingRequest(String model, List<String> input)
+{
+   /*******************************************************************************
+    ** Snapshot the inputs and reject empty or oversized batches before transport.
+    *******************************************************************************/
+   public EmbeddingRequest
+   {
+      input = List.copyOf(input);
+      if(model == null || model.isBlank() || input.isEmpty() || input.size() > 64)
+      {
+         throw (new IllegalArgumentException("An embedding request needs a model and 1 to 64 inputs."));
+      }
+   }
+}

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/EmbeddingResponse.java

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.spi;
+
+
+import java.util.List;
+
+
+/*******************************************************************************
+ ** Ordered vectors and billable usage. No input text is retained in the response.
+ *******************************************************************************/
+public record EmbeddingResponse(List<float[]> vectors, ModelUsage usage, String requestId)
+{
+}

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/HealthResult.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.spi;
+
+
+/*******************************************************************************
+ ** A health probe result; null healthy means unsupported.
+ *******************************************************************************/
+public record HealthResult(Boolean healthy, Long latencyMs, String message)
+{
+   /*******************************************************************************
+    ** Sanitize provider diagnostics.
+    *******************************************************************************/
+   public HealthResult
+   {
+      message = ModelProviderException.sanitizeProviderMessage(message, 300);
+   }
+}

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/ModelCapabilities.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package com.kingsrook.qbits.assistant.provider;
+package com.kingsrook.qbits.assistant.spi;
 
 
 /*******************************************************************************
@@ -23,6 +23,16 @@ package com.kingsrook.qbits.assistant.provider;
  *******************************************************************************/
 public class ModelCapabilities
 {
+
+   private Boolean vision = false;
+
+
+   private Boolean streaming = true;
+
+
+   private Boolean reasoningEffort = false;
+
+
    private Boolean tools             = true;
    private Boolean parallelToolCalls = true;
    private Boolean promptCaching     = false;
@@ -182,4 +192,98 @@ public class ModelCapabilities
       return (this);
    }
 
+
+
+
+   /*******************************************************************************
+    ** Getter for vision
+    *******************************************************************************/
+   public Boolean getVision()
+   {
+      return (this.vision);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for vision
+    *******************************************************************************/
+   public void setVision(Boolean vision)
+   {
+      this.vision = vision;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for vision
+    *******************************************************************************/
+   public ModelCapabilities withVision(Boolean vision)
+   {
+      this.vision = vision;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for streaming
+    *******************************************************************************/
+   public Boolean getStreaming()
+   {
+      return (this.streaming);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for streaming
+    *******************************************************************************/
+   public void setStreaming(Boolean streaming)
+   {
+      this.streaming = streaming;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for streaming
+    *******************************************************************************/
+   public ModelCapabilities withStreaming(Boolean streaming)
+   {
+      this.streaming = streaming;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for reasoningEffort
+    *******************************************************************************/
+   public Boolean getReasoningEffort()
+   {
+      return (this.reasoningEffort);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for reasoningEffort
+    *******************************************************************************/
+   public void setReasoningEffort(Boolean reasoningEffort)
+   {
+      this.reasoningEffort = reasoningEffort;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for reasoningEffort
+    *******************************************************************************/
+   public ModelCapabilities withReasoningEffort(Boolean reasoningEffort)
+   {
+      this.reasoningEffort = reasoningEffort;
+      return (this);
+   }
+
 }

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/ModelEventListener.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package com.kingsrook.qbits.assistant.provider;
+package com.kingsrook.qbits.assistant.spi;
 
 
 /*******************************************************************************

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/ModelMessage.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package com.kingsrook.qbits.assistant.provider;
+package com.kingsrook.qbits.assistant.spi;
 
 
 import java.util.ArrayList;

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/ModelPart.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package com.kingsrook.qbits.assistant.provider;
+package com.kingsrook.qbits.assistant.spi;
 
 
 import java.util.LinkedHashMap;
@@ -22,8 +22,10 @@ import java.util.Map;
 
 
 /*******************************************************************************
- ** One content part of a model message: text, a tool_use (assistant) or a
- ** tool_result (user). Tool results that report a failure set isError.
+ ** One content part of a model message: text, a tool_use (assistant), a
+ ** tool_result (user) or an image (user; base64 data plus its media type).
+ ** Tool results that report a failure set isError. toString never includes
+ ** text or image data, so a part can never leak content into a log line.
  *******************************************************************************/
 public class ModelPart
 {
@@ -34,7 +36,8 @@ public class ModelPart
    {
       TEXT,
       TOOL_USE,
-      TOOL_RESULT
+      TOOL_RESULT,
+      IMAGE
    }
 
    private Type                type;
@@ -43,6 +46,8 @@ public class ModelPart
    private String              toolName;
    private Map<String, Object> input;
    private Boolean             isError = false;
+   private String              mediaType;
+   private String              data;
 
 
 
@@ -76,6 +81,30 @@ public class ModelPart
 
 
 
+   /*******************************************************************************
+    ** An image part: the media type (image/png, image/jpeg, image/gif or
+    ** image/webp) and the base64-encoded bytes. Only for models whose
+    ** capabilities report vision.
+    *******************************************************************************/
+   public static ModelPart image(String mediaType, String base64Data)
+   {
+      return (new ModelPart().withType(Type.IMAGE).withMediaType(mediaType).withData(base64Data));
+   }
+
+
+
+   /*******************************************************************************
+    ** The kind and sizes only; never the text, input or image data.
+    *******************************************************************************/
+   @Override
+   public String toString()
+   {
+      return ("ModelPart{type=" + type + ", textChars=" + (text == null ? 0 : text.length()) + ", toolName=" + toolName
+         + (mediaType == null ? "" : ", mediaType=" + mediaType) + (data == null ? "" : ", dataChars=" + data.length()) + "}");
+   }
+
+
+
    /*******************************************************************************
     ** Getter for type
     *******************************************************************************/
@@ -260,4 +289,67 @@ public class ModelPart
       return (this);
    }
 
+
+
+
+   /*******************************************************************************
+    ** Getter for mediaType
+    *******************************************************************************/
+   public String getMediaType()
+   {
+      return (this.mediaType);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for mediaType
+    *******************************************************************************/
+   public void setMediaType(String mediaType)
+   {
+      this.mediaType = mediaType;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for mediaType
+    *******************************************************************************/
+   public ModelPart withMediaType(String mediaType)
+   {
+      this.mediaType = mediaType;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for data (base64)
+    *******************************************************************************/
+   public String getData()
+   {
+      return (this.data);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for data (base64)
+    *******************************************************************************/
+   public void setData(String data)
+   {
+      this.data = data;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for data (base64)
+    *******************************************************************************/
+   public ModelPart withData(String data)
+   {
+      this.data = data;
+      return (this);
+   }
+
 }

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/ModelPricing.java

@@ -14,14 +14,12 @@
  * limitations under the License.
  */
 
-package com.kingsrook.qbits.assistant.engine;
+package com.kingsrook.qbits.assistant.spi;
 
 
 import java.io.Serializable;
 import java.util.LinkedHashMap;
 import java.util.Map;
-import com.kingsrook.qbits.assistant.AssistantModelRouting;
-import com.kingsrook.qbits.assistant.provider.ModelUsage;
 
 
 /*******************************************************************************
@@ -63,9 +61,9 @@ public class ModelPricing implements Serializable
    public static Map<String, ModelPricing> defaults()
    {
       Map<String, ModelPricing> map = new LinkedHashMap<>();
-      map.put(AssistantModelRouting.SONNET_5_5, of(2.0, 10.0, 0.1));
-      map.put(AssistantModelRouting.OPUS_5_5, of(4.0, 20.0, 0.05));
-      map.put(AssistantModelRouting.HAIKU_5_5, of(0.10, 0.50, 0.1));
+      map.put("claude-sonnet-5-5", of(2.0, 10.0, 0.1));
+      map.put("claude-opus-5-5", of(4.0, 20.0, 0.05));
+      map.put("claude-haiku-5-5", of(0.10, 0.50, 0.1));
       map.put("claude-fable-5-1", of(10.0, 50.0, 0.025));
       map.put("claude-fable-5", of(10.0, 50.0, 0.1));
       map.put("claude-opus-5", of(5.0, 25.0, 0.1));

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/ModelProviderException.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package com.kingsrook.qbits.assistant.provider;
+package com.kingsrook.qbits.assistant.spi;
 
 
 /*******************************************************************************

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/ModelRequest.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package com.kingsrook.qbits.assistant.provider;
+package com.kingsrook.qbits.assistant.spi;
 
 
 import java.util.ArrayList;
@@ -32,6 +32,11 @@ import java.util.List;
  *******************************************************************************/
 public class ModelRequest
 {
+
+   private ModelCapabilities capabilities;
+
+
+   private Boolean                   streaming = true;
    private String                    model;
    private String                    effort;
    private Integer                   maxTokens;
@@ -48,7 +53,9 @@ public class ModelRequest
    public ModelRequest copy()
    {
       return (new ModelRequest()
+         .withStreaming(streaming)
          .withModel(model)
+         .withCapabilities(capabilities)
          .withEffort(effort)
          .withMaxTokens(maxTokens)
          .withParallelToolCalls(parallelToolCalls)
@@ -274,4 +281,57 @@ public class ModelRequest
       return (this);
    }
 
+
+
+
+   /*******************************************************************************
+    ** Getter for capabilities
+    *******************************************************************************/
+   public ModelCapabilities getCapabilities()
+   {
+      return (this.capabilities);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for capabilities
+    *******************************************************************************/
+   public void setCapabilities(ModelCapabilities capabilities)
+   {
+      this.capabilities = capabilities;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for capabilities
+    *******************************************************************************/
+   public ModelRequest withCapabilities(ModelCapabilities capabilities)
+   {
+      this.capabilities = capabilities;
+      return (this);
+   }
+
+
+
+
+   /*******************************************************************************
+    ** Whether to request streaming transport (classifiers use one JSON reply).
+    *******************************************************************************/
+   public Boolean getStreaming()
+   {
+      return (streaming);
+   }
+
+
+
+   /*******************************************************************************
+    ** Select streaming transport independently of model capability.
+    *******************************************************************************/
+   public ModelRequest withStreaming(Boolean streaming)
+   {
+      this.streaming = streaming;
+      return (this);
+   }
 }

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/ModelResponse.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package com.kingsrook.qbits.assistant.provider;
+package com.kingsrook.qbits.assistant.spi;
 
 
 import java.util.ArrayList;

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/ModelToolDefinition.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package com.kingsrook.qbits.assistant.provider;
+package com.kingsrook.qbits.assistant.spi;
 
 
 import java.util.Map;

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/ModelUsage.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package com.kingsrook.qbits.assistant.provider;
+package com.kingsrook.qbits.assistant.spi;
 
 
 /*******************************************************************************

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/ProviderSettings.java

@@ -0,0 +1,432 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.spi;
+
+
+import java.util.function.Supplier;
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import javax.net.ssl.SSLContext;
+
+
+/*******************************************************************************
+ ** Resolved connection settings. API keys and bearer-token suppliers are never
+ ** included in diagnostics. A supplier resolves a fresh token for each request.
+ *******************************************************************************/
+public class ProviderSettings
+{
+   @JsonIgnore
+   private Supplier<String> bearerTokenSupplier;
+
+   private String cloudProject;
+
+   private String tlsCaBundle;
+   @JsonIgnore
+   private transient SSLContext sslContext;
+   private String apiKeyEnvName;
+   private String kind;
+   private String apiKey;
+   private String baseUrl;
+   private String apiVersion;
+   private String region;
+   private Integer connectTimeoutSeconds = 10;
+   private Integer requestTimeoutSeconds = 120;
+
+
+
+   /*******************************************************************************
+    ** Getter for kind
+    *******************************************************************************/
+   public String getKind()
+   {
+      return (this.kind);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for kind
+    *******************************************************************************/
+   public void setKind(String kind)
+   {
+      this.kind = kind;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for kind
+    *******************************************************************************/
+   public ProviderSettings withKind(String kind)
+   {
+      this.kind = kind;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for apiKey
+    *******************************************************************************/
+   public String getApiKey()
+   {
+      return (this.apiKey);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for apiKey
+    *******************************************************************************/
+   public void setApiKey(String apiKey)
+   {
+      this.apiKey = apiKey;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for apiKey
+    *******************************************************************************/
+   public ProviderSettings withApiKey(String apiKey)
+   {
+      this.apiKey = apiKey;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for baseUrl
+    *******************************************************************************/
+   public String getBaseUrl()
+   {
+      return (this.baseUrl);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for baseUrl
+    *******************************************************************************/
+   public void setBaseUrl(String baseUrl)
+   {
+      this.baseUrl = baseUrl;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for baseUrl
+    *******************************************************************************/
+   public ProviderSettings withBaseUrl(String baseUrl)
+   {
+      this.baseUrl = baseUrl;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for apiVersion
+    *******************************************************************************/
+   public String getApiVersion()
+   {
+      return (this.apiVersion);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for apiVersion
+    *******************************************************************************/
+   public void setApiVersion(String apiVersion)
+   {
+      this.apiVersion = apiVersion;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for apiVersion
+    *******************************************************************************/
+   public ProviderSettings withApiVersion(String apiVersion)
+   {
+      this.apiVersion = apiVersion;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for region
+    *******************************************************************************/
+   public String getRegion()
+   {
+      return (this.region);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for region
+    *******************************************************************************/
+   public void setRegion(String region)
+   {
+      this.region = region;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for region
+    *******************************************************************************/
+   public ProviderSettings withRegion(String region)
+   {
+      this.region = region;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for connectTimeoutSeconds
+    *******************************************************************************/
+   public Integer getConnectTimeoutSeconds()
+   {
+      return (this.connectTimeoutSeconds);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for connectTimeoutSeconds
+    *******************************************************************************/
+   public void setConnectTimeoutSeconds(Integer connectTimeoutSeconds)
+   {
+      this.connectTimeoutSeconds = connectTimeoutSeconds;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for connectTimeoutSeconds
+    *******************************************************************************/
+   public ProviderSettings withConnectTimeoutSeconds(Integer connectTimeoutSeconds)
+   {
+      this.connectTimeoutSeconds = connectTimeoutSeconds;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for requestTimeoutSeconds
+    *******************************************************************************/
+   public Integer getRequestTimeoutSeconds()
+   {
+      return (this.requestTimeoutSeconds);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for requestTimeoutSeconds
+    *******************************************************************************/
+   public void setRequestTimeoutSeconds(Integer requestTimeoutSeconds)
+   {
+      this.requestTimeoutSeconds = requestTimeoutSeconds;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for requestTimeoutSeconds
+    *******************************************************************************/
+   public ProviderSettings withRequestTimeoutSeconds(Integer requestTimeoutSeconds)
+   {
+      this.requestTimeoutSeconds = requestTimeoutSeconds;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Safe diagnostic representation.
+    *******************************************************************************/
+   @Override
+   public String toString()
+   {
+      return ("ProviderSettings[kind=" + kind + "]");
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for tlsCaBundle
+    *******************************************************************************/
+   public String getTlsCaBundle()
+   {
+      return (this.tlsCaBundle);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for tlsCaBundle
+    *******************************************************************************/
+   public void setTlsCaBundle(String tlsCaBundle)
+   {
+      this.tlsCaBundle = tlsCaBundle;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for tlsCaBundle
+    *******************************************************************************/
+   public ProviderSettings withTlsCaBundle(String tlsCaBundle)
+   {
+      this.tlsCaBundle = tlsCaBundle;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for sslContext
+    *******************************************************************************/
+   @JsonIgnore
+   public SSLContext getSslContext()
+   {
+      return (this.sslContext);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for sslContext
+    *******************************************************************************/
+   public void setSslContext(SSLContext sslContext)
+   {
+      this.sslContext = sslContext;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for sslContext
+    *******************************************************************************/
+   public ProviderSettings withSslContext(SSLContext sslContext)
+   {
+      this.sslContext = sslContext;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for cloudProject
+    *******************************************************************************/
+   public String getCloudProject()
+   {
+      return (this.cloudProject);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for cloudProject
+    *******************************************************************************/
+   public void setCloudProject(String cloudProject)
+   {
+      this.cloudProject = cloudProject;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for cloudProject
+    *******************************************************************************/
+   public ProviderSettings withCloudProject(String cloudProject)
+   {
+      this.cloudProject = cloudProject;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for bearerTokenSupplier
+    *******************************************************************************/
+   @JsonIgnore
+   public Supplier<String> getBearerTokenSupplier()
+   {
+      return (this.bearerTokenSupplier);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for bearerTokenSupplier
+    *******************************************************************************/
+   public void setBearerTokenSupplier(Supplier<String> bearerTokenSupplier)
+   {
+      this.bearerTokenSupplier = bearerTokenSupplier;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for bearerTokenSupplier
+    *******************************************************************************/
+   public ProviderSettings withBearerTokenSupplier(Supplier<String> bearerTokenSupplier)
+   {
+      this.bearerTokenSupplier = bearerTokenSupplier;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** The configured environment variable name, never its secret value.
+    *******************************************************************************/
+   public String getApiKeyEnvName()
+   {
+      return (this.apiKeyEnvName);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for apiKeyEnvName
+    *******************************************************************************/
+   public void setApiKeyEnvName(String apiKeyEnvName)
+   {
+      this.apiKeyEnvName = apiKeyEnvName;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for apiKeyEnvName
+    *******************************************************************************/
+   public ProviderSettings withApiKeyEnvName(String apiKeyEnvName)
+   {
+      this.apiKeyEnvName = apiKeyEnvName;
+      return (this);
+   }
+}

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/StreamHandle.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package com.kingsrook.qbits.assistant.provider;
+package com.kingsrook.qbits.assistant.spi;
 
 
 import java.time.Duration;

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/SystemBlock.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package com.kingsrook.qbits.assistant.provider;
+package com.kingsrook.qbits.assistant.spi;
 
 
 /*******************************************************************************

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/TokenCount.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package com.kingsrook.qbits.assistant.provider;
+package com.kingsrook.qbits.assistant.spi;
 
 
 /*******************************************************************************

qbit-assistant-provider-api/src/main/java/com/kingsrook/qbits/assistant/spi/TrustedCaBundle.java

@@ -0,0 +1,153 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.spi;
+
+
+import java.io.ByteArrayInputStream;
+import java.nio.charset.StandardCharsets;
+import java.security.KeyStore;
+import java.security.cert.CertificateException;
+import java.security.cert.CertificateFactory;
+import java.security.cert.X509Certificate;
+import java.util.Arrays;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+import java.util.stream.Stream;
+import javax.net.ssl.SSLContext;
+import javax.net.ssl.TrustManager;
+import javax.net.ssl.TrustManagerFactory;
+import javax.net.ssl.X509TrustManager;
+
+
+/*******************************************************************************
+ ** Builds additive trust: JVM roots OR explicitly configured certificates.
+ ** Endpoint identification remains the HTTP client's responsibility and is enabled.
+ *******************************************************************************/
+public final class TrustedCaBundle implements X509TrustManager
+{
+   private final X509TrustManager defaults;
+   private final X509TrustManager additional;
+
+
+
+   /*******************************************************************************
+    ** Two independently validating trust managers, never a trust-all fallback.
+    *******************************************************************************/
+   TrustedCaBundle(X509TrustManager defaults, X509TrustManager additional)
+   {
+      this.defaults = defaults;
+      this.additional = additional;
+   }
+
+
+
+   /*******************************************************************************
+    ** Accept only one or more complete PEM certificates; reject trailing garbage.
+    *******************************************************************************/
+   public static SSLContext parse(String pem)
+   {
+      try
+      {
+         KeyStore store = KeyStore.getInstance(KeyStore.getDefaultType());
+         store.load(null, null);
+         CertificateFactory factory = CertificateFactory.getInstance("X.509");
+         Matcher matcher = Pattern.compile("-----BEGIN CERTIFICATE-----[\\s\\S]*?-----END CERTIFICATE-----").matcher(pem == null ? "" : pem);
+         int end = 0;
+         int count = 0;
+         while(matcher.find())
+         {
+            if(!pem.substring(end, matcher.start()).isBlank())
+            {
+               throw (new CertificateException());
+            }
+            X509Certificate certificate = (X509Certificate) factory.generateCertificate(new ByteArrayInputStream(matcher.group().getBytes(StandardCharsets.US_ASCII)));
+            store.setCertificateEntry("ca-" + count++, certificate);
+            end = matcher.end();
+         }
+         if(count == 0 || !pem.substring(end).isBlank())
+         {
+            throw (new CertificateException());
+         }
+         SSLContext context = SSLContext.getInstance("TLS");
+         context.init(null, new TrustManager[] { new TrustedCaBundle(manager(null), manager(store)) }, null);
+         return (context);
+      }
+      catch(Exception e)
+      {
+         throw (new IllegalArgumentException("Invalid CA bundle: expected one or more PEM X.509 certificates."));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** A null store asks JSSE to load the JVM's configured default trust roots.
+    *******************************************************************************/
+   private static X509TrustManager manager(KeyStore store) throws Exception
+   {
+      TrustManagerFactory factory = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
+      factory.init(store);
+      return (Arrays.stream(factory.getTrustManagers()).filter(X509TrustManager.class::isInstance).map(X509TrustManager.class::cast).findFirst().orElseThrow());
+   }
+
+
+
+   /*******************************************************************************
+    ** Client validation uses the same additive trust rule.
+    *******************************************************************************/
+   @Override
+   public void checkClientTrusted(X509Certificate[] chain, String authType) throws CertificateException
+   {
+      try
+      {
+         defaults.checkClientTrusted(chain, authType);
+      }
+      catch(CertificateException e)
+      {
+         additional.checkClientTrusted(chain, authType);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Try JVM roots first, then the named bundle, preserving chain validation.
+    *******************************************************************************/
+   @Override
+   public void checkServerTrusted(X509Certificate[] chain, String authType) throws CertificateException
+   {
+      try
+      {
+         defaults.checkServerTrusted(chain, authType);
+      }
+      catch(CertificateException e)
+      {
+         additional.checkServerTrusted(chain, authType);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Both sets of issuers remain accepted.
+    *******************************************************************************/
+   @Override
+   public X509Certificate[] getAcceptedIssuers()
+   {
+      return (Stream.concat(Arrays.stream(defaults.getAcceptedIssuers()), Arrays.stream(additional.getAcceptedIssuers())).toArray(X509Certificate[]::new));
+   }
+}

qbit-assistant-provider-api/src/test/java/com/kingsrook/qbits/assistant/spi/ProviderApiArchitectureTest.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.spi;
+
+
+import com.tngtech.archunit.core.domain.JavaClasses;
+import com.tngtech.archunit.core.importer.ClassFileImporter;
+import org.junit.jupiter.api.Test;
+import static com.tngtech.archunit.core.domain.JavaClass.Predicates.resideInAPackage;
+import static com.tngtech.archunit.core.domain.JavaClass.Predicates.resideOutsideOfPackage;
+import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;
+import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;
+
+
+/*******************************************************************************
+ ** Keep external provider consumers independent of the assistant runtime and QQQ.
+ *******************************************************************************/
+class ProviderApiArchitectureTest
+{
+   /*******************************************************************************
+    ** Import the entire artifact so an accidental package outside spi also fails.
+    *******************************************************************************/
+   @Test
+   void dependsOnlyOnApiTypes()
+   {
+      String spiPackage = "com.kingsrook.qbits.assistant.spi";
+      JavaClasses imported = new ClassFileImporter().importUrl(AssistantModelProvider.class.getProtectionDomain().getCodeSource().getLocation());
+      classes().should().resideInAPackage(spiPackage).check(imported);
+      noClasses().should().dependOnClassesThat(resideInAPackage("com.kingsrook.qbits..").and(resideOutsideOfPackage(spiPackage))).check(imported);
+      noClasses().should().dependOnClassesThat().resideInAnyPackage("com.kingsrook.qqq..").check(imported);
+   }
+}

qbit-assistant-provider-api/src/test/java/com/kingsrook/qbits/assistant/spi/ProviderApiTest.java

@@ -0,0 +1,231 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.spi;
+
+
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.atomic.AtomicInteger;
+import com.fasterxml.jackson.databind.DeserializationFeature;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import javax.net.ssl.SSLContext;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+
+/*******************************************************************************
+ ** Provider contracts work on a classpath with no assistant runtime or QQQ.
+ *******************************************************************************/
+class ProviderApiTest
+{
+   private final ObjectMapper mapper = new ObjectMapper().disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
+
+
+
+   /*******************************************************************************
+    ** Preserve provider-neutral requests and tool order through JSON; signed
+    ** provider state remains in memory only.
+    *******************************************************************************/
+   @Test
+   void requestRoundTripAndCopy() throws Exception
+   {
+      ModelCapabilities capabilities = new ModelCapabilities().withTools(true).withParallelToolCalls(true)
+         .withPromptCaching(true).withThinking(false).withMaxContextTokens(32000)
+         .withVision(false).withStreaming(true).withReasoningEffort(true);
+      ModelToolDefinition tool = new ModelToolDefinition().withName("lookup").withDescription("Look up a record")
+         .withInputSchema(Map.of("type", "object")).withStrict(true);
+      ModelMessage user = ModelMessage.user("Find it").withCacheHint(CacheHint.SHORT);
+      ModelMessage assistant = ModelMessage.assistant("Looking").withPart(ModelPart.toolUse("call-1", "lookup", null))
+         .withProviderState("private-signature");
+      ModelMessage result = new ModelMessage().withRole(ModelMessage.Role.USER)
+         .withParts(List.of(ModelPart.toolResult("call-1", "denied", true)));
+      ModelRequest request = new ModelRequest().withModel("example").withEffort("low").withMaxTokens(100)
+         .withParallelToolCalls(true).withStreaming(false).withCapabilities(capabilities)
+         .withSystem(List.of(new SystemBlock("rules", CacheHint.LONG), new SystemBlock().withText("user context").withCacheHint(CacheHint.SHORT)))
+         .withTools(List.of(tool)).withMessages(new ArrayList<>(List.of(user, assistant, result)));
+      String json = mapper.writeValueAsString(request);
+      assertThat(json).doesNotContain("private-signature", "providerState");
+      ModelRequest restored = mapper.readValue(json, ModelRequest.class);
+      assertThat(mapper.<JsonNode>valueToTree(restored)).isEqualTo(mapper.valueToTree(request));
+      assertThat(restored.getMessages().get(1).getProviderState()).isNull();
+      assertThat(restored.getMessages().get(2).getParts().get(0).getIsError()).isTrue();
+      ModelRequest copy = request.copy();
+      assertThat(mapper.<JsonNode>valueToTree(copy)).isEqualTo(mapper.valueToTree(request));
+      copy.getMessages().clear();
+      assertThat(request.getMessages()).hasSize(3);
+   }
+
+
+
+   /*******************************************************************************
+    ** An image part keeps its media type and data through JSON, and toString
+    ** never shows text or image data.
+    *******************************************************************************/
+   @Test
+   void imagePartRoundTripAndSafeToString() throws Exception
+   {
+      ModelPart image = ModelPart.image("image/png", "iVBORw0KGgoSECRETDATA");
+      assertThat(image.getType()).isEqualTo(ModelPart.Type.IMAGE);
+      ModelPart restored = mapper.readValue(mapper.writeValueAsString(image), ModelPart.class);
+      assertThat(restored.getMediaType()).isEqualTo("image/png");
+      assertThat(restored.getData()).isEqualTo("iVBORw0KGgoSECRETDATA");
+      assertThat(image.toString()).contains("IMAGE", "image/png").doesNotContain("SECRETDATA");
+      assertThat(ModelPart.text("private words").toString()).doesNotContain("private words");
+   }
+
+
+
+   /*******************************************************************************
+    ** Response helpers retain tool ordering, text, usage and safe metadata.
+    *******************************************************************************/
+   @Test
+   void responseAndPricingRoundTrip() throws Exception
+   {
+      ModelUsage usage = new ModelUsage().withInputTokens(2L).withOutputTokens(3L)
+         .withCacheReadTokens(4L).withCacheWriteTokens(5L).withCacheWrite1hTokens(1L);
+      ModelPart first = ModelPart.toolUse("first", "lookup", Map.of("id", 1));
+      ModelPart second = ModelPart.toolUse("second", "lookup", Map.of("id", 2));
+      ModelResponse response = new ModelResponse().withParts(List.of(ModelPart.text("a"), first, ModelPart.text("b"), second))
+         .withModel("example").withStopReason(ModelResponse.STOP_TOOL_USE).withRequestId("request-1")
+         .withUsage(usage).withProviderState("signature");
+      assertThat(response.getText()).isEqualTo("ab");
+      assertThat(response.getToolUses()).containsExactly(first, second);
+      String json = mapper.writeValueAsString(response);
+      assertThat(json).doesNotContain("signature", "providerState");
+      ModelResponse restored = mapper.readValue(json, ModelResponse.class);
+      assertThat(mapper.<JsonNode>valueToTree(restored)).isEqualTo(mapper.valueToTree(response));
+      assertThat(restored.getProviderState()).isNull();
+      assertThat(response.getProviderState()).isEqualTo("signature");
+      ModelPricing pricing = ModelPricing.of(0.1, 0.5, 0.1);
+      ModelPricing restoredPricing = mapper.readValue(mapper.writeValueAsString(pricing), ModelPricing.class);
+      assertThat(restoredPricing.costMicros(usage)).isEqualTo(3);
+      assertThat(new ModelUsage().withInputTokens(null).add(usage).add(null).billableTokens()).isEqualTo(10);
+      TokenCount tokens = mapper.readValue(mapper.writeValueAsString(new TokenCount().withInputTokens(12L)), TokenCount.class);
+      assertThat(tokens.getInputTokens()).isEqualTo(12L);
+   }
+
+
+
+   /*******************************************************************************
+    ** Plain validation settings require no credentials or entity classes, and
+    ** live token suppliers/TLS contexts cannot be serialized into diagnostics.
+    *******************************************************************************/
+   @Test
+   void settingsRoundTrip() throws Exception
+   {
+      ProviderSettings settings = new ProviderSettings().withKind("EXAMPLE").withApiKeyEnvName("EXAMPLE_KEY")
+         .withApiKey("test-only-key").withBaseUrl("https://example.invalid").withApiVersion("v1")
+         .withRegion("region").withCloudProject("project").withTlsCaBundle("corporate")
+         .withConnectTimeoutSeconds(5).withRequestTimeoutSeconds(30)
+         .withBearerTokenSupplier(() -> "ephemeral-token").withSslContext(SSLContext.getDefault());
+      String json = mapper.writeValueAsString(settings);
+      assertThat(json).doesNotContain("ephemeral-token", "bearerTokenSupplier", "sslContext");
+      ProviderSettings restored = mapper.readValue(json, ProviderSettings.class);
+      assertThat(mapper.<JsonNode>valueToTree(restored)).isEqualTo(mapper.valueToTree(settings));
+      assertThat(settings.getBearerTokenSupplier().get()).isEqualTo("ephemeral-token");
+      assertThat(settings.getSslContext()).isNotNull();
+      assertThat(restored.getBearerTokenSupplier()).isNull();
+      assertThat(restored.getSslContext()).isNull();
+   }
+
+
+
+   /*******************************************************************************
+    ** Embedding batches snapshot input and enforce the transport size contract.
+    *******************************************************************************/
+   @Test
+   void embeddingContracts()
+   {
+      List<String> input = new ArrayList<>(List.of("first", "second"));
+      EmbeddingRequest request = new EmbeddingRequest("embed", input);
+      input.clear();
+      assertThat(request.input()).containsExactly("first", "second");
+      assertThatThrownBy(() -> request.input().add("third")).isInstanceOf(UnsupportedOperationException.class);
+      assertThatThrownBy(() -> new EmbeddingRequest(" ", List.of("text"))).isInstanceOf(IllegalArgumentException.class);
+      assertThatThrownBy(() -> new EmbeddingRequest(null, List.of("text"))).isInstanceOf(IllegalArgumentException.class);
+      assertThatThrownBy(() -> new EmbeddingRequest("embed", List.of())).isInstanceOf(IllegalArgumentException.class);
+      assertThatThrownBy(() -> new EmbeddingRequest("embed", Collections.nCopies(65, "text"))).isInstanceOf(IllegalArgumentException.class);
+      assertThat(new EmbeddingRequest("embed", Collections.nCopies(64, "text")).input()).hasSize(64);
+      float[] vector = new float[] { 0.25F, 0.75F };
+      EmbeddingResponse response = new EmbeddingResponse(List.of(vector), new ModelUsage().withInputTokens(2L), "request");
+      assertThat(response.vectors().getFirst()).containsExactly(0.25F, 0.75F);
+      assertThat(response.usage().getInputTokens()).isEqualTo(2L);
+      assertThat(response.requestId()).isEqualTo("request");
+   }
+
+
+
+   /*******************************************************************************
+    ** Cancellation is idempotent, preserves accrued usage, and wins over late
+    ** completion. Timeout also cancels the underlying transport.
+    *******************************************************************************/
+   @Test
+   void cancellationAndTimeout() throws Exception
+   {
+      AtomicInteger cancellations = new AtomicInteger();
+      ModelUsage usage = new ModelUsage().withInputTokens(10L);
+      CompletableStreamHandle handle = new CompletableStreamHandle();
+      handle.setPartialUsage(() -> usage);
+      handle.setOnCancel(cancellations::incrementAndGet);
+      handle.cancel();
+      handle.cancel();
+      handle.complete(new ModelResponse().withStopReason(ModelResponse.STOP_END_TURN));
+      handle.fail(new ModelProviderException(ModelProviderException.Kind.SERVER, 500, "late failure"));
+      assertThat(handle.isCancelled()).isTrue();
+      assertThat(cancellations.get()).isEqualTo(1);
+      assertThat(handle.await(Duration.ofSeconds(1)).getUsage()).isSameAs(usage);
+      CompletableStreamHandle timeout = new CompletableStreamHandle();
+      timeout.setPartialUsage(() -> usage);
+      assertThatThrownBy(() -> timeout.await(Duration.ofMillis(1))).isInstanceOfSatisfying(ModelProviderException.class, error ->
+      {
+         assertThat(error.getKind()).isEqualTo(ModelProviderException.Kind.TIMEOUT);
+         assertThat(error.getPartialUsage()).isSameAs(usage);
+      });
+      assertThat(timeout.isCancelled()).isTrue();
+      handle.setPartialUsage(() ->
+      {
+         throw (new IllegalStateException("closed"));
+      });
+      assertThat(handle.partialUsage()).isNull();
+   }
+
+
+
+   /*******************************************************************************
+    ** Error metadata is bounded and redacted independently of error classification.
+    *******************************************************************************/
+   @Test
+   void errorDetails()
+   {
+      ModelProviderException error = new ModelProviderException(ModelProviderException.Kind.INVALID_REQUEST, 400, "Invalid schema")
+         .withStrictSchemaRejected(true).withProviderDetails("invalid_request", "bad key sk-abcdefghijk\ntry again", "req-123");
+      assertThat(error.isStrictSchemaRejected()).isTrue();
+      assertThat(error.getProviderErrorType()).isEqualTo("invalid_request");
+      assertThat(error.getProviderMessage()).isEqualTo("bad key [redacted] try again");
+      assertThat(error.getRequestId()).isEqualTo("req-123");
+      assertThat(error.isRetryable()).isFalse();
+      assertThat(ModelProviderException.sanitizeProviderMessage(" ", 10)).isNull();
+      assertThat(ModelProviderException.sanitizeProviderMessage(null, 10)).isNull();
+      assertThat(ModelProviderException.sanitizeProviderMessage("word ".repeat(100), 20)).hasSize(20);
+      assertThat(ModelProviderException.sanitizeProviderMessage("a".repeat(50), 100)).isEqualTo("[redacted]");
+   }
+}

qbit-assistant-provider-api/src/test/java/com/kingsrook/qbits/assistant/spi/ProviderComponentsTest.java

@@ -0,0 +1,79 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.spi;
+
+
+import java.time.Duration;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+
+/*******************************************************************************
+ ** Standalone contracts moved from the runtime's component tests.
+ *******************************************************************************/
+class ProviderComponentsTest
+{
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Test
+   void testPricing()
+   {
+      ModelPricing sonnet = ModelPricing.defaults().get("claude-sonnet-5-5");
+      ModelUsage   usage  = new ModelUsage().withInputTokens(6000L).withOutputTokens(800L).withCacheReadTokens(12_000L).withCacheWriteTokens(1000L).withCacheWrite1hTokens(400L);
+      //////////////////////////////////////////////////////////////////////////////////
+      // 6000*2 + 800*10 + 12000*0.2 + 600*2.5 + 400*4 = 12000+8000+2400+1500+1600   //
+      //////////////////////////////////////////////////////////////////////////////////
+      assertThat(sonnet.costMicros(usage)).isEqualTo(25_500);
+      assertThat(sonnet.costMicros(null)).isZero();
+      assertThat(new ModelPricing().costMicros(usage)).isZero();
+      assertThat(ModelPricing.defaults().get("claude-opus-5-5").getCacheReadUsdPerMTok()).isEqualTo(0.2);
+      assertThat(usage.billableTokens()).isEqualTo(7800);
+      assertThat(new ModelUsage().add(usage).add(null).getCacheReadTokens()).isEqualTo(12_000);
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Test
+   void testStreamHandle() throws Exception
+   {
+      CompletableStreamHandle handle = new CompletableStreamHandle();
+      handle.complete(new ModelResponse().withStopReason("end_turn"));
+      assertThat(handle.await(Duration.ofSeconds(1)).getStopReason()).isEqualTo("end_turn");
+
+      CompletableStreamHandle failing = new CompletableStreamHandle();
+      failing.fail(new ModelProviderException(ModelProviderException.Kind.RATE_LIMITED, 429, "slow down"));
+      assertThatThrownBy(() -> failing.await(Duration.ofSeconds(1))).isInstanceOfSatisfying(ModelProviderException.class, e ->
+      {
+         assertThat(e.isRetryable()).isTrue();
+         assertThat(e.getHttpStatus()).isEqualTo(429);
+      });
+
+      CompletableStreamHandle cancelled = new CompletableStreamHandle();
+      cancelled.setOnCancel(() ->
+      {
+         throw (new IllegalStateException("closing"));
+      });
+      cancelled.cancel();
+      cancelled.cancel();
+      assertThat(cancelled.await(Duration.ofSeconds(1)).getStopReason()).isEqualTo(ModelResponse.STOP_CANCELLED);
+      assertThat(new ModelProviderException(ModelProviderException.Kind.INVALID_REQUEST, 400, "x").isRetryable()).isFalse();
+   }
+}

qbit-assistant-provider-api/src/test/java/com/kingsrook/qbits/assistant/spi/ProviderDefaultsTest.java

@@ -0,0 +1,164 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.spi;
+
+
+import java.util.List;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+
+/*******************************************************************************
+ ** A minimal external provider compiles and uses SPI defaults without the runtime.
+ *******************************************************************************/
+class ProviderDefaultsTest
+{
+   /*******************************************************************************
+    ** Legacy two-argument factories and static model lists remain supported.
+    *******************************************************************************/
+   @Test
+   void minimalProviderDefaults() throws Exception
+   {
+      ExampleProvider provider = new ExampleProvider();
+      ProviderSettings settings = new ProviderSettings().withApiKey("test-key").withBaseUrl("https://example.invalid");
+      assertThat(provider.create(settings)).isSameAs(provider);
+      assertThat(provider.settings.getApiKey()).isEqualTo("test-key");
+      assertThat(provider.settings.getBaseUrl()).isEqualTo("https://example.invalid");
+      assertThat(provider.getKinds()).containsExactly("EXAMPLE_PROVIDER");
+      assertThat(provider.getDefaultBaseUrl("EXAMPLE_PROVIDER")).isNull();
+      assertThat(provider.getDefaultApiKeyEnvName("EXAMPLE_PROVIDER")).isEqualTo("EXAMPLE_KEY");
+      assertThat(provider.getDefaultLocation("EXAMPLE_PROVIDER")).isEqualTo("CLOUD");
+      assertThat(provider.requiresBaseUrl("EXAMPLE_PROVIDER")).isTrue();
+      assertThat(provider.validate(settings)).isEmpty();
+      assertThat(provider.discoverModels(settings)).containsExactly(new DiscoveredModel("example", "example", null, null));
+      assertThat(provider.checkHealth(settings).healthy()).isNull();
+      assertThat(provider.checkHealth(settings).message()).isEqualTo("Health check not supported");
+      assertThat(new HealthResult(false, 20L, "bad sk-abcdefghijk").message()).isEqualTo("bad [redacted]");
+      assertThat(provider.countTokens(new ModelRequest())).isNull();
+      assertThatThrownBy(() -> provider.embed(new EmbeddingRequest("example", List.of("text"))))
+         .isInstanceOfSatisfying(ModelProviderException.class, error -> assertThat(error.getKind()).isEqualTo(ModelProviderException.Kind.INVALID_REQUEST));
+      StringBuilder deltas = new StringBuilder();
+      ModelEventListener listener = deltas::append;
+      listener.onToolUseStart("call", "lookup");
+      assertThat(deltas).isEmpty();
+      listener.onTextDelta("visible answer");
+      assertThat(deltas).hasToString("visible answer");
+   }
+
+
+
+   /*******************************************************************************
+    ** Only the original required SPI methods are implemented.
+    *******************************************************************************/
+   private static class ExampleProvider implements AssistantProviderType, AssistantModelProvider
+   {
+      private ProviderSettings settings;
+
+
+
+      /*******************************************************************************
+       ** Minimal provider contract.
+       *******************************************************************************/
+      @Override
+      public String getType()
+      {
+         return ("example-provider");
+      }
+
+
+      /*******************************************************************************
+       ** Minimal provider contract.
+       *******************************************************************************/
+      @Override
+      public String getLabel()
+      {
+         return ("Example");
+      }
+
+
+      /*******************************************************************************
+       ** Minimal provider contract.
+       *******************************************************************************/
+      @Override
+      public List<String> getModels()
+      {
+         return (List.of("example"));
+      }
+
+
+      /*******************************************************************************
+       ** Minimal provider contract.
+       *******************************************************************************/
+      @Override
+      public String getDefaultApiKeyEnvName()
+      {
+         return ("EXAMPLE_KEY");
+      }
+
+
+      /*******************************************************************************
+       ** Minimal provider contract.
+       *******************************************************************************/
+      @Override
+      public String getDefaultBaseUrl()
+      {
+         return (null);
+      }
+
+
+      /*******************************************************************************
+       ** Minimal provider contract.
+       *******************************************************************************/
+      @Override
+      public AssistantModelProvider create(String apiKey, String baseUrl)
+      {
+         settings = new ProviderSettings().withApiKey(apiKey).withBaseUrl(baseUrl);
+         return (this);
+      }
+
+
+      /*******************************************************************************
+       ** Minimal provider contract.
+       *******************************************************************************/
+      @Override
+      public String getName()
+      {
+         return ("example");
+      }
+
+
+      /*******************************************************************************
+       ** Minimal provider contract.
+       *******************************************************************************/
+      @Override
+      public ModelCapabilities getCapabilities(String modelId)
+      {
+         return (new ModelCapabilities());
+      }
+
+
+      /*******************************************************************************
+       ** Minimal provider contract.
+       *******************************************************************************/
+      @Override
+      public StreamHandle stream(ModelRequest request, ModelEventListener listener)
+      {
+         throw (new UnsupportedOperationException());
+      }
+   }
+}

qbit-assistant-provider-api/src/test/java/com/kingsrook/qbits/assistant/spi/TrustedCaBundleTest.java

@@ -0,0 +1,67 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.spi;
+
+
+import java.security.KeyStore;
+import java.security.cert.X509Certificate;
+import java.util.Arrays;
+import java.util.Base64;
+import javax.net.ssl.TrustManagerFactory;
+import javax.net.ssl.X509TrustManager;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** Offline proof that adding a bundle does not replace the JVM's trust roots.
+ *******************************************************************************/
+class TrustedCaBundleTest
+{
+   /*******************************************************************************
+    ** Use existing public JVM roots in memory; no network or fixture signing.
+    *******************************************************************************/
+   @Test
+   void keepsDefaultRoots() throws Exception
+   {
+      X509TrustManager defaults = manager(null);
+      X509Certificate[] roots = defaults.getAcceptedIssuers();
+      assertThat(roots.length).isGreaterThan(1);
+      KeyStore extra = KeyStore.getInstance(KeyStore.getDefaultType());
+      extra.load(null, null);
+      extra.setCertificateEntry("one-root", roots[0]);
+      TrustedCaBundle combined = new TrustedCaBundle(defaults, manager(extra));
+      assertThat(combined.getAcceptedIssuers()).contains(roots);
+      assertThat(combined.getAcceptedIssuers()).hasSize(roots.length + 1);
+      combined.checkServerTrusted(new X509Certificate[] { roots[1] }, roots[1].getPublicKey().getAlgorithm());
+      combined.checkClientTrusted(new X509Certificate[] { roots[1] }, roots[1].getPublicKey().getAlgorithm());
+      String pem = "-----BEGIN CERTIFICATE-----\n" + Base64.getMimeEncoder(64, new byte[] { '\n' }).encodeToString(roots[0].getEncoded()) + "\n-----END CERTIFICATE-----\n";
+      assertThat(TrustedCaBundle.parse(pem).getProtocol()).isEqualTo("TLS");
+   }
+
+
+
+   /*******************************************************************************
+    ** Resolve a real PKIX manager from either the JVM or the small extra store.
+    *******************************************************************************/
+   private X509TrustManager manager(KeyStore store) throws Exception
+   {
+      TrustManagerFactory factory = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
+      factory.init(store);
+      return (Arrays.stream(factory.getTrustManagers()).filter(X509TrustManager.class::isInstance).map(X509TrustManager.class::cast).findFirst().orElseThrow());
+   }
+}

qbit-assistant-provider-bedrock/pom.xml

@@ -0,0 +1,142 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Copyright 2026 Kingsrook, LLC
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+   <modelVersion>4.0.0</modelVersion>
+
+   <parent>
+      <groupId>com.kingsrook.qbits</groupId>
+      <artifactId>qbit-assistant-parent</artifactId>
+      <version>${revision}</version>
+   </parent>
+
+   <artifactId>qbit-assistant-provider-bedrock</artifactId>
+   <packaging>jar</packaging>
+
+   <name>QBit Assistant - Bedrock provider</name>
+   <description>Bedrock provider using the Anthropic cloud backend</description>
+   <url>https://github.com/QRun-IO/qbit-assistant</url>
+
+   <dependencies>
+      <dependency>
+         <groupId>com.anthropic</groupId>
+         <artifactId>anthropic-java-bedrock</artifactId>
+      </dependency>
+      <dependency>
+         <groupId>com.kingsrook.qbits</groupId>
+         <artifactId>qbit-assistant-provider-anthropic</artifactId>
+      </dependency>
+
+      <dependency>
+         <groupId>com.kingsrook.qbits</groupId>
+         <artifactId>qbit-assistant-provider-api</artifactId>
+      </dependency>
+      <dependency>
+         <groupId>com.kingsrook.qbits</groupId>
+         <artifactId>qbit-assistant</artifactId>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>com.kingsrook.qqq</groupId>
+         <artifactId>qqq-backend-core</artifactId>
+      </dependency>
+      <dependency>
+         <groupId>com.fasterxml.jackson.core</groupId>
+         <artifactId>jackson-databind</artifactId>
+      </dependency>
+
+      <dependency>
+         <groupId>com.kingsrook.qbits</groupId>
+         <artifactId>qbit-assistant</artifactId>
+         <type>test-jar</type>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>com.kingsrook.qqq</groupId>
+         <artifactId>qqq-middleware-javalin</artifactId>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>org.junit.jupiter</groupId>
+         <artifactId>junit-jupiter</artifactId>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>org.assertj</groupId>
+         <artifactId>assertj-core</artifactId>
+         <scope>test</scope>
+      </dependency>
+   </dependencies>
+
+   <build>
+      <plugins>
+         <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-surefire-plugin</artifactId>
+            <configuration>
+               <!-- live evals call the real API: opt-in only -->
+               <excludedGroups>${test.excludedGroups}</excludedGroups>
+               <redirectTestOutputToFile>true</redirectTestOutputToFile>
+            </configuration>
+         </plugin>
+         <plugin>
+            <groupId>org.jacoco</groupId>
+            <artifactId>jacoco-maven-plugin</artifactId>
+            <executions>
+               <execution>
+                  <id>prepare-agent</id>
+                  <goals>
+                     <goal>prepare-agent</goal>
+                  </goals>
+               </execution>
+               <execution>
+                  <id>report</id>
+                  <phase>verify</phase>
+                  <goals>
+                     <goal>report</goal>
+                  </goals>
+               </execution>
+               <execution>
+                  <id>check</id>
+                  <goals>
+                     <goal>check</goal>
+                  </goals>
+                  <configuration>
+                     <rules>
+                        <rule>
+                           <element>BUNDLE</element>
+                           <limits>
+                              <limit>
+                                 <counter>INSTRUCTION</counter>
+                                 <value>COVEREDRATIO</value>
+                                 <minimum>0.70</minimum>
+                              </limit>
+                              <limit>
+                                 <counter>CLASS</counter>
+                                 <value>COVEREDRATIO</value>
+                                 <minimum>0.90</minimum>
+                              </limit>
+                           </limits>
+                        </rule>
+                     </rules>
+                  </configuration>
+               </execution>
+            </executions>
+         </plugin>
+      </plugins>
+   </build>
+</project>

qbit-assistant-provider-bedrock/src/main/java/com/kingsrook/qbits/assistant/provider/bedrock/BedrockEndpointBackend.java

@@ -0,0 +1,73 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.provider.bedrock;
+
+
+import com.anthropic.backends.Backend;
+import com.anthropic.core.http.HttpRequest;
+import com.anthropic.core.http.HttpResponse;
+
+
+/*******************************************************************************
+ ** SDK 2.71 has no Bedrock endpoint setter. Override only the endpoint, keeping
+ ** the SDK's request conversion, SigV4 signing of that endpoint, and decoding.
+ ** The caller must validate the URL against the host's allowlist first.
+ *******************************************************************************/
+record BedrockEndpointBackend(Backend delegate, String baseUrl) implements Backend
+{
+   /*******************************************************************************
+    ** Preserve the Bedrock model-path and body conversion.
+    *******************************************************************************/
+   @Override
+   public HttpRequest prepareRequest(HttpRequest request)
+   {
+      return (delegate.prepareRequest(request));
+   }
+
+
+
+   /*******************************************************************************
+    ** Sign the actual request URL, including the overridden host.
+    *******************************************************************************/
+   @Override
+   public HttpRequest authorizeRequest(HttpRequest request)
+   {
+      return (delegate.authorizeRequest(request));
+   }
+
+
+
+   /*******************************************************************************
+    ** Decode the AWS event stream through the SDK.
+    *******************************************************************************/
+   @Override
+   public HttpResponse prepareResponse(HttpResponse response)
+   {
+      return (delegate.prepareResponse(response));
+   }
+
+
+
+   /*******************************************************************************
+    ** Release the SDK's stream conversion resources.
+    *******************************************************************************/
+   @Override
+   public void close()
+   {
+      delegate.close();
+   }
+}

qbit-assistant-provider-bedrock/src/main/java/com/kingsrook/qbits/assistant/provider/bedrock/BedrockProviderType.java

@@ -0,0 +1,184 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.provider.bedrock;
+
+
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.List;
+import com.anthropic.backends.Backend;
+import com.anthropic.bedrock.backends.BedrockBackend;
+import com.anthropic.client.okhttp.AnthropicOkHttpClient;
+import com.anthropic.core.Timeout;
+import com.kingsrook.qbits.assistant.provider.anthropic.AnthropicModelProvider;
+import com.kingsrook.qbits.assistant.spi.AssistantModelProvider;
+import com.kingsrook.qbits.assistant.spi.AssistantProviderType;
+import com.kingsrook.qbits.assistant.spi.DiscoveredModel;
+import com.kingsrook.qbits.assistant.spi.ProviderSettings;
+import software.amazon.awssdk.auth.credentials.AwsCredentialsProvider;
+import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
+import software.amazon.awssdk.regions.Region;
+
+
+/*******************************************************************************
+ ** AWS Bedrock (Claude), using server credentials and region-derived endpoints.
+ ** Environment, profile and container (ECS/EKS Pod Identity) credentials use
+ ** the transitive SDK dependencies. Hosts using IRSA / web identity must add
+ ** software.amazon.awssdk:sts to their runtime classpath; the default credential
+ ** chain discovers it when present. This adapter does not depend on STS.
+ *******************************************************************************/
+public class BedrockProviderType implements AssistantProviderType
+{
+
+
+
+   /*******************************************************************************
+    ** Provider registry contract.
+    *******************************************************************************/
+   @Override
+   public String getType()
+   {
+      return ("bedrock");
+   }
+
+
+
+   /*******************************************************************************
+    ** Provider registry contract.
+    *******************************************************************************/
+   @Override
+   public String getLabel()
+   {
+      return ("AWS Bedrock (Claude)");
+   }
+
+
+
+   /*******************************************************************************
+    ** Provider registry contract.
+    *******************************************************************************/
+   @Override
+   public List<String> getModels()
+   {
+      return (List.of("us.anthropic.claude-sonnet-4-5-20250929-v1:0", "us.anthropic.claude-haiku-4-5-20251001-v1:0"));
+   }
+
+
+
+   /*******************************************************************************
+    ** Provider registry contract.
+    *******************************************************************************/
+   @Override
+   public String getDefaultApiKeyEnvName()
+   {
+      return (null);
+   }
+
+
+
+   /*******************************************************************************
+    ** Provider registry contract.
+    *******************************************************************************/
+   @Override
+   public String getDefaultBaseUrl()
+   {
+      return (null);
+   }
+
+
+
+   /*******************************************************************************
+    ** Provider registry contract.
+    *******************************************************************************/
+   @Override
+   public boolean requiresBaseUrl(String kind)
+   {
+      return (false);
+   }
+
+
+
+   /*******************************************************************************
+    ** Validate cloud settings without loading credentials.
+    *******************************************************************************/
+   @Override
+   public List<String> validate(ProviderSettings settings)
+   {
+      List<String> errors = new ArrayList<>();
+      if(settings.getRegion() == null || settings.getRegion().isBlank())
+      {
+         errors.add("Region is required for BEDROCK.");
+      }
+      if(settings.getApiKeyEnvName() != null && !settings.getApiKeyEnvName().isBlank())
+      {
+         errors.add("Leave API key variable empty: AWS Bedrock (Claude) uses the AWS default credential chain (environment, profile or server role).");
+      }
+      return (errors);
+   }
+
+
+
+   /*******************************************************************************
+    ** Cloud providers require resolved region/project settings.
+    *******************************************************************************/
+   @Override
+   public AssistantModelProvider create(String apiKey, String baseUrl)
+   {
+      throw (new IllegalArgumentException("Use ProviderSettings with the required cloud region."));
+   }
+
+
+
+   /*******************************************************************************
+    ** Static defaults: ListFoundationModels requires the Bedrock control-plane SDK,
+    ** which this adapter deliberately does not add.
+    *******************************************************************************/
+   @Override
+   public List<DiscoveredModel> discoverModels(ProviderSettings settings)
+   {
+      return (getModels().stream().map(id -> new DiscoveredModel(id, id, null, null)).toList());
+   }
+
+
+
+   /*******************************************************************************
+    ** Create the provider with server credentials.
+    *******************************************************************************/
+   @Override
+   public AssistantModelProvider create(ProviderSettings settings)
+   {
+      return (create(settings, DefaultCredentialsProvider.builder().build()));
+   }
+
+
+
+   /*******************************************************************************
+    ** Credential injection for contract tests; no credential values are stored.
+    *******************************************************************************/
+   AnthropicModelProvider create(ProviderSettings settings, AwsCredentialsProvider credentials)
+   {
+      Backend backend = BedrockBackend.builder().region(Region.of(settings.getRegion())).awsCredentialsProvider(credentials).build();
+      if(settings.getBaseUrl() != null)
+      {
+         backend = new BedrockEndpointBackend(backend, settings.getBaseUrl());
+      }
+      var client = AnthropicOkHttpClient.builder().backend(backend)
+         .timeout(Timeout.builder().connect(Duration.ofSeconds(settings.getConnectTimeoutSeconds()))
+            .request(Duration.ofSeconds(settings.getRequestTimeoutSeconds())).build());
+      return (AnthropicModelProvider.builder().client(client.build()).build());
+   }
+}

qbit-assistant-provider-bedrock/src/test/java/com/kingsrook/qbits/assistant/provider/bedrock/BedrockContractTest.java

@@ -0,0 +1,245 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.provider.bedrock;
+
+
+import java.nio.charset.StandardCharsets;
+import java.time.Clock;
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import com.kingsrook.qbits.assistant.AssistantQBitConfig;
+import com.kingsrook.qbits.assistant.engine.ProviderService;
+import com.kingsrook.qbits.assistant.model.AssistantProvider;
+import com.kingsrook.qbits.assistant.provider.anthropic.AnthropicModelProvider;
+import com.kingsrook.qbits.assistant.spi.ModelEventListener;
+import com.kingsrook.qbits.assistant.spi.ModelMessage;
+import com.kingsrook.qbits.assistant.spi.ModelPart;
+import com.kingsrook.qbits.assistant.spi.ModelProviderException;
+import com.kingsrook.qbits.assistant.spi.ModelRequest;
+import com.kingsrook.qbits.assistant.spi.ModelToolDefinition;
+import com.kingsrook.qbits.assistant.spi.ProviderSettings;
+import com.kingsrook.qbits.assistant.testing.CloudProviderTestServer;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
+import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
+import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
+import static com.kingsrook.qbits.assistant.testing.CloudProviderTestServer.JSON;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+
+/*******************************************************************************
+ ** Real Anthropic Bedrock SDK against signed loopback requests and binary streams.
+ *******************************************************************************/
+class BedrockContractTest
+{
+   static final String MODEL = "us.anthropic.claude-sonnet-4-5-20250929-v1:0";
+
+
+
+   /*******************************************************************************
+    ** Explicit fake credentials avoid all default-chain network lookup in tests.
+    *******************************************************************************/
+   static AnthropicModelProvider provider(CloudProviderTestServer server)
+   {
+      return (new BedrockProviderType().create(new ProviderSettings().withRegion("us-east-1").withBaseUrl(server.url())
+         .withConnectTimeoutSeconds(2).withRequestTimeoutSeconds(5),
+         StaticCredentialsProvider.create(AwsBasicCredentials.create("AKIDEXAMPLE", "synthetic-secret"))));
+   }
+
+
+
+   /*******************************************************************************
+    ** Engine-shaped request with an opted-in strict tool.
+    *******************************************************************************/
+   static ModelRequest request()
+   {
+      return (new ModelRequest().withModel(MODEL).withMaxTokens(1024).withMessages(List.of(ModelMessage.user("Count posts")))
+         .withTools(List.of(new ModelToolDefinition().withName("count_records").withDescription("Count records").withStrict(true)
+            .withInputSchema(Map.of("type", "object", "properties", Map.of("table", Map.of("type", "string")), "required", List.of("table"), "additionalProperties", false)))));
+   }
+
+
+
+   /*******************************************************************************
+    ** Binary chunk framing, SigV4, request rewriting, text, tools and usage.
+    *******************************************************************************/
+   @Test
+   void streamingContract() throws Exception
+   {
+      try(CloudProviderTestServer server = new CloudProviderTestServer())
+      {
+         server.enqueue(200, "application/vnd.amazon.eventstream", BedrockEventStream.encode(CloudProviderTestServer.anthropicEvents(MODEL, "Checking.", Map.of("table", "blog_post"))));
+         AnthropicModelProvider provider = provider(server);
+         try
+         {
+            StringBuilder text = new StringBuilder();
+            List<String> tools = new ArrayList<>();
+            var response = provider.stream(request(), new ModelEventListener()
+            {
+               /*******************************************************************************
+                ** Capture only visible text.
+                *******************************************************************************/
+               @Override
+               public void onTextDelta(String delta)
+               {
+                  text.append(delta);
+               }
+
+               /*******************************************************************************
+                ** Confirm tool-start callbacks pass through the reused adapter.
+                *******************************************************************************/
+               @Override
+               public void onToolUseStart(String id, String name)
+               {
+                  tools.add(id + ":" + name);
+               }
+            }).await(Duration.ofSeconds(10));
+            assertThat(text.toString()).isEqualTo("Checking.");
+            assertThat(response.getText()).isEqualTo("Checking.");
+            assertThat(tools).containsExactly("count:count_records");
+            assertThat(response.getToolUses()).singleElement().satisfies(tool ->
+            {
+               assertThat(tool.getToolUseId()).isEqualTo("count");
+               assertThat(tool.getInput()).containsEntry("table", "blog_post");
+            });
+            assertThat(response.getStopReason()).isEqualTo("tool_use");
+            assertThat(response.getUsage().getInputTokens()).isEqualTo(12);
+            assertThat(response.getUsage().getOutputTokens()).isEqualTo(7);
+            var sent = server.requests.getFirst();
+            assertThat(sent.path()).isEqualTo("/model/" + MODEL + "/invoke-with-response-stream");
+            assertThat(sent.authorization()).startsWith("AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/").contains("/us-east-1/bedrock/aws4_request", "Signature=");
+            var body = JSON.readTree(sent.body());
+            assertThat(body.path("anthropic_version").asText()).isEqualTo("bedrock-2023-05-31");
+            assertThat(body.has("model")).isFalse();
+            assertThat(body.has("stream")).isFalse();
+            assertThat(body.path("max_tokens").asInt()).isEqualTo(1024);
+            assertThat(body.path("messages").get(0).path("role").asText()).isEqualTo("user");
+            assertThat(body.path("tools").get(0).path("strict").asBoolean()).isTrue();
+         }
+         finally
+         {
+            provider.close();
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** An image part reaches Bedrock as an Anthropic base64 image block.
+    *******************************************************************************/
+   @Test
+   void imagePartContract() throws Exception
+   {
+      try(CloudProviderTestServer server = new CloudProviderTestServer())
+      {
+         server.enqueue(200, "application/vnd.amazon.eventstream", BedrockEventStream.encode(CloudProviderTestServer.anthropicEvents(MODEL, "A chart.", null)));
+         AnthropicModelProvider provider = provider(server);
+         try
+         {
+            ModelRequest request = new ModelRequest().withModel(MODEL).withMaxTokens(256).withMessages(List.of(new ModelMessage().withRole(ModelMessage.Role.USER)
+               .withPart(ModelPart.image("image/jpeg", "/9j/4AAQ")).withPart(ModelPart.text("Describe it"))));
+            assertThat(provider.getCapabilities(MODEL).getVision()).isTrue();
+            provider.stream(request, delta -> {}).await(Duration.ofSeconds(10));
+            var block = JSON.readTree(server.requests.getFirst().body()).path("messages").get(0).path("content").get(0);
+            assertThat(block.path("type").asText()).isEqualTo("image");
+            assertThat(block.path("source").path("type").asText()).isEqualTo("base64");
+            assertThat(block.path("source").path("media_type").asText()).isEqualTo("image/jpeg");
+            assertThat(block.path("source").path("data").asText()).isEqualTo("/9j/4AAQ");
+         }
+         finally
+         {
+            provider.close();
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The cloud backend keeps the Anthropic adapter's HTTP error mapping.
+    *******************************************************************************/
+   @ParameterizedTest
+   @CsvSource({ "403,AUTHENTICATION", "429,RATE_LIMITED", "500,SERVER" })
+   void errors(Integer status, ModelProviderException.Kind kind) throws Exception
+   {
+      try(CloudProviderTestServer server = new CloudProviderTestServer())
+      {
+         for(int attempt = 0; attempt < 3; attempt++)
+         {
+            server.enqueue(status, "application/json", "{\"message\":\"Synthetic failure\"}".getBytes(StandardCharsets.UTF_8));
+         }
+         AnthropicModelProvider provider = provider(server);
+         try
+         {
+            assertThatThrownBy(() -> provider.stream(request(), delta -> {}).await(Duration.ofSeconds(20)))
+               .isInstanceOfSatisfying(ModelProviderException.class, error ->
+               {
+                  assertThat(error.getKind()).isEqualTo(kind);
+                  assertThat(error.getHttpStatus()).isEqualTo(status);
+               });
+         }
+         finally
+         {
+            provider.close();
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Registry defaults and validation run without resolving AWS credentials.
+    *******************************************************************************/
+   @Test
+   void settingsValidationAndDefaults() throws Exception
+   {
+      var type = new BedrockProviderType();
+      var config = new AssistantQBitConfig().withProviderType(type).withAllowedBaseUrls(Set.of("http://127.0.0.1:1234"));
+      var service = new ProviderService(config, null, Clock.systemUTC());
+      var row = new AssistantProvider().withProviderType("bedrock");
+      assertThat(service.validate(row)).anyMatch(error -> error.contains("Region is required"));
+      row.withRegion(" ");
+      assertThat(service.validate(row)).anyMatch(error -> error.contains("Region is required"));
+      row.withRegion("us-east-1");
+      assertThat(service.validate(row)).isEmpty();
+      row.withApiKeyEnvName("AWS_API_KEY");
+      assertThat(service.validate(row)).anyMatch(error -> error.contains("default credential chain"));
+      row.withApiKeyEnvName(" ").withBaseUrl("https://unlisted.example");
+      assertThat(service.validate(row)).anyMatch(error -> error.contains("not allowed"));
+      row.withBaseUrl("http://127.0.0.1:1234");
+      assertThat(service.validate(row)).isEmpty();
+      assertThat(type.getType()).isEqualTo("bedrock");
+      assertThat(type.getKinds()).containsExactly("BEDROCK");
+      assertThat(type.getLabel()).isEqualTo("AWS Bedrock (Claude)");
+      assertThat(type.getDefaultLocation("BEDROCK")).isEqualTo("CLOUD");
+      assertThat(type.getDefaultApiKeyEnvName()).isNull();
+      assertThat(type.getDefaultBaseUrl()).isNull();
+      assertThat(type.discoverModels(new ProviderSettings())).extracting(model -> model.modelId()).containsExactlyElementsOf(type.getModels());
+      assertThat(type.checkHealth(new ProviderSettings()).healthy()).isNull();
+      assertThatThrownBy(() -> type.create("key", null)).isInstanceOf(IllegalArgumentException.class);
+      // Client creation is lazy: no credentials are resolved and no request sent.
+      var defaultChain = (AnthropicModelProvider) type.create(new ProviderSettings().withRegion("us-east-1"));
+      defaultChain.close();
+   }
+}
+

qbit-assistant-provider-bedrock/src/test/java/com/kingsrook/qbits/assistant/provider/bedrock/BedrockEventStream.java

@@ -0,0 +1,90 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.provider.bedrock;
+
+
+import java.io.ByteArrayOutputStream;
+import java.io.DataOutputStream;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.util.Base64;
+import java.util.List;
+import java.util.Map;
+import java.util.zip.CRC32;
+import com.kingsrook.qbits.assistant.testing.CloudProviderTestServer;
+
+
+/*******************************************************************************
+ ** Test-side AWS event-stream encoder: prelude, typed headers and both CRC32s.
+ *******************************************************************************/
+final class BedrockEventStream
+{
+   /*******************************************************************************
+    ** Each chunk carries base64 Anthropic event JSON, not an SSE envelope.
+    *******************************************************************************/
+   static byte[] encode(List<String> events) throws IOException
+   {
+      ByteArrayOutputStream stream = new ByteArrayOutputStream();
+      for(String event : events)
+      {
+         byte[] payload = CloudProviderTestServer.JSON.writeValueAsBytes(Map.of("bytes", Base64.getEncoder().encodeToString(event.getBytes(StandardCharsets.UTF_8))));
+         ByteArrayOutputStream headers = new ByteArrayOutputStream();
+         DataOutputStream headerData = new DataOutputStream(headers);
+         header(headerData, ":message-type", "event");
+         header(headerData, ":event-type", "chunk");
+         header(headerData, ":content-type", "application/json");
+         ByteArrayOutputStream frame = new ByteArrayOutputStream();
+         DataOutputStream data = new DataOutputStream(frame);
+         data.writeInt(16 + headers.size() + payload.length);
+         data.writeInt(headers.size());
+         data.writeInt(crc(frame.toByteArray()));
+         data.write(headers.toByteArray());
+         data.write(payload);
+         data.writeInt(crc(frame.toByteArray()));
+         stream.write(frame.toByteArray());
+      }
+      return (stream.toByteArray());
+   }
+
+
+
+   /*******************************************************************************
+    ** AWS header type 7 is a UTF-8 string with a two-byte length.
+    *******************************************************************************/
+   private static void header(DataOutputStream data, String name, String value) throws IOException
+   {
+      byte[] nameBytes = name.getBytes(StandardCharsets.UTF_8);
+      byte[] valueBytes = value.getBytes(StandardCharsets.UTF_8);
+      data.writeByte(nameBytes.length);
+      data.write(nameBytes);
+      data.writeByte(7);
+      data.writeShort(valueBytes.length);
+      data.write(valueBytes);
+   }
+
+
+
+   /*******************************************************************************
+    ** Network-order CRC32 for the prelude and complete message respectively.
+    *******************************************************************************/
+   private static int crc(byte[] bytes)
+   {
+      CRC32 crc = new CRC32();
+      crc.update(bytes);
+      return ((int) crc.getValue());
+   }
+}

qbit-assistant-provider-bedrock/src/test/java/com/kingsrook/qbits/assistant/provider/bedrock/BedrockGoldenTurnTest.java

@@ -0,0 +1,87 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.provider.bedrock;
+
+
+import com.kingsrook.qbits.assistant.AssistantModelRouting;
+import com.kingsrook.qbits.assistant.AssistantQBitConfig;
+import com.kingsrook.qbits.assistant.testing.AssistantTestFixture;
+import com.kingsrook.qbits.assistant.testing.CloudProviderTestServer;
+import com.kingsrook.qbits.assistant.testing.GoldenTasks;
+import com.kingsrook.qbits.assistant.testing.TurnRunner;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import org.junit.jupiter.api.Tag;
+import org.junit.jupiter.api.Test;
+import static com.kingsrook.qbits.assistant.testing.CloudProviderTestServer.JSON;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** Golden task through the cloud adapter, turn engine and permissioned UI tools.
+ *******************************************************************************/
+@Tag("golden")
+class BedrockGoldenTurnTest
+{
+   /*******************************************************************************
+    ** A real count_records round trip returns the tool result to the model.
+    *******************************************************************************/
+   @Test
+   void goldenToolRoundTrip() throws Exception
+   {
+      try(CloudProviderTestServer server = new CloudProviderTestServer())
+      {
+         String answer = "There are " + AssistantTestFixture.PUBLISHED_POSTS + " published posts. /app/blog_post";
+         String model = BedrockContractTest.MODEL;
+         server.enqueue(200, "application/vnd.amazon.eventstream", BedrockEventStream.encode(CloudProviderTestServer.anthropicEvents(model, "", CloudProviderTestServer.countInput())));
+         server.enqueue(200, "application/vnd.amazon.eventstream", BedrockEventStream.encode(CloudProviderTestServer.anthropicEvents(model, answer, null)));
+         var provider = BedrockContractTest.provider(server);
+         var config = new AssistantQBitConfig().withProviderName(provider.getName()).withModelProvider(provider)
+            .withModels(new AssistantModelRouting().withMainModel(model));
+         try
+         {
+            var instance = AssistantTestFixture.build(config);
+            var task = GoldenTasks.all().stream().filter(t -> t.id().equals("count-published-posts")).findFirst().orElseThrow();
+            var outcome = new TurnRunner(instance, config).run(task.userId(), task.prompt());
+            assertThat(outcome.errorCode()).isNull();
+            task.check().accept(outcome);
+            assertThat(outcome.text()).endsWith(answer);
+            assertThat(outcome.end()).isNotEmpty();
+            assertThat(server.requests).hasSize(2);
+            var messages = JSON.readTree(server.requests.get(1).body()).path("messages");
+            var assistant = messages.get(messages.size() - 2);
+            var result = messages.get(messages.size() - 1);
+            assertThat(assistant.path("role").asText()).isEqualTo("assistant");
+            assertThat(assistant.path("content").toString()).contains("count_records", "count");
+            assertThat(result.path("role").asText()).isEqualTo("user");
+            var toolResult = result.path("content").get(0);
+            assertThat(toolResult.path("type").asText()).isEqualTo("tool_result");
+            assertThat(toolResult.path("tool_use_id").asText()).isEqualTo("count");
+            assertThat(toolResult.path("is_error").asBoolean()).isFalse();
+            assertThat(toolResult.path("content").toString()).contains("count");
+         }
+         finally
+         {
+            if(config.getRuntime() != null)
+            {
+               config.getRuntime().close();
+            }
+            provider.close();
+            QContext.clear();
+         }
+      }
+   }
+}

qbit-assistant-provider-openai/pom.xml

@@ -0,0 +1,133 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Copyright 2026 Kingsrook, LLC
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+   <modelVersion>4.0.0</modelVersion>
+
+   <parent>
+      <groupId>com.kingsrook.qbits</groupId>
+      <artifactId>qbit-assistant-parent</artifactId>
+      <version>${revision}</version>
+   </parent>
+
+   <artifactId>qbit-assistant-provider-openai</artifactId>
+   <packaging>jar</packaging>
+
+   <name>QBit Assistant - OpenAI-compatible provider</name>
+   <description>OpenAI-compatible Chat Completions provider using the JDK HTTP client</description>
+   <url>https://github.com/QRun-IO/qbit-assistant</url>
+
+   <dependencies>
+      <dependency>
+         <groupId>com.kingsrook.qbits</groupId>
+         <artifactId>qbit-assistant-provider-api</artifactId>
+      </dependency>
+      <dependency>
+         <groupId>com.kingsrook.qbits</groupId>
+         <artifactId>qbit-assistant</artifactId>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>com.kingsrook.qqq</groupId>
+         <artifactId>qqq-backend-core</artifactId>
+      </dependency>
+      <dependency>
+         <groupId>com.fasterxml.jackson.core</groupId>
+         <artifactId>jackson-databind</artifactId>
+      </dependency>
+
+      <dependency>
+         <groupId>com.kingsrook.qbits</groupId>
+         <artifactId>qbit-assistant</artifactId>
+         <type>test-jar</type>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>com.kingsrook.qqq</groupId>
+         <artifactId>qqq-middleware-javalin</artifactId>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>org.junit.jupiter</groupId>
+         <artifactId>junit-jupiter</artifactId>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>org.assertj</groupId>
+         <artifactId>assertj-core</artifactId>
+         <scope>test</scope>
+      </dependency>
+   </dependencies>
+
+   <build>
+      <plugins>
+         <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-surefire-plugin</artifactId>
+            <configuration>
+               <!-- live evals call the real API: opt-in only -->
+               <excludedGroups>${test.excludedGroups}</excludedGroups>
+               <redirectTestOutputToFile>true</redirectTestOutputToFile>
+            </configuration>
+         </plugin>
+         <plugin>
+            <groupId>org.jacoco</groupId>
+            <artifactId>jacoco-maven-plugin</artifactId>
+            <executions>
+               <execution>
+                  <id>prepare-agent</id>
+                  <goals>
+                     <goal>prepare-agent</goal>
+                  </goals>
+               </execution>
+               <execution>
+                  <id>report</id>
+                  <phase>verify</phase>
+                  <goals>
+                     <goal>report</goal>
+                  </goals>
+               </execution>
+               <execution>
+                  <id>check</id>
+                  <goals>
+                     <goal>check</goal>
+                  </goals>
+                  <configuration>
+                     <rules>
+                        <rule>
+                           <element>BUNDLE</element>
+                           <limits>
+                              <limit>
+                                 <counter>INSTRUCTION</counter>
+                                 <value>COVEREDRATIO</value>
+                                 <minimum>0.70</minimum>
+                              </limit>
+                              <limit>
+                                 <counter>CLASS</counter>
+                                 <value>COVEREDRATIO</value>
+                                 <minimum>0.90</minimum>
+                              </limit>
+                           </limits>
+                        </rule>
+                     </rules>
+                  </configuration>
+               </execution>
+            </executions>
+         </plugin>
+      </plugins>
+   </build>
+</project>

qbit-assistant-provider-openai/src/main/java/com/kingsrook/qbits/assistant/provider/openai/OpenAiCompatibleModelProvider.java

@@ -0,0 +1,509 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.provider.openai;
+
+
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.net.http.HttpResponse;
+import java.net.http.HttpTimeoutException;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.TreeMap;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicLong;
+import java.util.concurrent.atomic.AtomicReference;
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.kingsrook.qbits.assistant.spi.AssistantModelProvider;
+import com.kingsrook.qbits.assistant.spi.CompletableStreamHandle;
+import com.kingsrook.qbits.assistant.spi.EmbeddingRequest;
+import com.kingsrook.qbits.assistant.spi.EmbeddingResponse;
+import com.kingsrook.qbits.assistant.spi.ModelCapabilities;
+import com.kingsrook.qbits.assistant.spi.ModelEventListener;
+import com.kingsrook.qbits.assistant.spi.ModelPart;
+import com.kingsrook.qbits.assistant.spi.ModelProviderException;
+import com.kingsrook.qbits.assistant.spi.ModelRequest;
+import com.kingsrook.qbits.assistant.spi.ModelResponse;
+import com.kingsrook.qbits.assistant.spi.ModelUsage;
+import com.kingsrook.qbits.assistant.spi.ProviderSettings;
+import com.kingsrook.qbits.assistant.spi.StreamHandle;
+
+
+/*******************************************************************************
+ ** JDK HTTP Chat Completions adapter. Only visible content is emitted or stored;
+ ** reasoning deltas are ignored. Each call owns its cancellation and read guard.
+ *******************************************************************************/
+public class OpenAiCompatibleModelProvider implements AssistantModelProvider
+{
+   private final OpenAiHttp http;
+   private final boolean local;
+
+
+
+   /*******************************************************************************
+    ** Build a client with resolved settings.
+    *******************************************************************************/
+   public OpenAiCompatibleModelProvider(ProviderSettings settings)
+   {
+      http = new OpenAiHttp(settings);
+      local = "LOCAL".equals(new OpenAiCompatibleProviderType().getDefaultLocation(http.settings.getKind()));
+   }
+
+
+
+   /*******************************************************************************
+    ** Adapter identity.
+    *******************************************************************************/
+   @Override
+   public String getName()
+   {
+      return ("openai-compatible");
+   }
+
+
+
+   /*******************************************************************************
+    ** One bounded batch, with the deadline covering headers and the entire body.
+    ** Restore input order from the response indexes; reject malformed vectors.
+    *******************************************************************************/
+   @Override
+   public EmbeddingResponse embed(EmbeddingRequest request) throws ModelProviderException
+   {
+      ObjectNode body = OpenAiHttp.JSON.createObjectNode();
+      body.put("model", request.model());
+      body.set("input", OpenAiHttp.JSON.valueToTree(request.input()));
+      var pending = http.client.sendAsync(http.request(request.model(), http.settings.getRequestTimeoutSeconds(), "embeddings")
+         .POST(java.net.http.HttpRequest.BodyPublishers.ofString(body.toString())).build(), HttpResponse.BodyHandlers.ofString());
+      try
+      {
+         HttpResponse<String> response = pending.get(http.settings.getRequestTimeoutSeconds(), TimeUnit.SECONDS);
+         if(response.statusCode() != 200)
+         {
+            throw (http.error(response.statusCode(), response.body(), OpenAiHttp.requestId(response), false));
+         }
+         JsonNode json = OpenAiHttp.JSON.readTree(response.body());
+         if(json.has("error"))
+         {
+            throw (http.error(500, response.body(), OpenAiHttp.requestId(response), false));
+         }
+         float[][] vectors = new float[request.input().size()][];
+         Integer dimensions = null;
+         for(JsonNode item : json.path("data"))
+         {
+            Integer index = item.path("index").asInt(-1);
+            JsonNode values = item.path("embedding");
+            if(index < 0 || index >= vectors.length || vectors[index] != null || !values.isArray() || values.isEmpty()
+               || (dimensions != null && dimensions != values.size()))
+            {
+               throw (new IOException("Invalid embedding response."));
+            }
+            dimensions = values.size();
+            float[] vector = new float[dimensions];
+            for(Integer i = 0; i < vector.length; i++)
+            {
+               if(!values.get(i).isNumber())
+               {
+                  throw (new IOException("Invalid embedding coordinate."));
+               }
+               vector[i] = (float) values.get(i).asDouble();
+               if(!Float.isFinite(vector[i]))
+               {
+                  throw (new IOException("Non-finite embedding coordinate."));
+               }
+            }
+            vectors[index] = vector;
+         }
+         if(java.util.Arrays.stream(vectors).anyMatch(java.util.Objects::isNull))
+         {
+            throw (new IOException("Missing embedding."));
+         }
+         return (new EmbeddingResponse(List.of(vectors), new ModelUsage().withInputTokens(json.path("usage").path("prompt_tokens").asLong()), OpenAiHttp.requestId(response)));
+      }
+      catch(java.util.concurrent.TimeoutException e)
+      {
+         throw (new ModelProviderException(ModelProviderException.Kind.TIMEOUT, null, "The provider did not answer in time."));
+      }
+      catch(InterruptedException e)
+      {
+         Thread.currentThread().interrupt();
+         throw (new ModelProviderException(ModelProviderException.Kind.NETWORK, null, "The embedding request was interrupted."));
+      }
+      catch(java.util.concurrent.ExecutionException | IOException e)
+      {
+         throw (OpenAiHttp.transportError(e));
+      }
+      finally
+      {
+         pending.cancel(true);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Conservative defaults; registry rows can override model-specific facts.
+    *******************************************************************************/
+   @Override
+   public ModelCapabilities getCapabilities(String modelId)
+   {
+      return (new ModelCapabilities().withTools(true).withParallelToolCalls(true).withPromptCaching(false).withThinking(false)
+         .withMaxContextTokens(local ? 32_000 : 128_000).withStreaming(true).withVision(false).withReasoningEffort(false));
+   }
+
+
+
+   /*******************************************************************************
+    ** Interrupting the worker aborts the HTTP call, including a blocked body read.
+    *******************************************************************************/
+   @Override
+   public StreamHandle stream(ModelRequest request, ModelEventListener listener)
+   {
+      CompletableStreamHandle handle = new CompletableStreamHandle();
+      AtomicReference<InputStream> input = new AtomicReference<>();
+      Thread worker = Thread.ofVirtual().unstarted(() -> run(request, listener, handle, input));
+      handle.setOnCancel(() ->
+      {
+         worker.interrupt();
+         close(input.get());
+      });
+      worker.start();
+      return (handle);
+   }
+
+
+
+   /*******************************************************************************
+    ** Guard the entire request and idle reads, including after HTTP headers.
+    *******************************************************************************/
+   private void run(ModelRequest request, ModelEventListener listener, CompletableStreamHandle handle, AtomicReference<InputStream> input)
+   {
+      Thread worker = Thread.currentThread();
+      AtomicLong lastRead = new AtomicLong(System.nanoTime());
+      long started = lastRead.get();
+      long timeout = TimeUnit.SECONDS.toNanos(http.settings.getRequestTimeoutSeconds());
+      ScheduledExecutorService guard = Executors.newSingleThreadScheduledExecutor(Thread.ofVirtual().factory());
+      Accumulator result = new Accumulator(request.getModel(), listener);
+      handle.setPartialUsage(() -> result.usage);
+      guard.scheduleAtFixedRate(() ->
+      {
+         long now = System.nanoTime();
+         if(now - lastRead.get() >= timeout || now - started >= timeout)
+         {
+            handle.fail(new ModelProviderException(ModelProviderException.Kind.TIMEOUT, null, "The provider did not answer in time.").withPartialUsage(result.usage));
+            worker.interrupt();
+            close(input.get());
+         }
+      }, 100, 100, TimeUnit.MILLISECONDS);
+      try
+      {
+         ModelCapabilities caps = request.getCapabilities() == null ? getCapabilities(request.getModel()) : request.getCapabilities();
+         ObjectNode body = OpenAiMapping.request(request, http.settings.getKind(), caps);
+         boolean strict = false;
+         for(JsonNode tool : body.path("tools"))
+         {
+            strict |= tool.path("function").path("strict").asBoolean();
+         }
+         HttpResponse<InputStream> response = http.client.send(http.request(request.getModel(), http.settings.getRequestTimeoutSeconds())
+            .POST(java.net.http.HttpRequest.BodyPublishers.ofString(body.toString())).build(), HttpResponse.BodyHandlers.ofInputStream());
+         input.set(response.body());
+         result.requestId = OpenAiHttp.requestId(response);
+         if(handle.isCancelled())
+         {
+            return;
+         }
+         if(response.statusCode() != 200)
+         {
+            throw (http.error(response.statusCode(), new String(response.body().readNBytes(64 * 1024), StandardCharsets.UTF_8), result.requestId, strict));
+         }
+         if(!Boolean.FALSE.equals(request.getStreaming()) && Boolean.TRUE.equals(caps.getStreaming()))
+         {
+            readEvents(response.body(), lastRead, result, strict, handle);
+         }
+         else
+         {
+            result.accept(OpenAiHttp.JSON.readTree(response.body()), false, http, strict);
+         }
+         handle.complete(result.response());
+      }
+      catch(ModelProviderException e)
+      {
+         handle.fail(e.withPartialUsage(result.usage));
+      }
+      catch(HttpTimeoutException e)
+      {
+         handle.fail(new ModelProviderException(ModelProviderException.Kind.TIMEOUT, null, "The provider did not answer in time.").withPartialUsage(result.usage));
+      }
+      catch(InterruptedException e)
+      {
+         Thread.currentThread().interrupt();
+         if(!handle.isCancelled())
+         {
+            handle.fail(new ModelProviderException(ModelProviderException.Kind.NETWORK, null, "The provider request was interrupted."));
+         }
+      }
+      catch(IOException | RuntimeException e)
+      {
+         ////////////////////////////////////////////////////////////////////////
+         // a transport error at or past the deadline is the timeout itself    //
+         // (the JDK client or the guard closed the call), whichever saw it    //
+         // first; report it as TIMEOUT so the kind does not depend on a race. //
+         ////////////////////////////////////////////////////////////////////////
+         long now = System.nanoTime();
+         long margin = TimeUnit.MILLISECONDS.toNanos(200);
+         boolean late = now - started >= timeout - margin || now - lastRead.get() >= timeout - margin;
+         handle.fail((late ? new ModelProviderException(ModelProviderException.Kind.TIMEOUT, null, "The provider did not answer in time.") : OpenAiHttp.transportError(e)).withPartialUsage(result.usage));
+      }
+      finally
+      {
+         guard.shutdownNow();
+         close(input.get());
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** SSE data fields, CRLF, comments, multi-line data and an optional DONE marker.
+    *******************************************************************************/
+   private void readEvents(InputStream stream, AtomicLong lastRead, Accumulator result, boolean strict, CompletableStreamHandle handle) throws IOException, ModelProviderException
+   {
+      BufferedReader reader = new BufferedReader(new InputStreamReader(stream, StandardCharsets.UTF_8));
+      StringBuilder data = new StringBuilder();
+      String line;
+      while(!handle.isCancelled() && (line = reader.readLine()) != null)
+      {
+         lastRead.set(System.nanoTime());
+         if(line.isEmpty())
+         {
+            if(data.length() > 0)
+            {
+               if("[DONE]".equals(data.toString().trim()))
+               {
+                  return;
+               }
+               result.accept(OpenAiHttp.JSON.readTree(data.toString()), true, http, strict);
+               data.setLength(0);
+            }
+         }
+         else if(line.startsWith("data:"))
+         {
+            if(data.length() > 0)
+            {
+               data.append('\n');
+            }
+            data.append(line.substring(5).stripLeading());
+         }
+      }
+      if(data.length() > 0 && !"[DONE]".equals(data.toString().trim()))
+      {
+         result.accept(OpenAiHttp.JSON.readTree(data.toString()), true, http, strict);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Closing an already cancelled stream is harmless.
+    *******************************************************************************/
+   private static void close(InputStream input)
+   {
+      if(input != null)
+      {
+         try
+         {
+            input.close();
+         }
+         catch(IOException e)
+         {
+            // The aborted HTTP call may already have closed the stream.
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Tool arguments arrive as JSON fragments, ordered by call index.
+    *******************************************************************************/
+   private static class Tool
+   {
+      private String id = "";
+      private String name = "";
+      private final StringBuilder arguments = new StringBuilder();
+      private boolean announced;
+   }
+
+
+
+   /*******************************************************************************
+    ** Shared mapping for stream chunks and one-shot responses.
+    *******************************************************************************/
+   private static class Accumulator
+   {
+      private final ModelEventListener listener;
+      private final StringBuilder text = new StringBuilder();
+      private final Map<Integer, Tool> tools = new TreeMap<>();
+      private volatile ModelUsage usage = new ModelUsage();
+      private String model;
+      private String requestId;
+      private String stop = ModelResponse.STOP_END_TURN;
+
+
+
+      /*******************************************************************************
+       ** One completion.
+       *******************************************************************************/
+      Accumulator(String model, ModelEventListener listener)
+      {
+         this.model = model;
+         this.listener = listener;
+      }
+
+
+
+      /*******************************************************************************
+       ** Ignore reasoning fields; retain only text, tools and billable usage.
+       *******************************************************************************/
+      void accept(JsonNode chunk, boolean streaming, OpenAiHttp http, boolean strict) throws ModelProviderException
+      {
+         if(chunk.has("error"))
+         {
+            JsonNode error = chunk.path("error");
+            int status = error.path("status").asInt(error.path("code").asInt(500));
+            String type = error.path("type").asText();
+            if(status == 500)
+            {
+               status = switch(type)
+               {
+                  case "invalid_request_error" -> 400;
+                  case "authentication_error" -> 401;
+                  case "rate_limit_error" -> 429;
+                  case "overloaded_error" -> 503;
+                  default -> 500;
+               };
+            }
+            throw (http.error(status, chunk.toString(), requestId, strict));
+         }
+         model = chunk.path("model").asText(model);
+         if(chunk.hasNonNull("usage"))
+         {
+            JsonNode used = chunk.get("usage");
+            long cached = used.path("prompt_tokens_details").path("cached_tokens").asLong();
+            usage = new ModelUsage().withInputTokens(Math.max(0, used.path("prompt_tokens").asLong() - cached))
+               .withOutputTokens(used.path("completion_tokens").asLong()).withCacheReadTokens(cached);
+         }
+         for(JsonNode choice : chunk.path("choices"))
+         {
+            if(choice.path("index").asInt() != 0)
+            {
+               continue;
+            }
+            JsonNode delta = choice.path(streaming ? "delta" : "message");
+            String content = delta.path("content").asText("");
+            if(!content.isEmpty())
+            {
+               text.append(content);
+               listener.onTextDelta(content);
+            }
+            int position = 0;
+            for(JsonNode call : delta.path("tool_calls"))
+            {
+               Tool tool = tools.computeIfAbsent(call.path("index").asInt(position++), k -> new Tool());
+               if(tool.id.isEmpty())
+               {
+                  tool.id = call.path("id").asText("");
+               }
+               if(tool.name.isEmpty())
+               {
+                  tool.name = call.path("function").path("name").asText("");
+               }
+               tool.arguments.append(call.path("function").path("arguments").asText(""));
+               if(!tool.announced && !tool.id.isEmpty() && !tool.name.isEmpty())
+               {
+                  listener.onToolUseStart(tool.id, tool.name);
+                  tool.announced = true;
+               }
+            }
+            if(choice.hasNonNull("finish_reason"))
+            {
+               stop = switch(choice.get("finish_reason").asText())
+               {
+                  case "tool_calls", "function_call" -> ModelResponse.STOP_TOOL_USE;
+                  case "length" -> ModelResponse.STOP_MAX_TOKENS;
+                  case "content_filter" -> ModelResponse.STOP_REFUSAL;
+                  default -> ModelResponse.STOP_END_TURN;
+               };
+            }
+         }
+      }
+
+
+
+      /*******************************************************************************
+       ** Parse complete argument objects only, preserving parallel call order.
+       *******************************************************************************/
+      ModelResponse response()
+      {
+         List<ModelPart> parts = new ArrayList<>();
+         if(!text.isEmpty())
+         {
+            parts.add(ModelPart.text(text.toString()));
+         }
+         for(Map.Entry<Integer, Tool> entry : tools.entrySet())
+         {
+            Tool tool = entry.getValue();
+            if(tool.id.isEmpty())
+            {
+               tool.id = "call_" + entry.getKey();
+            }
+            if(!tool.announced)
+            {
+               listener.onToolUseStart(tool.id, tool.name);
+               tool.announced = true;
+            }
+            Map<String, Object> arguments;
+            try
+            {
+               arguments = tool.arguments.isEmpty() ? Map.of() : OpenAiHttp.JSON.readerFor(new TypeReference<Map<String, Object>>() {})
+                  .with(com.fasterxml.jackson.databind.DeserializationFeature.FAIL_ON_TRAILING_TOKENS).readValue(tool.arguments.toString());
+               if(arguments == null)
+               {
+                  throw (new IOException("Tool arguments must be an object."));
+               }
+            }
+            catch(IOException e)
+            {
+               arguments = Map.of("_invalid_arguments", tool.arguments.substring(0, Math.min(200, tool.arguments.length())));
+            }
+            parts.add(ModelPart.toolUse(tool.id, tool.name, arguments));
+         }
+         if(!tools.isEmpty() && ModelResponse.STOP_END_TURN.equals(stop))
+         {
+            stop = ModelResponse.STOP_TOOL_USE;
+         }
+         return (new ModelResponse().withModel(model).withRequestId(requestId).withParts(parts).withUsage(usage).withStopReason(stop));
+      }
+   }
+}

qbit-assistant-provider-openai/src/main/java/com/kingsrook/qbits/assistant/provider/openai/OpenAiCompatibleProviderType.java

@@ -0,0 +1,199 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.provider.openai;
+
+
+import java.util.List;
+import com.kingsrook.qbits.assistant.spi.AssistantModelProvider;
+import com.kingsrook.qbits.assistant.spi.AssistantProviderType;
+import com.kingsrook.qbits.assistant.spi.DiscoveredModel;
+import com.kingsrook.qbits.assistant.spi.HealthResult;
+import com.kingsrook.qbits.assistant.spi.ModelProviderException;
+import com.kingsrook.qbits.assistant.spi.ProviderSettings;
+
+
+/*******************************************************************************
+ ** One installed adapter for the Chat Completions dialects.
+ *******************************************************************************/
+public class OpenAiCompatibleProviderType implements AssistantProviderType
+{
+   /*******************************************************************************
+    ** Installed adapter id.
+    *******************************************************************************/
+   @Override
+   public String getType()
+   {
+      return ("openai-compatible");
+   }
+
+
+
+   /*******************************************************************************
+    ** Settings label.
+    *******************************************************************************/
+   @Override
+   public String getLabel()
+   {
+      return ("OpenAI-compatible");
+   }
+
+
+
+   /*******************************************************************************
+    ** Discover endpoint-specific models instead of guessing ids.
+    *******************************************************************************/
+   @Override
+   public List<String> getModels()
+   {
+      return (List.of());
+   }
+
+
+
+   /*******************************************************************************
+    ** Extensible kind list.
+    *******************************************************************************/
+   @Override
+   public List<String> getKinds()
+   {
+      return (List.of("OPENAI", "AZURE_OPENAI", "OPENROUTER", "OLLAMA", "LM_STUDIO", "VLLM", "LLAMA_CPP", "OPENAI_COMPATIBLE"));
+   }
+
+
+
+   /*******************************************************************************
+    ** The legacy factory uses the generic dialect.
+    *******************************************************************************/
+   @Override
+   public String getDefaultApiKeyEnvName()
+   {
+      return (null);
+   }
+
+
+
+   /*******************************************************************************
+    ** The generic dialect requires an explicit URL.
+    *******************************************************************************/
+   @Override
+   public String getDefaultBaseUrl()
+   {
+      return (null);
+   }
+
+
+
+   /*******************************************************************************
+    ** Built-in endpoints. Redirects are never followed.
+    *******************************************************************************/
+   @Override
+   public String getDefaultBaseUrl(String kind)
+   {
+      return (switch(kind)
+      {
+         case "OPENAI" -> "https://api.openai.com/v1";
+         case "OPENROUTER" -> "https://openrouter.ai/api/v1";
+         case "OLLAMA" -> "http://localhost:11434/v1";
+         case "LM_STUDIO" -> "http://localhost:1234/v1";
+         case "VLLM" -> "http://localhost:8000/v1";
+         case "LLAMA_CPP" -> "http://localhost:8080/v1";
+         default -> null;
+      });
+   }
+
+
+
+   /*******************************************************************************
+    ** Default key references, never key values.
+    *******************************************************************************/
+   @Override
+   public String getDefaultApiKeyEnvName(String kind)
+   {
+      return (switch(kind)
+      {
+         case "OPENAI" -> "OPENAI_API_KEY";
+         case "AZURE_OPENAI" -> "AZURE_OPENAI_API_KEY";
+         case "OPENROUTER" -> "OPENROUTER_API_KEY";
+         default -> null;
+      });
+   }
+
+
+
+   /*******************************************************************************
+    ** Location is an admin-editable fact, with a kind-based default.
+    *******************************************************************************/
+   @Override
+   public String getDefaultLocation(String kind)
+   {
+      return (List.of("OLLAMA", "LM_STUDIO", "VLLM", "LLAMA_CPP").contains(kind) ? "LOCAL" : "CLOUD");
+   }
+
+
+
+   /*******************************************************************************
+    ** Backward-compatible factory.
+    *******************************************************************************/
+   @Override
+   public AssistantModelProvider create(String apiKey, String baseUrl)
+   {
+      return (create(new ProviderSettings().withKind("OPENAI_COMPATIBLE").withApiKey(apiKey).withBaseUrl(baseUrl)));
+   }
+
+
+
+   /*******************************************************************************
+    ** Full connection settings.
+    *******************************************************************************/
+   @Override
+   public AssistantModelProvider create(ProviderSettings settings)
+   {
+      return (new OpenAiCompatibleModelProvider(settings));
+   }
+
+
+
+   /*******************************************************************************
+    ** Only a models request, never a completion.
+    *******************************************************************************/
+   @Override
+   public List<DiscoveredModel> discoverModels(ProviderSettings settings) throws ModelProviderException
+   {
+      return (new OpenAiHttp(settings).models(settings.getRequestTimeoutSeconds()));
+   }
+
+
+
+   /*******************************************************************************
+    ** A short models probe with latency and count.
+    *******************************************************************************/
+   @Override
+   public HealthResult checkHealth(ProviderSettings settings)
+   {
+      long start = System.nanoTime();
+      try
+      {
+         List<DiscoveredModel> models = new OpenAiHttp(settings).models(Math.min(10, settings.getRequestTimeoutSeconds()));
+         return (new HealthResult(true, (System.nanoTime() - start) / 1_000_000, models.size() + " models available"));
+      }
+      catch(ModelProviderException e)
+      {
+         return (new HealthResult(false, (System.nanoTime() - start) / 1_000_000,
+            e.getKind() + (e.getHttpStatus() == null ? "" : " HTTP " + e.getHttpStatus()) + ": " + e.getMessage()));
+      }
+   }
+}

qbit-assistant-provider-openai/src/main/java/com/kingsrook/qbits/assistant/provider/openai/OpenAiHttp.java

@@ -0,0 +1,297 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.provider.openai;
+
+
+import java.io.IOException;
+import java.net.URI;
+import java.net.URLEncoder;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.net.http.HttpTimeoutException;
+import java.nio.charset.StandardCharsets;
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.kingsrook.qbits.assistant.spi.DiscoveredModel;
+import com.kingsrook.qbits.assistant.spi.ModelProviderException;
+import com.kingsrook.qbits.assistant.spi.ProviderSettings;
+import javax.net.ssl.SSLHandshakeException;
+
+
+/*******************************************************************************
+ ** Shared HTTP/authentication/error mapping. ProviderService guards URLs before
+ ** constructing this transport; redirects must not move keys to another host.
+ *******************************************************************************/
+final class OpenAiHttp
+{
+   static final ObjectMapper JSON = new ObjectMapper();
+   final HttpClient client;
+   final ProviderSettings settings;
+   private final String base;
+
+
+
+   /*******************************************************************************
+    ** Copy settings so callers cannot mutate a cached client's credentials.
+    *******************************************************************************/
+   OpenAiHttp(ProviderSettings source)
+   {
+      settings = new ProviderSettings().withKind(source.getKind() == null ? "OPENAI_COMPATIBLE" : source.getKind())
+         .withTlsCaBundle(source.getTlsCaBundle()).withSslContext(source.getSslContext())
+         .withApiKey(source.getApiKey()).withBaseUrl(source.getBaseUrl()).withApiVersion(source.getApiVersion()).withRegion(source.getRegion())
+         .withBearerTokenSupplier(source.getBearerTokenSupplier()).withCloudProject(source.getCloudProject())
+         .withConnectTimeoutSeconds(source.getConnectTimeoutSeconds()).withRequestTimeoutSeconds(source.getRequestTimeoutSeconds());
+      String url = settings.getBaseUrl() == null ? new OpenAiCompatibleProviderType().getDefaultBaseUrl(settings.getKind()) : settings.getBaseUrl();
+      if(url == null)
+      {
+         throw (new IllegalArgumentException("A base URL is required for this provider kind."));
+      }
+      base = url.replaceAll("/+$", "");
+      HttpClient.Builder builder = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(settings.getConnectTimeoutSeconds())).followRedirects(HttpClient.Redirect.NEVER);
+      if(settings.getSslContext() != null)
+      {
+         builder.sslContext(settings.getSslContext());
+      }
+      client = builder.build();
+   }
+
+
+
+   /*******************************************************************************
+    ** Azure uses deployment paths and a version query parameter.
+    *******************************************************************************/
+   HttpRequest.Builder request(String model, Integer seconds) throws ModelProviderException
+   {
+      return (request(model, seconds, "chat/completions"));
+   }
+
+
+
+   /*******************************************************************************
+    ** Chat and embeddings share authentication, TLS, deadlines and Azure paths.
+    *******************************************************************************/
+   HttpRequest.Builder request(String model, Integer seconds, String operation) throws ModelProviderException
+   {
+      try
+      {
+         String path = model == null ? "/models" : "/" + operation;
+         if("AZURE_OPENAI".equals(settings.getKind()))
+         {
+            path = model == null ? "/openai/models" : "/openai/deployments/" + encode(model) + "/" + operation;
+            path += "?api-version=" + encode(settings.getApiVersion() == null || settings.getApiVersion().isBlank() ? "2024-10-21" : settings.getApiVersion());
+         }
+         HttpRequest.Builder builder = HttpRequest.newBuilder(URI.create(base + path)).timeout(Duration.ofSeconds(seconds)).header("Content-Type", "application/json");
+         if(settings.getBearerTokenSupplier() != null)
+         {
+            String token = settings.getBearerTokenSupplier().get();
+            if(token == null || token.isBlank())
+            {
+               throw (new ModelProviderException(ModelProviderException.Kind.AUTHENTICATION, null, "The provider access token is unavailable."));
+            }
+            builder.header("Authorization", "Bearer " + token);
+         }
+         else if(settings.getApiKey() != null && !settings.getApiKey().isBlank())
+         {
+            if("AZURE_OPENAI".equals(settings.getKind()))
+            {
+               builder.header("api-key", settings.getApiKey());
+            }
+            else
+            {
+               builder.header("Authorization", "Bearer " + settings.getApiKey());
+            }
+         }
+         return (builder);
+      }
+      catch(IllegalArgumentException e)
+      {
+         throw (new ModelProviderException(ModelProviderException.Kind.INVALID_REQUEST, null, "The provider connection settings are invalid."));
+      }
+      catch(RuntimeException e)
+      {
+         throw (new ModelProviderException(ModelProviderException.Kind.AUTHENTICATION, null, "Could not obtain the provider access token."));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Models with optional server-specific context information.
+    *******************************************************************************/
+   List<DiscoveredModel> models(Integer seconds) throws ModelProviderException
+   {
+      CompletableFuture<HttpResponse<String>> pending = client.sendAsync(request(null, seconds).GET().build(), HttpResponse.BodyHandlers.ofString());
+      try
+      {
+         HttpResponse<String> response = pending.get(seconds, TimeUnit.SECONDS);
+         if(response.statusCode() != 200)
+         {
+            throw (error(response.statusCode(), response.body(), requestId(response), false));
+         }
+         JsonNode body = JSON.readTree(response.body());
+         if(body.has("error"))
+         {
+            throw (error(500, response.body(), requestId(response), false));
+         }
+         List<DiscoveredModel> result = new ArrayList<>();
+         for(JsonNode model : body.path("data"))
+         {
+            String id = model.path("id").asText();
+            if(id.isBlank())
+            {
+               continue;
+            }
+            int context = model.path("context_length").asInt(model.path("max_model_len").asInt(model.path("meta").path("n_ctx_train").asInt()));
+            result.add(new DiscoveredModel(id, model.path("name").asText(id), context > 0 ? context : null, model.path("owned_by").asText(null)));
+         }
+         return (result);
+      }
+      catch(TimeoutException e)
+      {
+         throw (new ModelProviderException(ModelProviderException.Kind.TIMEOUT, null, "The provider did not answer in time."));
+      }
+      catch(ExecutionException e)
+      {
+         throw (transportError(e));
+      }
+      catch(InterruptedException e)
+      {
+         Thread.currentThread().interrupt();
+         throw (new ModelProviderException(ModelProviderException.Kind.NETWORK, null, "The provider request was interrupted."));
+      }
+      catch(IOException e)
+      {
+         throw (transportError(e));
+      }
+      finally
+      {
+         pending.cancel(true);
+         client.close();
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Sanitize errors, explicitly removing even short or unusual API keys.
+    *******************************************************************************/
+   ModelProviderException error(int status, String body, String requestId, boolean strict)
+   {
+      String message = "The provider refused the request.";
+      String type = "openai-compatible";
+      try
+      {
+         JsonNode error = JSON.readTree(body).path("error");
+         message = error.path("message").asText(message);
+         type = error.path("type").asText(type);
+      }
+      catch(Exception e)
+      {
+         // Do not expose unstructured proxy pages or request bodies.
+      }
+      message = safe(message);
+      type = safe(type);
+      ModelProviderException.Kind kind = errorKind(status);
+      String lower = message == null ? "" : message.toLowerCase(Locale.ROOT);
+      return (new ModelProviderException(kind, status, message).withProviderDetails(type, message, safe(requestId))
+         .withStrictSchemaRejected(strict && status == 400 && (lower.contains("strict") || lower.contains("schema") || lower.contains("grammar"))));
+   }
+
+
+
+   /*******************************************************************************
+    ** Credential-free diagnostics.
+    *******************************************************************************/
+   private String safe(String value)
+   {
+      if(settings.getBearerTokenSupplier() != null)
+      {
+         // Dynamic credentials can be echoed by a remote error. Do not retain
+         // tokens or include remote diagnostics for bearer-supplier requests.
+         return (null);
+      }
+      String key = settings.getApiKey();
+      return (ModelProviderException.sanitizeProviderMessage(value == null || key == null || key.isEmpty() ? value : value.replace(key, "[redacted]"), 300));
+   }
+
+
+
+   /*******************************************************************************
+    ** Common request-id headers.
+    *******************************************************************************/
+   static String requestId(HttpResponse<?> response)
+   {
+      return (response.headers().firstValue("x-request-id").orElse(response.headers().firstValue("apim-request-id").orElse(null)));
+   }
+
+
+
+   /*******************************************************************************
+    ** Encode a single path segment or query value.
+    *******************************************************************************/
+   private static String encode(String value)
+   {
+      return (URLEncoder.encode(value, StandardCharsets.UTF_8).replace("+", "%20"));
+   }
+
+
+
+   /*******************************************************************************
+    ** Map the provider error category.
+    *******************************************************************************/
+   private static ModelProviderException.Kind errorKind(int status)
+   {
+      return (switch(status)
+      {
+         case 401, 403 -> ModelProviderException.Kind.AUTHENTICATION;
+         case 429 -> ModelProviderException.Kind.RATE_LIMITED;
+         case 503, 529 -> ModelProviderException.Kind.OVERLOADED;
+         case 400, 404, 422 -> ModelProviderException.Kind.INVALID_REQUEST;
+         default -> status >= 500 ? ModelProviderException.Kind.SERVER : ModelProviderException.Kind.INVALID_REQUEST;
+      });
+   }
+
+
+   /*******************************************************************************
+    ** Fixed diagnostics omit remote certificate details, URLs and credentials.
+    *******************************************************************************/
+   static ModelProviderException transportError(Throwable error)
+   {
+      for(Throwable cause = error; cause != null; cause = cause.getCause())
+      {
+         if(cause instanceof SSLHandshakeException)
+         {
+            return (new ModelProviderException(ModelProviderException.Kind.NETWORK, null,
+               "The provider TLS certificate is not trusted or does not match the host. Check tlsCaBundle and the HTTPS hostname."));
+         }
+         if(cause instanceof HttpTimeoutException)
+         {
+            return (new ModelProviderException(ModelProviderException.Kind.TIMEOUT, null, "The provider did not answer in time."));
+         }
+      }
+      return (new ModelProviderException(ModelProviderException.Kind.NETWORK, null, "Could not read the provider response."));
+   }
+}

qbit-assistant-provider-openai/src/main/java/com/kingsrook/qbits/assistant/provider/openai/OpenAiMapping.java

@@ -0,0 +1,216 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.provider.openai;
+
+
+import java.util.List;
+import java.util.Locale;
+import java.util.stream.Collectors;
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.node.ArrayNode;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.kingsrook.qbits.assistant.spi.ModelCapabilities;
+import com.kingsrook.qbits.assistant.spi.ModelMessage;
+import com.kingsrook.qbits.assistant.spi.ModelPart;
+import com.kingsrook.qbits.assistant.spi.ModelRequest;
+import com.kingsrook.qbits.assistant.spi.ModelToolDefinition;
+import com.kingsrook.qbits.assistant.spi.SystemBlock;
+
+
+/*******************************************************************************
+ ** Chat Completions request mapping and conservative strict-schema checks.
+ *******************************************************************************/
+final class OpenAiMapping
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private OpenAiMapping()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Map only capabilities the target dialect supports.
+    *******************************************************************************/
+   static ObjectNode request(ModelRequest request, String kind, ModelCapabilities capabilities) throws JsonProcessingException
+   {
+      ObjectNode body = OpenAiHttp.JSON.createObjectNode();
+      boolean streaming = !Boolean.FALSE.equals(request.getStreaming()) && Boolean.TRUE.equals(capabilities.getStreaming());
+      boolean nativeOpenAi = List.of("OPENAI", "AZURE_OPENAI").contains(kind);
+      String model = request.getModel();
+      body.put("model", "VERTEX".equals(kind) && model != null && !model.contains("/") ? "google/" + model : model);
+      body.put("stream", streaming);
+      if(streaming)
+      {
+         body.putObject("stream_options").put("include_usage", true);
+      }
+      if(request.getMaxTokens() != null)
+      {
+         body.put(nativeOpenAi ? "max_completion_tokens" : "max_tokens", request.getMaxTokens());
+      }
+      if(Boolean.TRUE.equals(capabilities.getReasoningEffort()) && request.getEffort() != null)
+      {
+         String effort = request.getEffort().toLowerCase(Locale.ROOT);
+         body.put("reasoning_effort", List.of("low", "medium").contains(effort) ? effort : "high");
+      }
+      ArrayNode messages = body.putArray("messages");
+      if(!request.getSystem().isEmpty())
+      {
+         messages.addObject().put("role", "system").put("content", request.getSystem().stream().map(SystemBlock::getText).collect(Collectors.joining("\n\n")));
+      }
+      for(ModelMessage message : request.getMessages())
+      {
+         ObjectNode current = null;
+         for(ModelPart part : message.getParts())
+         {
+            if(part.getType() == ModelPart.Type.TOOL_RESULT)
+            {
+               current = null;
+               messages.addObject().put("role", "tool").put("tool_call_id", part.getToolUseId())
+                  .put("content", (Boolean.TRUE.equals(part.getIsError()) ? "ERROR: " : "") + part.getText());
+               continue;
+            }
+            if(current == null)
+            {
+               current = messages.addObject().put("role", message.getRole() == ModelMessage.Role.ASSISTANT ? "assistant" : "user");
+               current.put("content", "");
+            }
+            if(part.getType() == ModelPart.Type.TEXT)
+            {
+               if(current.get("content").isArray())
+               {
+                  ((ArrayNode) current.get("content")).addObject().put("type", "text").put("text", part.getText());
+               }
+               else
+               {
+                  current.put("content", current.path("content").asText() + part.getText());
+               }
+            }
+            else if(part.getType() == ModelPart.Type.IMAGE)
+            {
+               ///////////////////////////////////////////////////////////////////
+               // a message with an image switches to the content-part array    //
+               // form; messages without images keep the plain string content   //
+               ///////////////////////////////////////////////////////////////////
+               if(!current.get("content").isArray())
+               {
+                  String    text  = current.path("content").asText();
+                  ArrayNode array = current.putArray("content");
+                  if(!text.isEmpty())
+                  {
+                     array.addObject().put("type", "text").put("text", text);
+                  }
+               }
+               ((ArrayNode) current.get("content")).addObject().put("type", "image_url").putObject("image_url")
+                  .put("url", "data:" + part.getMediaType() + ";base64," + part.getData());
+            }
+            else if(part.getType() == ModelPart.Type.TOOL_USE)
+            {
+               ArrayNode calls = current.has("tool_calls") ? (ArrayNode) current.get("tool_calls") : current.putArray("tool_calls");
+               calls.addObject().put("id", part.getToolUseId()).put("type", "function").putObject("function")
+                  .put("name", part.getToolName()).put("arguments", OpenAiHttp.JSON.writeValueAsString(part.getInput()));
+            }
+         }
+      }
+      if(!request.getTools().isEmpty() && Boolean.TRUE.equals(capabilities.getTools()))
+      {
+         ArrayNode tools = body.putArray("tools");
+         for(ModelToolDefinition tool : request.getTools())
+         {
+            JsonNode schema = OpenAiHttp.JSON.valueToTree(tool.getInputSchema());
+            ObjectNode function = tools.addObject().put("type", "function").putObject("function").put("name", tool.getName()).put("description", tool.getDescription());
+            function.set("parameters", schema);
+            if(nativeOpenAi && Boolean.TRUE.equals(tool.getStrict()) && strictCompatible(schema))
+            {
+               function.put("strict", true);
+            }
+         }
+         if(List.of("OPENAI", "AZURE_OPENAI", "OPENROUTER", "VLLM").contains(kind))
+         {
+            body.put("parallel_tool_calls", Boolean.TRUE.equals(request.getParallelToolCalls()) && Boolean.TRUE.equals(capabilities.getParallelToolCalls()));
+         }
+      }
+      return (body);
+   }
+
+
+
+   /*******************************************************************************
+    ** Every object must forbid extras and require every declared property.
+    *******************************************************************************/
+   static boolean strictCompatible(JsonNode schema)
+   {
+      if(schema == null || !schema.isObject())
+      {
+         return (false);
+      }
+      JsonNode type = schema.path("type");
+      if("object".equals(type.asText()) || schema.has("properties") || (type.isArray() && type.toString().contains("\"object\"")))
+      {
+         if(!schema.has("additionalProperties") || !schema.get("additionalProperties").isBoolean() || schema.get("additionalProperties").asBoolean())
+         {
+            return (false);
+         }
+         JsonNode required = schema.path("required");
+         var names = schema.path("properties").fieldNames();
+         while(names.hasNext())
+         {
+            String name = names.next();
+            boolean found = false;
+            for(JsonNode value : required)
+            {
+               found |= name.equals(value.asText());
+            }
+            if(!found || !strictCompatible(schema.path("properties").get(name)))
+            {
+               return (false);
+            }
+         }
+      }
+      for(String keyword : List.of("items", "additionalProperties"))
+      {
+         if(schema.path(keyword).isObject() && !strictCompatible(schema.get(keyword)))
+         {
+            return (false);
+         }
+      }
+      for(String keyword : List.of("anyOf", "oneOf", "allOf", "prefixItems"))
+      {
+         for(JsonNode child : schema.path(keyword))
+         {
+            if(!strictCompatible(child))
+            {
+               return (false);
+            }
+         }
+      }
+      for(String keyword : List.of("$defs", "definitions"))
+      {
+         for(JsonNode child : schema.path(keyword))
+         {
+            if(!strictCompatible(child))
+            {
+               return (false);
+            }
+         }
+      }
+      return (true);
+   }
+}

qbit-assistant-provider-openai/src/test/java/com/kingsrook/qbits/assistant/provider/openai/LiveOpenAiCompatibleTest.java

@@ -0,0 +1,77 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.provider.openai;
+
+
+import java.nio.file.Path;
+import java.time.Duration;
+import java.util.List;
+import com.kingsrook.qbits.assistant.AssistantQBitConfig;
+import com.kingsrook.qbits.assistant.spi.ModelMessage;
+import com.kingsrook.qbits.assistant.spi.ModelProviderException;
+import com.kingsrook.qbits.assistant.spi.ModelRequest;
+import com.kingsrook.qbits.assistant.spi.ProviderSettings;
+import org.junit.jupiter.api.Assumptions;
+import org.junit.jupiter.api.Tag;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** Opt-in smoke test; never contacts an endpoint in the default build.
+ *******************************************************************************/
+@Tag("live")
+class LiveOpenAiCompatibleTest
+{
+   /*******************************************************************************
+    ** All connection details come from environment references.
+    *******************************************************************************/
+   @Test
+   void live() throws Exception
+   {
+      String url = System.getenv("ASSISTANT_LIVE_OPENAI_BASE_URL");
+      String model = System.getenv("ASSISTANT_LIVE_OPENAI_MODEL");
+      Assumptions.assumeTrue(url != null && !url.isBlank() && model != null && !model.isBlank(), "Live URL and model must be set");
+      String kind = System.getenv("ASSISTANT_LIVE_OPENAI_KIND");
+      String keyEnv = System.getenv("ASSISTANT_LIVE_OPENAI_KEY_ENV");
+      ProviderSettings settings = new ProviderSettings().withKind(kind == null || kind.isBlank() ? "OLLAMA" : kind)
+         .withBaseUrl(url).withApiKey(keyEnv == null || keyEnv.isBlank() ? null : System.getenv(keyEnv));
+      String caFile = System.getenv("ASSISTANT_LIVE_OPENAI_CA_FILE");
+      if(caFile != null && !caFile.isBlank())
+      {
+         settings.withTlsCaBundle("live").withSslContext(new AssistantQBitConfig().withTrustedCaBundleFile("live", Path.of(caFile)).getTrustedCaBundles().get("live"));
+      }
+      try
+      {
+         OpenAiCompatibleProviderType type = new OpenAiCompatibleProviderType();
+         Assumptions.assumeTrue(Boolean.TRUE.equals(type.checkHealth(settings).healthy()), "Live health probe must pass");
+         assertThat(type.discoverModels(settings)).isNotEmpty();
+         var provider = type.create(settings);
+         StringBuilder text = new StringBuilder();
+         provider.stream(new ModelRequest().withModel(model).withMaxTokens(128).withMessages(List.of(ModelMessage.user("Reply with OK."))), text::append).await(Duration.ofSeconds(120));
+         assertThat(text).isNotEmpty();
+         var response = provider.stream(new ModelRequest().withModel(model).withMaxTokens(256).withTools(List.of(OpenAiContractTest.tool()))
+            .withMessages(List.of(ModelMessage.user("Call lookup with q set to hello. Do not answer without calling the tool."))), t -> {}).await(Duration.ofSeconds(120));
+         assertThat(response.getToolUses()).anyMatch(t -> "lookup".equals(t.getToolName()));
+      }
+      catch(ModelProviderException e)
+      {
+         Assumptions.assumeFalse(e.getKind() == ModelProviderException.Kind.NETWORK || e.getKind() == ModelProviderException.Kind.TIMEOUT, "Live endpoint unreachable (including TLS)");
+         throw (e);
+      }
+   }
+}

qbit-assistant-provider-openai/src/test/java/com/kingsrook/qbits/assistant/provider/openai/MockOpenAiServer.java

@@ -0,0 +1,183 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.provider.openai;
+
+
+import java.io.IOException;
+import java.net.InetSocketAddress;
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.LinkedBlockingQueue;
+import javax.net.ssl.SSLContext;
+import com.sun.net.httpserver.HttpExchange;
+import com.sun.net.httpserver.HttpServer;
+import com.sun.net.httpserver.HttpsConfigurator;
+import com.sun.net.httpserver.HttpsServer;
+
+
+/*******************************************************************************
+ ** Loopback-only scripted Chat Completions server with captured requests.
+ *******************************************************************************/
+class MockOpenAiServer implements AutoCloseable
+{
+   final List<Captured> requests = new CopyOnWriteArrayList<>();
+   private final LinkedBlockingQueue<Script> scripts = new LinkedBlockingQueue<>();
+   private final HttpServer server;
+   private final ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();
+
+
+
+   /*******************************************************************************
+    ** Captured wire data, only synthetic keys in default tests.
+    *******************************************************************************/
+   record Captured(String path, String authorization, String apiKey, String body)
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Delay can be before headers or after an SSE keep-alive.
+    *******************************************************************************/
+   record Script(int status, String body, long delayMs, boolean afterHeaders, CountDownLatch started)
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Bind only the loopback interface.
+    *******************************************************************************/
+   MockOpenAiServer() throws IOException
+   {
+      this(null);
+   }
+
+
+
+   /*******************************************************************************
+    ** Optional TLS uses exactly the same scripted endpoints and request capture.
+    *******************************************************************************/
+   MockOpenAiServer(SSLContext tls) throws IOException
+   {
+      if(tls == null)
+      {
+         server = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
+      }
+      else
+      {
+         HttpsServer https = HttpsServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
+         https.setHttpsConfigurator(new HttpsConfigurator(tls));
+         server = https;
+      }
+      server.createContext("/", this::serve);
+      server.setExecutor(executor);
+      server.start();
+   }
+
+
+
+   /*******************************************************************************
+    ** Base URL deliberately has the v1 prefix.
+    *******************************************************************************/
+   String url()
+   {
+      return ((server instanceof HttpsServer ? "https://localhost:" : "http://127.0.0.1:") + server.getAddress().getPort() + "/v1");
+   }
+
+
+
+   /*******************************************************************************
+    ** Queue a reply.
+    *******************************************************************************/
+   void enqueue(int status, String body)
+   {
+      scripts.add(new Script(status, body, 0, false, new CountDownLatch(1)));
+   }
+
+
+
+   /*******************************************************************************
+    ** Queue a stalled response.
+    *******************************************************************************/
+   CountDownLatch stall(boolean afterHeaders)
+   {
+      CountDownLatch started = new CountDownLatch(1);
+      scripts.add(new Script(200, "data: [DONE]\n\n", 2500, afterHeaders, started));
+      return (started);
+   }
+
+
+
+   /*******************************************************************************
+    ** Capture and reply, tolerating client cancellation.
+    *******************************************************************************/
+   private void serve(HttpExchange exchange) throws IOException
+   {
+      try(exchange)
+      {
+         requests.add(new Captured(exchange.getRequestURI().toString(), exchange.getRequestHeaders().getFirst("Authorization"),
+            exchange.getRequestHeaders().getFirst("api-key"), new String(exchange.getRequestBody().readAllBytes(), StandardCharsets.UTF_8)));
+         Script script = scripts.poll();
+         if(script == null)
+         {
+            exchange.sendResponseHeaders(500, -1);
+            return;
+         }
+         if(!script.afterHeaders())
+         {
+            script.started().countDown();
+            Thread.sleep(script.delayMs());
+         }
+         exchange.getResponseHeaders().set("Content-Type", script.body().startsWith("{") ? "application/json" : "text/event-stream");
+         exchange.getResponseHeaders().set("x-request-id", "mock-request");
+         exchange.sendResponseHeaders(script.status(), 0);
+         if(script.afterHeaders())
+         {
+            exchange.getResponseBody().write(": keep-alive\r\n\r\n".getBytes(StandardCharsets.UTF_8));
+            exchange.getResponseBody().flush();
+            script.started().countDown();
+            Thread.sleep(script.delayMs());
+         }
+         exchange.getResponseBody().write(script.body().getBytes(StandardCharsets.UTF_8));
+      }
+      catch(InterruptedException e)
+      {
+         Thread.currentThread().interrupt();
+      }
+      catch(IOException e)
+      {
+         // Cancellation closes the client socket while a script is writing.
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Stop all handlers.
+    *******************************************************************************/
+   @Override
+   public void close()
+   {
+      server.stop(0);
+      executor.shutdownNow();
+   }
+}

qbit-assistant-provider-openai/src/test/java/com/kingsrook/qbits/assistant/provider/openai/OpenAiContractTest.java

@@ -0,0 +1,577 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.provider.openai;
+
+
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.kingsrook.qbits.assistant.spi.ModelCapabilities;
+import com.kingsrook.qbits.assistant.spi.ModelEventListener;
+import com.kingsrook.qbits.assistant.spi.ModelMessage;
+import com.kingsrook.qbits.assistant.spi.ModelPart;
+import com.kingsrook.qbits.assistant.spi.ModelProviderException;
+import com.kingsrook.qbits.assistant.spi.ModelRequest;
+import com.kingsrook.qbits.assistant.spi.ModelResponse;
+import com.kingsrook.qbits.assistant.spi.ModelToolDefinition;
+import com.kingsrook.qbits.assistant.spi.ProviderSettings;
+import com.kingsrook.qbits.assistant.spi.SystemBlock;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
+import org.junit.jupiter.params.provider.ValueSource;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+
+/*******************************************************************************
+ ** Contract tests exercise the wire protocol through localhost HTTP only.
+ *******************************************************************************/
+class OpenAiContractTest
+{
+   /*******************************************************************************
+    ** Classifiers opt out of streaming even when the model supports it.
+    *******************************************************************************/
+   @Test
+   void nonStreamingClassifier() throws Exception
+   {
+      try(MockOpenAiServer server = new MockOpenAiServer())
+      {
+         server.enqueue(200, "{\"model\":\"test\",\"choices\":[{\"message\":{\"content\":\"SIMPLE\"},\"finish_reason\":\"stop\"}],\"usage\":{\"prompt_tokens\":18,\"completion_tokens\":1}}");
+         var provider = new OpenAiCompatibleModelProvider(settings(server, "OPENAI"));
+         ModelResponse response = provider.stream(request().withStreaming(false).withMaxTokens(4), new StringBuilder()::append).await(Duration.ofSeconds(3));
+         assertThat(response.getText()).isEqualTo("SIMPLE");
+         JsonNode body = OpenAiHttp.JSON.readTree(server.requests.getFirst().body());
+         assertThat(body.path("stream").asBoolean()).isFalse();
+         assertThat(body.path("max_completion_tokens").asInt()).isEqualTo(4);
+         assertThat(body.has("stream_options")).isFalse();
+      }
+   }
+
+
+
+   static final String TEXT = "data: {\"model\":\"test\",\"choices\":[{\"delta\":{\"content\":\"OK\"},\"finish_reason\":\"stop\"}]}\r\n\r\ndata: [DONE]\r\n\r\n";
+
+
+
+   /*******************************************************************************
+    ** A minimal request, also shared by the opt-in live test.
+    *******************************************************************************/
+   static ModelRequest request()
+   {
+      return (new ModelRequest().withModel("test").withMaxTokens(32).withEffort("max").withMessages(List.of(ModelMessage.user("Hello"))));
+   }
+
+
+
+   /*******************************************************************************
+    ** Synthetic settings for the local server.
+    *******************************************************************************/
+   static ProviderSettings settings(MockOpenAiServer server, String kind)
+   {
+      return (new ProviderSettings().withKind(kind).withBaseUrl(server.url()).withApiKey("synthetic-key"));
+   }
+
+
+
+   /*******************************************************************************
+    ** Strict-compatible schema with one required property.
+    *******************************************************************************/
+   static ModelToolDefinition tool()
+   {
+      return (new ModelToolDefinition().withName("lookup").withDescription("Look up a value").withStrict(true)
+         .withInputSchema(Map.of("type", "object", "additionalProperties", false, "properties", Map.of("q", Map.of("type", "string")), "required", List.of("q"))));
+   }
+
+
+
+   /*******************************************************************************
+    ** Kind-specific parameters, ordered tool results, auth and strict behavior.
+    *******************************************************************************/
+   @ParameterizedTest
+   @ValueSource(strings = { "OPENAI", "AZURE_OPENAI", "OPENROUTER", "OLLAMA", "LM_STUDIO", "VLLM", "LLAMA_CPP", "OPENAI_COMPATIBLE" })
+   void requestContract(String kind) throws Exception
+   {
+      try(MockOpenAiServer server = new MockOpenAiServer())
+      {
+         server.enqueue(200, TEXT);
+         boolean nativeKind = kind.equals("OPENAI") || kind.equals("AZURE_OPENAI");
+         ModelRequest request = request().withCapabilities(new ModelCapabilities().withReasoningEffort(true)).withTools(List.of(tool()))
+            .withSystem(List.of(new SystemBlock().withText("one"), new SystemBlock().withText("two")))
+            .withMessages(List.of(ModelMessage.user("hi"), new ModelMessage().withRole(ModelMessage.Role.ASSISTANT)
+               .withPart(ModelPart.toolUse("a", "lookup", Map.of("q", "a"))).withPart(ModelPart.toolUse("b", "lookup", Map.of("q", "b"))),
+               new ModelMessage().withRole(ModelMessage.Role.USER).withPart(ModelPart.toolResult("a", "first", false)).withPart(ModelPart.toolResult("b", "second", true))));
+         var provider = new OpenAiCompatibleModelProvider(settings(server, kind));
+         StringBuilder text = new StringBuilder();
+         assertThat(provider.stream(request, text::append).await(Duration.ofSeconds(5)).getText()).isEqualTo("OK");
+         assertThat(text.toString()).isEqualTo("OK");
+         var captured = server.requests.getFirst();
+         JsonNode body = OpenAiHttp.JSON.readTree(captured.body());
+         assertThat(body.path("messages").get(0).path("content").asText()).isEqualTo("one\n\ntwo");
+         assertThat(body.path("messages").get(2).path("tool_calls").get(0).path("function").path("arguments").asText()).isEqualTo("{\"q\":\"a\"}");
+         assertThat(body.path("messages").get(3).path("tool_call_id").asText()).isEqualTo("a");
+         assertThat(body.path("messages").get(4).path("content").asText()).isEqualTo("ERROR: second");
+         assertThat(body.path("tools").get(0).path("function").has("strict")).isEqualTo(nativeKind);
+         assertThat(body.has("max_completion_tokens")).isEqualTo(nativeKind);
+         assertThat(body.has("max_tokens")).isEqualTo(!nativeKind);
+         assertThat(body.path("reasoning_effort").asText()).isEqualTo("high");
+         assertThat(body.has("tool_choice")).isFalse();
+         assertThat(body.has("parallel_tool_calls")).isEqualTo(List.of("OPENAI", "AZURE_OPENAI", "OPENROUTER", "VLLM").contains(kind));
+         assertThat(provider.countTokens(request)).isNull();
+         if(kind.equals("AZURE_OPENAI"))
+         {
+            assertThat(captured.path()).isEqualTo("/v1/openai/deployments/test/chat/completions?api-version=2024-10-21");
+            assertThat(captured.apiKey()).isEqualTo("synthetic-key");
+            assertThat(captured.authorization()).isNull();
+         }
+         else
+         {
+            assertThat(captured.authorization()).isEqualTo("Bearer synthetic-key");
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** An image part switches that user message to the content-part array (text
+    ** then image_url with a data URL); messages without images stay strings.
+    *******************************************************************************/
+   @Test
+   void imagePartsUseContentArray() throws Exception
+   {
+      try(MockOpenAiServer server = new MockOpenAiServer())
+      {
+         server.enqueue(200, TEXT);
+         ModelRequest request = request().withMessages(List.of(ModelMessage.user("first"), ModelMessage.assistant("ok"),
+            new ModelMessage().withRole(ModelMessage.Role.USER).withPart(ModelPart.text("<uploaded_file/>"))
+               .withPart(ModelPart.image("image/png", "iVBORw0KGgo=")).withPart(ModelPart.text("What is this?"))));
+         var provider = new OpenAiCompatibleModelProvider(settings(server, "OPENAI"));
+         assertThat(provider.stream(request, text -> {}).await(Duration.ofSeconds(5)).getText()).isEqualTo("OK");
+         JsonNode body = OpenAiHttp.JSON.readTree(server.requests.getFirst().body());
+         assertThat(body.path("messages").get(0).path("content").isTextual()).isTrue();
+         JsonNode content = body.path("messages").get(2).path("content");
+         assertThat(content.isArray()).isTrue();
+         assertThat(content.get(0).path("type").asText()).isEqualTo("text");
+         assertThat(content.get(0).path("text").asText()).isEqualTo("<uploaded_file/>");
+         assertThat(content.get(1).path("type").asText()).isEqualTo("image_url");
+         assertThat(content.get(1).path("image_url").path("url").asText()).isEqualTo("data:image/png;base64,iVBORw0KGgo=");
+         assertThat(content.get(2).path("text").asText()).isEqualTo("What is this?");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Fragmented parallel tools, comments, cache usage and ignored reasoning.
+    *******************************************************************************/
+   @Test
+   void streamedToolsAndUsage() throws Exception
+   {
+      try(MockOpenAiServer server = new MockOpenAiServer())
+      {
+         StringBuilder script = new StringBuilder(": comment\r\n\r\n");
+         script.append(event(Map.of("choices", List.of(Map.of("delta", Map.of("reasoning_content", "never expose", "tool_calls", List.of(
+            Map.of("index", 1, "id", "b", "function", Map.of("name", "lookup", "arguments", "")),
+            Map.of("index", 0, "id", "a", "function", Map.of("name", "lookup", "arguments", "")))))))));
+         for(char c : "{\"q\":\"value\"}".toCharArray())
+         {
+            script.append(event(Map.of("choices", List.of(Map.of("delta", Map.of("tool_calls", List.of(
+               Map.of("index", 0, "function", Map.of("arguments", String.valueOf(c))), Map.of("index", 1, "function", Map.of("arguments", String.valueOf(c))))))))));
+         }
+         script.append(event(Map.of("choices", List.of(Map.of("delta", Map.of(), "finish_reason", "tool_calls")), "usage",
+            Map.of("prompt_tokens", 100, "completion_tokens", 8, "prompt_tokens_details", Map.of("cached_tokens", 70)))));
+         server.enqueue(200, script + "data: [DONE]\n\n");
+         List<String> starts = new ArrayList<>();
+         StringBuilder text = new StringBuilder();
+         ModelResponse response = new OpenAiCompatibleModelProvider(settings(server, "OLLAMA").withApiKey(null)).stream(request(), new ModelEventListener()
+         {
+
+
+
+            /*******************************************************************************
+             ** Provider contract.
+             *******************************************************************************/
+            @Override
+            public void onTextDelta(String delta)
+            {
+               text.append(delta);
+            }
+
+
+
+            /*******************************************************************************
+             ** Provider contract.
+             *******************************************************************************/
+            @Override
+            public void onToolUseStart(String id, String name)
+            {
+               starts.add(id);
+            }
+         }).await(Duration.ofSeconds(5));
+         assertThat(response.getToolUses()).extracting(ModelPart::getToolUseId).containsExactly("a", "b");
+         assertThat(response.getToolUses().getFirst().getInput()).containsEntry("q", "value");
+         assertThat(starts).containsExactly("b", "a");
+         assertThat(text).isEmpty();
+         assertThat(response.getUsage().getInputTokens()).isEqualTo(30L);
+         assertThat(response.getUsage().getCacheReadTokens()).isEqualTo(70L);
+         assertThat(response.getUsage().getOutputTokens()).isEqualTo(8L);
+         assertThat(response.getStopReason()).isEqualTo(ModelResponse.STOP_TOOL_USE);
+         assertThat(server.requests.getFirst().authorization()).isNull();
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Single JSON mode and defaults without optional request fields.
+    *******************************************************************************/
+   @Test
+   void nonStreamingAndNoUsage() throws Exception
+   {
+      try(MockOpenAiServer server = new MockOpenAiServer())
+      {
+         server.enqueue(200, "{\"choices\":[{\"message\":{\"content\":\"done\"},\"finish_reason\":\"length\"}]}");
+         var provider = new OpenAiCompatibleModelProvider(settings(server, "OPENAI"));
+         StringBuilder text = new StringBuilder();
+         ModelResponse response = provider.stream(request().withCapabilities(new ModelCapabilities().withStreaming(false)), text::append).await(Duration.ofSeconds(5));
+         assertThat(response.getStopReason()).isEqualTo(ModelResponse.STOP_MAX_TOKENS);
+         assertThat(text.toString()).isEqualTo("done");
+         assertThat(response.getUsage().billableTokens()).isZero();
+         JsonNode body = OpenAiHttp.JSON.readTree(server.requests.getFirst().body());
+         assertThat(body.path("stream").asBoolean()).isFalse();
+         assertThat(body.has("stream_options")).isFalse();
+         assertThat(body.has("reasoning_effort")).isFalse();
+         assertThat(body.has("parallel_tool_calls")).isFalse();
+         server.enqueue(200, TEXT);
+         assertThat(provider.stream(request(), text::append).await(Duration.ofSeconds(5)).getUsage().billableTokens()).isZero();
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Every HTTP error category carries safe details.
+    *******************************************************************************/
+   @ParameterizedTest
+   @CsvSource({ "401,AUTHENTICATION", "403,AUTHENTICATION", "429,RATE_LIMITED", "503,OVERLOADED", "529,OVERLOADED", "400,INVALID_REQUEST", "404,INVALID_REQUEST", "422,INVALID_REQUEST", "500,SERVER", "502,SERVER" })
+   void errors(int status, String kind) throws Exception
+   {
+      try(MockOpenAiServer server = new MockOpenAiServer())
+      {
+         server.enqueue(status, "{\"error\":{\"type\":\"bad_request\",\"message\":\"Rejected synthetic-key\"}}");
+         assertThatThrownBy(() -> new OpenAiCompatibleModelProvider(settings(server, "OPENAI")).stream(request(), t -> {}).await(Duration.ofSeconds(5)))
+            .isInstanceOfSatisfying(ModelProviderException.class, e ->
+            {
+               assertThat(e.getKind().name()).isEqualTo(kind);
+               assertThat(e.getHttpStatus()).isEqualTo(status);
+               assertThat(e.getRequestId()).isEqualTo("mock-request");
+               assertThat(e.getMessage()).doesNotContain("synthetic-key");
+               assertThat(e.getProviderMessage()).contains("[redacted]");
+            });
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Strict rejection is opt-in; incompatible nested object schemas are omitted.
+    *******************************************************************************/
+   @Test
+   void strictAndStreamErrors() throws Exception
+   {
+      try(MockOpenAiServer server = new MockOpenAiServer())
+      {
+         var provider = new OpenAiCompatibleModelProvider(settings(server, "OPENAI"));
+         String error = "{\"error\":{\"type\":\"invalid_request_error\",\"message\":\"strict schema grammar refused\"}}";
+         for(boolean sse : List.of(false, true))
+         {
+            server.enqueue(sse ? 200 : 400, sse ? "data: " + error + "\n\n" : error);
+            assertThatThrownBy(() -> provider.stream(request().withTools(List.of(tool())), t -> {}).await(Duration.ofSeconds(5)))
+               .isInstanceOfSatisfying(ModelProviderException.class, e -> assertThat(e.isStrictSchemaRejected()).isTrue());
+         }
+         server.enqueue(200, TEXT);
+         provider.stream(request().withTools(List.of(tool().withInputSchema(Map.of("type", "object", "properties", Map.of())))), t -> {}).await(Duration.ofSeconds(5));
+         assertThat(OpenAiHttp.JSON.readTree(server.requests.getLast().body()).path("tools").get(0).path("function").has("strict")).isFalse();
+         assertThat(OpenAiMapping.strictCompatible(OpenAiHttp.JSON.readTree("{\"type\":\"array\",\"items\":{\"type\":\"object\"}}"))).isFalse();
+         assertThat(OpenAiMapping.strictCompatible(OpenAiHttp.JSON.readTree("{\"anyOf\":[{\"type\":\"object\"}]}"))).isFalse();
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Header timeout, stalled body timeout, cancellation and network failure.
+    *******************************************************************************/
+   @Test
+   void timeoutCancelAndNetwork() throws Exception
+   {
+      try(MockOpenAiServer server = new MockOpenAiServer())
+      {
+         var provider = new OpenAiCompatibleModelProvider(settings(server, "OLLAMA").withRequestTimeoutSeconds(1));
+         for(boolean afterHeaders : List.of(false, true))
+         {
+            server.stall(afterHeaders);
+            assertThatThrownBy(() -> provider.stream(request(), t -> {}).await(Duration.ofSeconds(5)))
+               .isInstanceOfSatisfying(ModelProviderException.class, e -> assertThat(e.getKind()).isEqualTo(ModelProviderException.Kind.TIMEOUT));
+         }
+         var started = server.stall(true);
+         var handle = provider.stream(request(), t -> {});
+         assertThat(started.await(3, java.util.concurrent.TimeUnit.SECONDS)).isTrue();
+         handle.cancel();
+         assertThat(handle.await(Duration.ofSeconds(2)).getStopReason()).isEqualTo(ModelResponse.STOP_CANCELLED);
+         assertThat(handle.isCancelled()).isTrue();
+      }
+      String closed;
+      try(MockOpenAiServer server = new MockOpenAiServer())
+      {
+         closed = server.url();
+      }
+      var provider = new OpenAiCompatibleModelProvider(new ProviderSettings().withKind("OLLAMA").withBaseUrl(closed));
+      assertThatThrownBy(() -> provider.stream(request(), t -> {}).await(Duration.ofSeconds(5)))
+         .isInstanceOfSatisfying(ModelProviderException.class, e -> assertThat(e.getKind()).isEqualTo(ModelProviderException.Kind.NETWORK));
+   }
+
+
+
+   /*******************************************************************************
+    ** Discovery timeouts include the body, and failed probes never complete.
+    *******************************************************************************/
+   @Test
+   void discoveryTimeoutAndMalformedResponse() throws Exception
+   {
+      try(MockOpenAiServer server = new MockOpenAiServer())
+      {
+         var type = new OpenAiCompatibleProviderType();
+         var settings = settings(server, "OLLAMA").withRequestTimeoutSeconds(1);
+         server.stall(true);
+         assertThatThrownBy(() -> type.discoverModels(settings)).isInstanceOfSatisfying(ModelProviderException.class,
+            e -> assertThat(e.getKind()).isEqualTo(ModelProviderException.Kind.TIMEOUT));
+         server.enqueue(200, "not JSON");
+         assertThat(type.checkHealth(settings).healthy()).isFalse();
+         server.enqueue(200, "{\"error\":{\"message\":\"failed\"}}");
+         assertThat(type.checkHealth(settings).healthy()).isFalse();
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** JDK header validation must never expose even an invalid credential.
+    *******************************************************************************/
+   @Test
+   void invalidHeaderDoesNotLeakKey() throws Exception
+   {
+      try(MockOpenAiServer server = new MockOpenAiServer())
+      {
+         var settings = settings(server, "OPENAI").withApiKey("private\ncredential");
+         assertThatThrownBy(() -> new OpenAiCompatibleProviderType().discoverModels(settings))
+            .isInstanceOfSatisfying(ModelProviderException.class, e ->
+            {
+               assertThat(e.getMessage()).doesNotContain("private", "credential");
+               assertThat(e.getCause()).isNull();
+            });
+         assertThat(new OpenAiCompatibleProviderType().checkHealth(settings).healthy()).isFalse();
+         assertThat(server.requests).isEmpty();
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Non-streaming calls preserve tools and usage, including cached tokens.
+    *******************************************************************************/
+   @Test
+   void nonStreamingTools() throws Exception
+   {
+      try(MockOpenAiServer server = new MockOpenAiServer())
+      {
+         server.enqueue(200, """
+            {"choices":[{"message":{"tool_calls":[
+               {"id":"one","function":{"name":"lookup","arguments":"{\\"q\\":\\"x\\"}"}},
+               {"id":"two","function":{"name":"lookup","arguments":"{}"}}]},"finish_reason":"tool_calls"}],
+               "usage":{"prompt_tokens":12,"completion_tokens":4,"prompt_tokens_details":{"cached_tokens":2}}}
+            """);
+         var response = new OpenAiCompatibleModelProvider(settings(server, "OPENAI")).stream(
+            request().withCapabilities(new ModelCapabilities().withStreaming(false)), t -> {}).await(Duration.ofSeconds(5));
+         assertThat(response.getToolUses()).extracting(ModelPart::getToolUseId).containsExactly("one", "two");
+         assertThat(response.getToolUses().getFirst().getInput()).containsEntry("q", "x");
+         assertThat(response.getUsage().getInputTokens()).isEqualTo(10L);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Model discovery context dialects, Azure path and health without completions.
+    *******************************************************************************/
+   @ParameterizedTest
+   @ValueSource(strings = { "OPENAI", "OPENROUTER", "AZURE_OPENAI", "VLLM", "LLAMA_CPP" })
+   void discoveryAndHealth(String kind) throws Exception
+   {
+      try(MockOpenAiServer server = new MockOpenAiServer())
+      {
+         String models = "{\"data\":[{\"id\":\"a\",\"owned_by\":\"owner\",\"context_length\":64000},{\"id\":\"b\",\"max_model_len\":32000},{\"id\":\"c\",\"meta\":{\"n_ctx_train\":16000}}]}";
+         server.enqueue(200, models);
+         var type = new OpenAiCompatibleProviderType();
+         var settings = settings(server, kind).withApiVersion("2024-10-21");
+         assertThat(type.discoverModels(settings)).extracting(m -> m.contextWindowTokens()).containsExactly(64000, 32000, 16000);
+         server.enqueue(200, models);
+         assertThat(type.checkHealth(settings).message()).isEqualTo("3 models available");
+         server.enqueue(401, "{\"error\":{\"message\":\"bad key\"}}");
+         assertThat(type.checkHealth(settings).healthy()).isFalse();
+         assertThat(server.requests).allSatisfy(r -> assertThat(r.path()).isEqualTo(kind.equals("AZURE_OPENAI") ? "/v1/openai/models?api-version=2024-10-21" : "/v1/models"));
+         assertThat(type.getKinds()).hasSize(8);
+         assertThat(type.getModels()).isEmpty();
+         assertThat(type.getDefaultBaseUrl()).isNull();
+         assertThat(type.getDefaultApiKeyEnvName()).isNull();
+         assertThat(type.getLabel()).isEqualTo("OpenAI-compatible");
+         for(String k : type.getKinds())
+         {
+            assertThat(type.getDefaultLocation(k)).isIn("LOCAL", "CLOUD");
+            type.getDefaultBaseUrl(k);
+            type.getDefaultApiKeyEnvName(k);
+         }
+         assertThat(type.create(null, server.url()).getName()).isEqualTo(type.getType());
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Serialize a scripted SSE event.
+    *******************************************************************************/
+   static String event(Object value) throws Exception
+   {
+      return ("data: " + OpenAiHttp.JSON.writeValueAsString(value) + "\n\n");
+   }
+
+   /*******************************************************************************
+    ** Repeated identities, missing ids and older servers' stop reason are tolerated.
+    *******************************************************************************/
+   @Test
+   void repeatedToolIdentityAndMissingId() throws Exception
+   {
+      try(MockOpenAiServer server = new MockOpenAiServer())
+      {
+         StringBuilder script = new StringBuilder();
+         for(String fragment : List.of("{", "\"q\":", "\"hello\"}"))
+         {
+            script.append(event(Map.of("choices", List.of(Map.of("delta", Map.of("tool_calls", List.of(
+               Map.of("index", 0, "id", "repeated", "function", Map.of("name", "lookup", "arguments", fragment)),
+               Map.of("index", 1, "function", Map.of("name", "lookup", "arguments", fragment)))), "finish_reason", "stop")))));
+         }
+         server.enqueue(200, script.toString());
+         ModelResponse response = new OpenAiCompatibleModelProvider(settings(server, "OLLAMA")).stream(request(), t -> {}).await(Duration.ofSeconds(5));
+         assertThat(response.getStopReason()).isEqualTo(ModelResponse.STOP_TOOL_USE);
+         assertThat(response.getToolUses()).extracting(ModelPart::getToolUseId).containsExactly("repeated", "call_1");
+         assertThat(response.getToolUses()).allSatisfy(tool ->
+         {
+            assertThat(tool.getToolName()).isEqualTo("lookup");
+            assertThat(tool.getInput()).containsExactlyEntriesOf(Map.of("q", "hello"));
+         });
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Invalid JSON becomes bounded input for kernel validation, never NETWORK.
+    *******************************************************************************/
+   @ParameterizedTest
+   @ValueSource(strings = { "{broken", "null", "[]", "{} trailing", "long" })
+   void malformedArguments(String input) throws Exception
+   {
+      String arguments = input.equals("long") ? "x".repeat(250) : input;
+      try(MockOpenAiServer server = new MockOpenAiServer())
+      {
+         server.enqueue(200, event(Map.of("choices", List.of(Map.of("delta", Map.of("tool_calls", List.of(
+            Map.of("index", 0, "function", Map.of("name", "lookup", "arguments", arguments)))), "finish_reason", "stop")))));
+         ModelResponse response = new OpenAiCompatibleModelProvider(settings(server, "LLAMA_CPP")).stream(request(), t -> {}).await(Duration.ofSeconds(5));
+         assertThat(response.getStopReason()).isEqualTo(ModelResponse.STOP_TOOL_USE);
+         assertThat(response.getToolUses().getFirst().getInput()).containsExactlyEntriesOf(Map.of("_invalid_arguments", arguments.substring(0, Math.min(200, arguments.length()))));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Supplier tokens take precedence over static keys and refresh per request.
+    *******************************************************************************/
+   @Test
+   void bearerSupplierPrecedenceAndRedaction() throws Exception
+   {
+      try(MockOpenAiServer server = new MockOpenAiServer())
+      {
+         var token = new java.util.concurrent.atomic.AtomicReference<>("first-private-token");
+         ProviderSettings settings = settings(server, "VERTEX").withBearerTokenSupplier(token::get);
+         var provider = new OpenAiCompatibleModelProvider(settings);
+         server.enqueue(200, TEXT);
+         provider.stream(request(), delta -> {}).await(Duration.ofSeconds(5));
+         assertThat(server.requests.getFirst().authorization()).isEqualTo("Bearer first-private-token");
+         token.set("next-private-token");
+         server.enqueue(403, "{\"error\":{\"type\":\"next-private-token\",\"message\":\"next-private-token\"}}");
+         assertThatThrownBy(() -> provider.stream(request(), delta -> {}).await(Duration.ofSeconds(5)))
+            .isInstanceOfSatisfying(ModelProviderException.class, error ->
+            {
+               assertThat(error.getKind()).isEqualTo(ModelProviderException.Kind.AUTHENTICATION);
+               assertThat(error.getProviderMessage()).isNull();
+               assertThat(error.getProviderErrorType()).isNull();
+               assertThat(error.toString()).doesNotContain("private-token");
+            });
+         assertThat(server.requests.get(1).authorization()).isEqualTo("Bearer next-private-token");
+         assertThat(settings.toString()).doesNotContain("private-token");
+         assertThat(OpenAiHttp.JSON.writeValueAsString(settings)).doesNotContain("bearerTokenSupplier", "private-token");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Missing or failed dynamic credentials never fall back to a static secret.
+    *******************************************************************************/
+   @Test
+   void unavailableBearerSupplier() throws Exception
+   {
+      try(MockOpenAiServer server = new MockOpenAiServer())
+      {
+         ProviderSettings settings = settings(server, "VERTEX");
+         for(String value : java.util.Arrays.asList(null, "", " "))
+         {
+            settings.setBearerTokenSupplier(() -> value);
+            var provider = new OpenAiCompatibleModelProvider(settings);
+            assertThatThrownBy(() -> provider.stream(request(), delta -> {}).await(Duration.ofSeconds(5)))
+               .isInstanceOfSatisfying(ModelProviderException.class, error -> assertThat(error.getKind()).isEqualTo(ModelProviderException.Kind.AUTHENTICATION));
+         }
+         settings.withBearerTokenSupplier(() ->
+         {
+            throw (new IllegalStateException("private-token"));
+         });
+         var provider = new OpenAiCompatibleModelProvider(settings);
+         assertThatThrownBy(() -> provider.stream(request(), delta -> {}).await(Duration.ofSeconds(5)))
+            .isInstanceOfSatisfying(ModelProviderException.class, error ->
+            {
+               assertThat(error.getKind()).isEqualTo(ModelProviderException.Kind.AUTHENTICATION);
+               assertThat(error.toString()).doesNotContain("private-token");
+               assertThat(error.getCause()).isNull();
+            });
+         assertThat(server.requests).isEmpty();
+      }
+   }
+}

qbit-assistant-provider-openai/src/test/java/com/kingsrook/qbits/assistant/provider/openai/OpenAiEmbeddingTest.java

@@ -0,0 +1,133 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.provider.openai;
+
+
+import java.util.List;
+import com.kingsrook.qbits.assistant.spi.EmbeddingRequest;
+import com.kingsrook.qbits.assistant.spi.ModelProviderException;
+import com.kingsrook.qbits.assistant.spi.ProviderSettings;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+
+/*******************************************************************************
+ ** Embedding wire contracts through the same local HTTP harness as chat.
+ *******************************************************************************/
+class OpenAiEmbeddingTest
+{
+   /*******************************************************************************
+    ** Input arrays, response indexes, usage and authentication are preserved.
+    *******************************************************************************/
+   @Test
+   void shapeOrderAndAzure() throws Exception
+   {
+      for(String kind : List.of("OPENAI", "AZURE_OPENAI", "OLLAMA"))
+      {
+         try(MockOpenAiServer server = new MockOpenAiServer())
+         {
+            server.enqueue(200, "{\"data\":[{\"index\":1,\"embedding\":[0,1]},{\"index\":0,\"embedding\":[1,0]}],\"usage\":{\"prompt_tokens\":7}}");
+            var provider = new OpenAiCompatibleModelProvider(new ProviderSettings().withKind(kind).withBaseUrl(server.url()).withApiKey("synthetic-key").withApiVersion("2024-10-21"));
+            var response = provider.embed(new EmbeddingRequest("bge-m3", List.of("first", "second")));
+            assertThat(response.vectors()).hasSize(2);
+            assertThat(response.vectors().getFirst()).containsExactly(1, 0);
+            assertThat(response.usage().getInputTokens()).isEqualTo(7L);
+            var captured = server.requests.getFirst();
+            assertThat(captured.path()).isEqualTo(kind.equals("AZURE_OPENAI") ? "/v1/openai/deployments/bge-m3/embeddings?api-version=2024-10-21" : "/v1/embeddings");
+            var body = OpenAiHttp.JSON.readTree(captured.body());
+            assertThat(body.path("model").asText()).isEqualTo("bge-m3");
+            assertThat(body.path("input").size()).isEqualTo(2);
+            assertThat(body.has("messages")).isFalse();
+            assertThat(body.has("stream")).isFalse();
+            assertThat(kind.equals("AZURE_OPENAI") ? captured.apiKey() : captured.authorization()).contains("synthetic-key");
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Reuse chat's safe error categories, without echoing credentials.
+    *******************************************************************************/
+   @Test
+   void errorsAndMalformedVectors() throws Exception
+   {
+      try(MockOpenAiServer server = new MockOpenAiServer())
+      {
+         var provider = new OpenAiCompatibleModelProvider(new ProviderSettings().withKind("OPENAI").withBaseUrl(server.url()).withApiKey("synthetic-key"));
+         server.enqueue(429, "{\"error\":{\"message\":\"synthetic-key rejected\"}}");
+         assertThatThrownBy(() -> provider.embed(new EmbeddingRequest("embed", List.of("text"))))
+            .isInstanceOfSatisfying(ModelProviderException.class, e ->
+            {
+               assertThat(e.getKind()).isEqualTo(ModelProviderException.Kind.RATE_LIMITED);
+               assertThat(e.getMessage()).doesNotContain("synthetic-key");
+            });
+         for(String body : List.of("{}", "{\"data\":[{\"index\":0,\"embedding\":[\"not numeric\"]}]}",
+            "{\"data\":[{\"index\":2,\"embedding\":[1]}]}", "{\"data\":[{\"index\":0,\"embedding\":[1]},{\"index\":0,\"embedding\":[1]}]}"))
+         {
+            server.enqueue(200, body);
+            assertThatThrownBy(() -> provider.embed(new EmbeddingRequest("embed", List.of("text")))).isInstanceOf(ModelProviderException.class);
+         }
+         assertThatThrownBy(() -> new EmbeddingRequest("embed", java.util.Collections.nCopies(65, "text"))).isInstanceOf(IllegalArgumentException.class);
+         assertThatThrownBy(() -> new EmbeddingRequest("embed", List.of())).isInstanceOf(IllegalArgumentException.class);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Deadline covers a stalled response body, not only HTTP headers.
+    *******************************************************************************/
+   @Test
+   void bodyTimeout() throws Exception
+   {
+      try(MockOpenAiServer server = new MockOpenAiServer())
+      {
+         server.stall(true);
+         var provider = new OpenAiCompatibleModelProvider(new ProviderSettings().withKind("OLLAMA").withBaseUrl(server.url()).withRequestTimeoutSeconds(1));
+         assertThatThrownBy(() -> provider.embed(new EmbeddingRequest("embed", List.of("text"))))
+            .isInstanceOfSatisfying(ModelProviderException.class, e -> assertThat(e.getKind()).isEqualTo(ModelProviderException.Kind.TIMEOUT));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The transport accepts a complete 64-input batch and rejects overflow
+    ** before sending. EmbeddingService owns splitting larger indexing jobs.
+    *******************************************************************************/
+   @Test
+   void maximumBatch() throws Exception
+   {
+      try(MockOpenAiServer server = new MockOpenAiServer())
+      {
+         var body = OpenAiHttp.JSON.createObjectNode();
+         var data = body.putArray("data");
+         for(Integer i = 0; i < 64; i++)
+         {
+            data.addObject().put("index", i).putArray("embedding").add(1).add(0);
+         }
+         server.enqueue(200, body.toString());
+         var provider = new OpenAiCompatibleModelProvider(new ProviderSettings().withKind("OLLAMA").withBaseUrl(server.url()));
+         assertThat(provider.embed(new EmbeddingRequest("embed", java.util.Collections.nCopies(64, "text"))).vectors()).hasSize(64);
+         assertThat(OpenAiHttp.JSON.readTree(server.requests.getFirst().body()).path("input").size()).isEqualTo(64);
+         assertThatThrownBy(() -> provider.embed(new EmbeddingRequest("embed", java.util.Collections.nCopies(65, "text")))).isInstanceOf(IllegalArgumentException.class);
+         assertThat(server.requests).hasSize(1);
+      }
+   }
+}

qbit-assistant-provider-openai/src/test/java/com/kingsrook/qbits/assistant/provider/openai/OpenAiGoldenTurnTest.java

@@ -0,0 +1,87 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.provider.openai;
+
+
+import java.util.List;
+import java.util.Map;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.kingsrook.qbits.assistant.AssistantQBitConfig;
+import com.kingsrook.qbits.assistant.testing.AssistantTestFixture;
+import com.kingsrook.qbits.assistant.testing.GoldenTasks;
+import com.kingsrook.qbits.assistant.testing.TurnRunner;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import org.junit.jupiter.api.Tag;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** Golden fixture task through the real adapter, engine and tool result mapping.
+ *******************************************************************************/
+@Tag("golden")
+class OpenAiGoldenTurnTest
+{
+   /*******************************************************************************
+    ** A golden task travels through the engine, real UI tools and a tool round trip.
+    *******************************************************************************/
+   @Test
+   void goldenToolRoundTrip() throws Exception
+   {
+      try(MockOpenAiServer server = new MockOpenAiServer())
+      {
+         Map<String, Object> arguments = Map.of("table", "blog_post", "filter", Map.of("booleanOperator", "AND", "criteria",
+            List.of(Map.of("field", "status", "operator", "EQUALS", "values", List.of("PUBLISHED")))));
+         Map<String, Object> call = Map.of("index", 0, "id", "count", "function", Map.of("name", "count_records", "arguments", OpenAiHttp.JSON.writeValueAsString(arguments)));
+         server.enqueue(200, OpenAiContractTest.event(Map.of("choices", List.of(Map.of("delta", Map.of("tool_calls", List.of(call)), "finish_reason", "stop")))));
+         server.enqueue(200, OpenAiContractTest.event(Map.of("choices", List.of(Map.of("delta", Map.of("content", "There are " + AssistantTestFixture.PUBLISHED_POSTS + " published posts. /app/blog_post"), "finish_reason", "stop")))));
+         var provider = new OpenAiCompatibleModelProvider(OpenAiContractTest.settings(server, "OLLAMA"));
+         var config = new AssistantQBitConfig().withProviderName(provider.getName()).withModelProvider(provider);
+         try
+         {
+            var instance = AssistantTestFixture.build(config);
+            var task = GoldenTasks.all().stream().filter(t -> t.id().equals("count-published-posts")).findFirst().orElseThrow();
+            var outcome = new TurnRunner(instance, config).run(task.userId(), task.prompt());
+            assertThat(outcome.errorCode()).isNull();
+            task.check().accept(outcome);
+            assertThat(outcome.text()).isEqualTo("There are " + AssistantTestFixture.PUBLISHED_POSTS + " published posts. /app/blog_post");
+            assertThat(outcome.end()).isNotEmpty();
+            assertThat(server.requests).hasSize(2);
+            JsonNode messages = OpenAiHttp.JSON.readTree(server.requests.get(1).body()).path("messages");
+            JsonNode assistant = messages.get(messages.size() - 2);
+            assertThat(assistant.path("role").asText()).isEqualTo("assistant");
+            assertThat(assistant.path("tool_calls")).hasSize(1);
+            assertThat(assistant.path("tool_calls").get(0).path("id").asText()).isEqualTo("count");
+            assertThat(assistant.path("tool_calls").get(0).path("function").path("name").asText()).isEqualTo("count_records");
+            assertThat(messages.get(messages.size() - 1).path("content").asText()).contains("count").doesNotStartWith("ERROR:");
+            assertThat(messages.get(messages.size() - 1).path("role").asText()).isEqualTo("tool");
+            assertThat(messages.get(messages.size() - 1).path("tool_call_id").asText()).isEqualTo("count");
+         }
+         finally
+         {
+            if(config.getRuntime() != null)
+            {
+               config.getRuntime().close();
+            }
+            QContext.clear();
+         }
+      }
+   }
+
+
+
+}

qbit-assistant-provider-openai/src/test/java/com/kingsrook/qbits/assistant/provider/openai/OpenAiTlsTest.java

@@ -0,0 +1,216 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.provider.openai;
+
+
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.security.KeyStore;
+import java.time.Duration;
+import java.util.Set;
+import com.kingsrook.qbits.assistant.AssistantQBitConfig;
+import com.kingsrook.qbits.assistant.model.AssistantProvider;
+import com.kingsrook.qbits.assistant.spi.ModelProviderException;
+import com.kingsrook.qbits.assistant.spi.ProviderSettings;
+import com.kingsrook.qbits.assistant.testing.AssistantTestFixture;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import javax.net.ssl.KeyManagerFactory;
+import javax.net.ssl.SSLContext;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+
+/*******************************************************************************
+ ** Private CA coverage against loopback HTTPS; all key material is test-only.
+ *******************************************************************************/
+class OpenAiTlsTest
+{
+   @TempDir
+   Path temporary;
+
+
+
+   /*******************************************************************************
+    ** The public test root, never a real deployment CA.
+    *******************************************************************************/
+   private String pem() throws Exception
+   {
+      try(InputStream input = getClass().getResourceAsStream("/tls/ca.pem"))
+      {
+         return (new String(input.readAllBytes(), StandardCharsets.US_ASCII));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Leaf chain signed by the test root, valid for localhost but not its IP.
+    *******************************************************************************/
+   private SSLContext serverContext() throws Exception
+   {
+      KeyStore store = KeyStore.getInstance("PKCS12");
+      try(InputStream input = getClass().getResourceAsStream("/tls/server.p12"))
+      {
+         store.load(input, "test-only".toCharArray());
+      }
+      KeyManagerFactory keys = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());
+      keys.init(store, "test-only".toCharArray());
+      SSLContext context = SSLContext.getInstance("TLS");
+      context.init(keys.getKeyManagers(), null, null);
+      return (context);
+   }
+
+
+
+   /*******************************************************************************
+    ** Every operation rejects the unknown CA with a safe, actionable diagnostic.
+    *******************************************************************************/
+   @Test
+   void untrustedCertificate() throws Exception
+   {
+      try(MockOpenAiServer server = new MockOpenAiServer(serverContext()))
+      {
+         ProviderSettings settings = OpenAiContractTest.settings(server, "OLLAMA");
+         var type = new OpenAiCompatibleProviderType();
+         assertThatThrownBy(() -> type.discoverModels(settings)).isInstanceOfSatisfying(ModelProviderException.class, this::trustError);
+         assertThat(type.checkHealth(settings).healthy()).isFalse();
+         assertThat(type.checkHealth(settings).message()).contains("NETWORK", "tlsCaBundle");
+         assertThatThrownBy(() -> type.create(settings).stream(OpenAiContractTest.request(), t -> {}).await(Duration.ofSeconds(5)))
+            .isInstanceOfSatisfying(ModelProviderException.class, this::trustError);
+         assertThat(server.requests).isEmpty();
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** No raw handshake details, keys, or certificate contents escape.
+    *******************************************************************************/
+   private void trustError(ModelProviderException error)
+   {
+      assertThat(error.getKind()).isEqualTo(ModelProviderException.Kind.NETWORK);
+      assertThat(error.getMessage()).contains("certificate is not trusted", "tlsCaBundle").doesNotContain("synthetic-key", "TEST ONLY", "BEGIN CERTIFICATE");
+      assertThat(error.getCause()).isNull();
+   }
+
+
+
+   /*******************************************************************************
+    ** Shared trust enables all operations while endpoint identification stays on.
+    *******************************************************************************/
+   @Test
+   void trustedHealthDiscoveryChatAndHostnameCheck() throws Exception
+   {
+      var config = new AssistantQBitConfig().withTrustedCaBundle("test-root", pem());
+      try(MockOpenAiServer server = new MockOpenAiServer(serverContext()))
+      {
+         ProviderSettings settings = OpenAiContractTest.settings(server, "OLLAMA").withTlsCaBundle("test-root")
+            .withSslContext(config.getTrustedCaBundles().get("test-root"));
+         var type = new OpenAiCompatibleProviderType();
+         String models = "{\"data\":[{\"id\":\"test\"}]}";
+         server.enqueue(200, models);
+         assertThat(type.checkHealth(settings).healthy()).isTrue();
+         server.enqueue(200, models);
+         assertThat(type.discoverModels(settings)).extracting(m -> m.modelId()).containsExactly("test");
+         server.enqueue(200, OpenAiContractTest.TEXT);
+         assertThat(type.create(settings).stream(OpenAiContractTest.request(), t -> {}).await(Duration.ofSeconds(5)).getText()).isEqualTo("OK");
+         assertThat(server.requests).hasSize(3).allSatisfy(r -> assertThat(r.authorization()).isEqualTo("Bearer synthetic-key"));
+         settings.withBaseUrl(server.url().replace("localhost", "127.0.0.1"));
+         assertThatThrownBy(() -> type.discoverModels(settings)).isInstanceOfSatisfying(ModelProviderException.class, this::trustError);
+         assertThatThrownBy(() -> type.create(settings).stream(OpenAiContractTest.request(), t -> {}).await(Duration.ofSeconds(5)))
+            .isInstanceOfSatisfying(ModelProviderException.class, this::trustError);
+         assertThat(server.requests).hasSize(3);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Parse at startup, accept multiple PEMs, omit contexts from serialized beans.
+    *******************************************************************************/
+   @Test
+   void eagerConfigAndSerialization() throws Exception
+   {
+      String pem = pem();
+      Path file = temporary.resolve("bundle.pem");
+      Files.writeString(file, pem + pem);
+      var config = new AssistantQBitConfig().withTrustedCaBundleFile("test-root", file);
+      Files.delete(file);
+      assertThat(config.getTrustedCaBundles()).containsKey("test-root");
+      assertThatThrownBy(() -> config.getTrustedCaBundles().clear()).isInstanceOf(UnsupportedOperationException.class);
+      assertThat(OpenAiHttp.JSON.writeValueAsString(config)).doesNotContain("trustedCaBundles", "BEGIN CERTIFICATE", "test-root");
+      var settings = new ProviderSettings().withSslContext(config.getTrustedCaBundles().get("test-root"));
+      assertThat(OpenAiHttp.JSON.writeValueAsString(settings)).doesNotContain("sslContext", "BEGIN CERTIFICATE");
+      for(String invalid : new String[] { null, "", "private-content", pem + "private-content", "-----BEGIN CERTIFICATE-----bad-----END CERTIFICATE-----" })
+      {
+         assertThatThrownBy(() -> config.withTrustedCaBundle("bad", invalid)).isInstanceOf(IllegalArgumentException.class)
+            .hasMessageContaining("Invalid CA bundle").hasMessageNotContaining("private-content").hasNoCause();
+      }
+      assertThatThrownBy(() -> config.withTrustedCaBundle(" ", pem)).hasMessageContaining("CA bundle name");
+      assertThatThrownBy(() -> config.withTrustedCaBundleFile("missing", file)).hasMessage("Could not read the configured CA bundle file.").hasNoCause();
+   }
+
+
+
+   /*******************************************************************************
+    ** Settings saves reject unknown names and HTTP; changing names rebuilds clients.
+    *******************************************************************************/
+   @Test
+   void registryValidationAndClientCache() throws Exception
+   {
+      var config = new AssistantQBitConfig().withProviderType(new OpenAiCompatibleProviderType())
+         .withAllowedBaseUrls(Set.of("https://localhost:8443/v1"))
+         .withTrustedCaBundle("first", pem()).withTrustedCaBundle("second", pem());
+      try
+      {
+         var instance = AssistantTestFixture.build(config);
+         QContext.init(instance, AssistantTestFixture.sessionFor(AssistantTestFixture.ADMIN));
+         var service = config.getRuntime().getProviderService();
+         var row = new AssistantProvider().withName("Test TLS").withProviderType("openai-compatible").withKind("OLLAMA")
+            .withBaseUrl("https://localhost:8443/v1").withTlsCaBundle("unknown");
+         assertThat(service.validate(row)).anyMatch(e -> e.contains("configured on this server"));
+         assertThatThrownBy(() -> service.settings(row)).hasMessageContaining("TLS CA bundle");
+         assertThatThrownBy(() -> config.getRuntime().getStore().insert(row)).hasMessageContaining("TLS CA bundle");
+         row.withTlsCaBundle("first").withBaseUrl(null);
+         assertThat(service.validate(row)).anyMatch(e -> e.contains("HTTPS"));
+         row.withBaseUrl("https://localhost:8443/v1");
+         assertThat(service.validate(row)).isEmpty();
+         row.withId(config.getRuntime().getStore().insert(row).getId());
+         assertThat(row.getTlsCaBundle()).isEqualTo("first");
+         assertThat(service.settings(row).getSslContext()).isSameAs(config.getTrustedCaBundles().get("first"));
+         var first = service.forRow(row, "test").provider();
+         assertThat(service.forRow(row, "test").provider()).isSameAs(first);
+         row.withTlsCaBundle("second");
+         assertThat(service.forRow(row, "test").provider()).isNotSameAs(first);
+         row.withTlsCaBundle(null);
+         assertThat(service.settings(row).getSslContext()).isNull();
+         assertThat(instance.getTable(AssistantProvider.TABLE_NAME).getField("tlsCaBundle").getMaxLength()).isEqualTo(100);
+      }
+      finally
+      {
+         if(config.getRuntime() != null)
+         {
+            config.getRuntime().close();
+         }
+         QContext.clear();
+      }
+   }
+}

qbit-assistant-provider-openai/src/test/java/com/kingsrook/qbits/assistant/provider/openai/demo/OpenAiDemoServer.java

@@ -0,0 +1,335 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.provider.openai.demo;
+
+
+import java.io.IOException;
+import java.math.BigDecimal;
+import java.net.InetSocketAddress;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.kingsrook.qbits.assistant.AssistantQBitConfig;
+import com.kingsrook.qbits.assistant.metadata.AssistantMetaDataBuilder;
+import com.kingsrook.qbits.assistant.model.AssistantModel;
+import com.kingsrook.qbits.assistant.model.AssistantProvider;
+import com.kingsrook.qbits.assistant.persistence.AssistantStore;
+import com.kingsrook.qbits.assistant.processes.DiscoverModelsProcess;
+import com.kingsrook.qbits.assistant.processes.TestConnectionProcess;
+import com.kingsrook.qbits.assistant.processes.TestModelConnectionProcess;
+import com.kingsrook.qbits.assistant.provider.fake.ScriptedModelProvider;
+import com.kingsrook.qbits.assistant.provider.openai.OpenAiCompatibleProviderType;
+import com.kingsrook.qbits.assistant.spi.AssistantProviderType;
+import com.kingsrook.qbits.assistant.testing.AssistantTestFixture;
+import com.kingsrook.qbits.assistant.testing.EvalSupport;
+import com.kingsrook.qbits.assistant.testing.GoldenTasks;
+import com.kingsrook.qbits.assistant.testing.PresentationGoldenTask;
+import com.kingsrook.qbits.assistant.testing.TurnRunner;
+import com.kingsrook.qqq.backend.core.actions.processes.QProcessCallbackFactory;
+import com.kingsrook.qqq.backend.core.actions.processes.RunProcessAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.instances.AbstractQQQApplication;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessInput;
+import com.kingsrook.qqq.backend.core.model.metadata.QAuthenticationType;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.authentication.QAuthenticationMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.session.QSession;
+import com.kingsrook.qqq.backend.core.modules.authentication.QAuthenticationModuleCustomizerInterface;
+import com.kingsrook.qqq.middleware.javalin.QApplicationJavalinServer;
+import com.sun.net.httpserver.HttpExchange;
+import com.sun.net.httpserver.HttpServer;
+
+
+/*******************************************************************************
+ ** Memory-backed P-a screenshot demo. All discovery, tests and usage come from
+ ** real application calls to a localhost mock; no external credentials are used.
+ *******************************************************************************/
+public class OpenAiDemoServer extends AbstractQQQApplication
+{
+   private static final String ADMIN = "admin-demo";
+   private static final String MODEL = "qwen3:30b-a3b";
+   private static final String IMAGE_QUESTION = "How many images do I have by type?";
+   private static final ObjectMapper JSON = new ObjectMapper();
+   private static QInstance instance;
+
+
+
+   /*******************************************************************************
+    ** Give browser sessions the same admin identity used for demo traffic.
+    *******************************************************************************/
+   public static class DemoSessionCustomizer implements QAuthenticationModuleCustomizerInterface
+   {
+      /*******************************************************************************
+       **
+       *******************************************************************************/
+      @Override
+      public void customizeSession(QInstance qInstance, QSession qSession, Map<String, Object> context)
+      {
+         QSession admin = AssistantTestFixture.sessionFor(ADMIN);
+         qSession.setUser(admin.getUser());
+         qSession.setPermissions(admin.getPermissions());
+         qSession.withSecurityKeyValue(AssistantMetaDataBuilder.allAccessKeyName(AssistantQBitConfig.DEFAULT_OWNER_KEY_TYPE), true);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public QInstance defineQInstance() throws QException
+   {
+      return (instance);
+   }
+
+
+
+   /*******************************************************************************
+    ** Seed settings, execute the record actions and a turn, then serve Next UI.
+    *******************************************************************************/
+   public static void main(String[] args) throws Exception
+   {
+      int port = args.length > 0 ? Integer.parseInt(args[0]) : 8099;
+      HttpServer mock = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
+      mock.createContext("/", OpenAiDemoServer::serveMock);
+      mock.start();
+      Runtime.getRuntime().addShutdownHook(new Thread(() -> mock.stop(0)));
+      String baseUrl = "http://127.0.0.1:" + mock.getAddress().getPort() + "/v1";
+      AssistantQBitConfig config = new AssistantQBitConfig()
+         .withProviderName(ScriptedModelProvider.DEFAULT_NAME)
+         .withModelProvider(new ScriptedModelProvider())
+         .withProviderType(new OpenAiCompatibleProviderType())
+         .withAllowedBaseUrls(Set.of(baseUrl))
+         .withSecretResolver(name -> null)
+         .withAllowedWidgetNames(Set.of());
+      AssistantProviderType anthropic = optionalAnthropicType();
+      if(anthropic != null)
+      {
+         config.withProviderType(anthropic);
+      }
+      instance = AssistantTestFixture.build(config);
+      Integer providerId;
+      Integer modelId;
+      QContext.init(instance, AssistantTestFixture.sessionFor(ADMIN));
+      try
+      {
+         AssistantStore store = config.getRuntime().getStore();
+         AssistantProvider local = store.insert(new AssistantProvider().withName("Local GPU (Ollama)")
+            .withProviderType("openai-compatible").withKind("OLLAMA").withLocation("LOCAL").withHipaaEligible(true)
+            .withBaseUrl(baseUrl).withModel(MODEL).withEnabled(true).withIsDefault(true));
+         providerId = local.getId();
+         store.insert(new AssistantProvider().withName("OpenRouter").withProviderType("openai-compatible")
+            .withKind("OPENROUTER").withLocation("CLOUD").withEnabled(false).withIsDefault(false));
+         if(anthropic != null)
+         {
+            store.insert(new AssistantProvider().withName("Claude (production)").withProviderType(anthropic.getType())
+               .withModel("claude-sonnet-5-5").withEnabled(false).withIsDefault(false));
+         }
+
+         runProcess(DiscoverModelsProcess.NAME, providerId);
+         AssistantModel model = store.listModels().stream().filter(m -> providerId.equals(m.getProviderId()) && MODEL.equals(m.getModelId()))
+            .findFirst().orElseThrow(() -> new QException("Demo model discovery failed."));
+         modelId = model.getId();
+         store.update(model.withInputUsdPerMTok(new BigDecimal("0.05")).withOutputUsdPerMTok(new BigDecimal("0.10")));
+         runProcess(TestConnectionProcess.NAME, providerId);
+         runProcess(TestModelConnectionProcess.NAME, modelId);
+         if(!"OK".equals(store.getProvider(providerId).getLastTestStatus())
+            || store.listModels().stream().noneMatch(m -> modelId.equals(m.getId()) && "OK".equals(m.getLastTestStatus())))
+         {
+            throw (new QException("Demo connection tests failed."));
+         }
+      }
+      finally
+      {
+         QContext.clear();
+      }
+      TurnRunner.Outcome outcome = new TurnRunner(instance, config).run(ADMIN, "Say hello from the local demo provider.");
+      if(outcome.errorCode() != null || outcome.text().isBlank())
+      {
+         throw (new QException("Demo assistant turn failed: " + outcome.errorCode()));
+      }
+      TurnRunner.Outcome presentation = new TurnRunner(instance, config).run(ADMIN, IMAGE_QUESTION);
+      PresentationGoldenTask.check(presentation);
+      instance.withInstanceDefaultAuthentication(new QAuthenticationMetaData().withName("mock").withType(QAuthenticationType.MOCK)
+         .withCustomizer(new QCodeReference(DemoSessionCustomizer.class)));
+      instance.setHomeAppName(AssistantMetaDataBuilder.APP_NAME);
+      new QApplicationJavalinServer(new OpenAiDemoServer()).withPort(port).withServeFrontendNext(true).start();
+      System.out.println("Assistant home: http://localhost:" + port + "/app/" + AssistantMetaDataBuilder.APP_NAME);
+      System.out.println("Local provider: http://localhost:" + port + "/app/assistant_provider/" + providerId);
+      System.out.println("Local model: http://localhost:" + port + "/app/assistant_model/" + modelId);
+      System.out.println("Image presentation conversation id: " + presentation.conversationId());
+   }
+
+
+
+   /*******************************************************************************
+    ** Reuse the Anthropic type only when that optional module is on the classpath.
+    *******************************************************************************/
+   private static AssistantProviderType optionalAnthropicType() throws ReflectiveOperationException
+   {
+      try
+      {
+         return ((AssistantProviderType) Class.forName("com.kingsrook.qbits.assistant.provider.anthropic.AnthropicProviderType")
+            .getDeclaredConstructor().newInstance());
+      }
+      catch(ClassNotFoundException e)
+      {
+         return (null);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Execute the same streamed ETL process as the record action, skipping UI.
+    *******************************************************************************/
+   private static void runProcess(String process, Integer id) throws QException
+   {
+      RunProcessInput input = new RunProcessInput();
+      input.setProcessName(process);
+      input.setCallback(QProcessCallbackFactory.forPrimaryKey("id", id));
+      input.setFrontendStepBehavior(RunProcessInput.FrontendStepBehavior.SKIP);
+      new RunProcessAction().execute(input);
+   }
+
+
+
+   /*******************************************************************************
+    ** Repeatable localhost endpoints for startup traffic and screenshot actions.
+    ** Token counts are mock API reports, never measurements of GPU inference.
+    *******************************************************************************/
+   private static void serveMock(HttpExchange exchange) throws IOException
+   {
+      try(exchange)
+      {
+         byte[] request = exchange.getRequestBody().readAllBytes();
+         String path = exchange.getRequestURI().getPath();
+         String body;
+         if("GET".equals(exchange.getRequestMethod()) && "/v1/models".equals(path))
+         {
+            exchange.getResponseHeaders().set("Content-Type", "application/json");
+            body = """
+               {"object":"list","data":[{"id":"qwen3:30b-a3b","object":"model","owned_by":"local"},
+               {"id":"gpt-oss:20b","object":"model","owned_by":"local"},
+               {"id":"qwen3-coder:30b","object":"model","owned_by":"local"},
+               {"id":"bge-m3","object":"model","owned_by":"local"}]}
+               """;
+         }
+         else if("POST".equals(exchange.getRequestMethod()) && "/v1/chat/completions".equals(path))
+         {
+            exchange.getResponseHeaders().set("Content-Type", "text/event-stream");
+            body = completion(JSON.readTree(request));
+         }
+         else
+         {
+            exchange.sendResponseHeaders(404, -1);
+            return;
+         }
+         exchange.sendResponseHeaders(200, 0);
+         exchange.getResponseBody().write(body.getBytes(StandardCharsets.UTF_8));
+         exchange.getResponseBody().flush();
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Follow the latest user turn, so connection tests and repeated chats are
+    ** independent. Counts are read from the adapter's actual tool messages.
+    *******************************************************************************/
+   private static String completion(JsonNode request) throws IOException
+   {
+      String question = "";
+      Map<String, Integer> counts = new LinkedHashMap<>();
+      boolean presented = false;
+      for(JsonNode message : request.path("messages"))
+      {
+         if("user".equals(message.path("role").asText()))
+         {
+            question = message.path("content").asText();
+            counts.clear();
+            presented = false;
+         }
+         else if("tool".equals(message.path("role").asText()) && IMAGE_QUESTION.equals(question))
+         {
+            String id = message.path("tool_call_id").asText();
+            if(id.startsWith("count-image/"))
+            {
+               counts.put(id.substring("count-".length()), ((Number) EvalSupport.unwrap(message.path("content").asText()).get("count")).intValue());
+            }
+            else if("present-images".equals(id))
+            {
+               presented = true;
+            }
+         }
+      }
+
+      Map<String, Object> delta = Map.of("role", "assistant", "content", "Hello from the local demo provider.");
+      String finish = "stop";
+      if(IMAGE_QUESTION.equals(question) && !presented)
+      {
+         List<Map<String, Object>> calls = new ArrayList<>();
+         if(counts.isEmpty())
+         {
+            for(String mime : List.of("image/jpeg", "image/png", "image/webp", "image/gif", "image/svg+xml"))
+            {
+               calls.add(toolCall(calls.size(), "count-" + mime, "count_records", Map.of("table", "media", "filter",
+                  GoldenTasks.filter("AND", GoldenTasks.criterion("mimeType", "EQUALS", mime)))));
+            }
+         }
+         else
+         {
+            if(counts.size() != 5 || counts.get("image/webp") != 0 || counts.get("image/gif") != 0 || counts.get("image/svg+xml") != 0)
+            {
+               throw (new IOException("Unexpected demo image counts."));
+            }
+            Map<String, Object> input = PresentationGoldenTask.input(counts.get("image/jpeg"), counts.get("image/png"));
+            input.put("actions", List.of(Map.of("label", "Show the PNG files", "prompt", "Show the PNG files")));
+            calls.add(toolCall(0, "present-images", "present_results", input));
+         }
+         delta = Map.of("role", "assistant", "tool_calls", calls);
+         finish = "tool_calls";
+      }
+      else if(presented)
+      {
+         delta = Map.of("role", "assistant", "content", "You can open either image type above.");
+      }
+      return ("data: " + JSON.writeValueAsString(Map.of("id", "demo-completion", "object", "chat.completion.chunk",
+         "choices", List.of(Map.of("index", 0, "delta", delta)))) + "\n\n"
+         + "data: " + JSON.writeValueAsString(Map.of("choices", List.of(Map.of("index", 0, "delta", Map.of(), "finish_reason", finish)))) + "\n\n"
+         + "data: {\"choices\":[],\"usage\":{\"prompt_tokens\":24,\"completion_tokens\":8,\"total_tokens\":32}}\n\n"
+         + "data: [DONE]\n\n");
+   }
+
+
+
+   /*******************************************************************************
+    ** Encode tool arguments as a JSON string, as OpenAI streaming requires.
+    *******************************************************************************/
+   private static Map<String, Object> toolCall(Integer index, String id, String name, Map<String, Object> arguments) throws IOException
+   {
+      return (Map.of("index", index, "id", id, "type", "function", "function", Map.of("name", name, "arguments", JSON.writeValueAsString(arguments))));
+   }
+}

qbit-assistant-provider-openai/src/test/java/com/kingsrook/qbits/assistant/provider/openai/demo/README.md

@@ -0,0 +1,64 @@
+# OpenAI-compatible provider registry demo
+
+Run from the repository root in PowerShell with Java 21. This is a manual,
+memory-backed screenshot server, not a Surefire test. Nothing is persisted
+between runs. No API keys or external model services are needed: the secret
+resolver deliberately returns no keys, including when the shell has credentials.
+
+Build the test classpath (the local reactor class directories come first below,
+so the demo uses this checkout's code and fixture):
+
+```powershell
+.\mvnw.cmd -q -pl qbit-assistant-provider-openai -am test-compile dependency:build-classpath '-Dmdep.includeScope=test' '-Dmdep.outputFile=target/demo-classpath.txt'
+if ($LASTEXITCODE -ne 0) { throw 'Demo compilation/classpath generation failed' }
+
+$demoDependencies = (Get-Content qbit-assistant-provider-openai/target/demo-classpath.txt -Raw).Trim()
+$demoFrontend = "$env:USERPROFILE/.m2/repository/com/kingsrook/qqq/qqq-frontend-next/1.0.0-RC.18/qqq-frontend-next-1.0.0-RC.18.jar"
+$demoClasspath = "qbit-assistant-provider-openai/target/test-classes;qbit-assistant-provider-openai/target/classes;qbit-assistant/target/test-classes;qbit-assistant/target/classes;$demoFrontend;$demoDependencies"
+java -cp $demoClasspath com.kingsrook.qbits.assistant.provider.openai.demo.OpenAiDemoServer 8099
+```
+
+The frontend artifact is `com.kingsrook.qqq:qqq-frontend-next:1.0.0-RC.18`,
+already in the local Maven repository. Adjust `$demoFrontend` if your Maven
+local repository is elsewhere. Omit the final port argument for the default
+8099, or use another free port (the smoke check used 18099). Stop with Ctrl+C.
+
+Startup prints these URLs (with the selected port):
+
+- Assistant home: `http://localhost:8099/app/assistantAdmin`
+- Local provider: `http://localhost:8099/app/assistant_provider/1`
+- Priced and tested model: `http://localhost:8099/app/assistant_model/1`
+
+Startup also prints `Image presentation conversation id: <id>`. Open that
+conversation in the assistant panel history as `admin-demo` to capture the
+answer to "How many images do I have by type?". The id is assigned on each run;
+the conversation and its presentation are memory-backed and reset on restart.
+
+Every browser session is `admin-demo`. Startup inserts an enabled, default,
+keyless Local GPU (Ollama) provider, marked LOCAL and HIPAA eligible for the
+synthetic demo, and a disabled CLOUD OpenRouter provider whose key is Not set.
+If the Anthropic module is explicitly added to the classpath, its provider type
+and a disabled Claude (production) row are also included; otherwise it is skipped.
+
+The normal Discover models process fetches four model IDs from the localhost
+mock: `qwen3:30b-a3b`, `gpt-oss:20b`, `qwen3-coder:30b`, and `bge-m3`.
+A normal update sets qwen3's input/output compute prices to $0.05/$0.10 per
+million tokens. The provider and model Test connection processes then each
+make a real HTTP completion call, recording two TEST usage rows and the
+last-test fields. The greeting turn records a third usage row with purpose
+TURN. An image breakdown turn then makes three more model calls through the
+real OpenAI adapter and engine: five MIME-filtered `count_records` calls,
+`present_results` using the returned counts, and a short closing message.
+The fixture seeds 81 JPEG and 20 PNG rows (no WebP, GIF or SVG). The presentation
+includes a table with computed shares, filtered row links, a pie chart, JPEG
+and PNG filter links, and a "Show the PNG files" prompt action.
+Discovery timestamps/status also come from the actual process.
+
+Replies and token counts are synthetic mock API responses (24 input / 8 output
+tokens per completion), not live GPU measurements or billed cloud usage.
+No usage/history rows are manually seeded. The mock remains available for
+repeating discovery, connection tests and chat while taking screenshots.
+
+Capture the P-a screens in light and dark at 390 and 1440 px; see
+[`docs/screenshots/README.md`](../../../../../../../../../../../docs/screenshots/README.md)
+for the planned screenshot prefixes.

qbit-assistant-provider-openai/src/test/resources/tls/README.md

@@ -0,0 +1,23 @@
+# Test-only TLS fixtures
+
+These certificates and the private key in `server.p12` are synthetic test material.
+They must never be used for deployment or trusted outside tests. The PKCS12
+password is `test-only`. The CA private key is not retained in the repository.
+BouncyCastle was not on the test classpath, so fixtures were generated with the
+JDK 21 **keytool executable**, not internal `sun.security` APIs.
+
+The leaf is signed by `QBit TEST ONLY Root CA` and has only `DNS:localhost` in its
+SAN; connecting to `127.0.0.1` deliberately fails hostname verification. Both
+certificates start on 2020-01-01 and last 36,500 days to avoid date-dependent tests.
+Each regeneration creates fresh random keys. Run in a temporary directory, then
+copy only `ca.pem` and `server.p12` here:
+
+```sh
+keytool -genkeypair -alias ca -keyalg RSA -keysize 2048 -dname 'CN=QBit TEST ONLY Root CA' -ext bc:c=ca:true -ext ku:c=keyCertSign,cRLSign -startdate '2020/01/01 00:00:00' -validity 36500 -keystore ca.p12 -storepass test-only -storetype PKCS12 -noprompt
+keytool -exportcert -rfc -alias ca -keystore ca.p12 -storepass test-only -file ca.pem
+keytool -genkeypair -alias server -keyalg RSA -keysize 2048 -dname 'CN=localhost' -startdate '2020/01/01 00:00:00' -validity 36500 -keystore server.p12 -storetype PKCS12 -storepass test-only -noprompt
+keytool -certreq -alias server -keystore server.p12 -storepass test-only -file server.csr
+keytool -gencert -alias ca -keystore ca.p12 -storepass test-only -infile server.csr -outfile server.pem -rfc -startdate '2020/01/01 00:00:00' -validity 36500 -ext san=dns:localhost -ext eku=serverAuth -ext ku=digitalSignature,keyEncipherment
+keytool -importcert -alias ca -file ca.pem -keystore server.p12 -storepass test-only -noprompt
+keytool -importcert -alias server -file server.pem -keystore server.p12 -storepass test-only -noprompt
+```

qbit-assistant-provider-openai/src/test/resources/tls/ca.pem

@@ -0,0 +1,19 @@
+-----BEGIN CERTIFICATE-----
+MIIDCDCCAfCgAwIBAgIII8Xlo9Lidn4wDQYJKoZIhvcNAQEMBQAwITEfMB0GA1UE
+AxMWUUJpdCBURVNUIE9OTFkgUm9vdCBDQTAgFw0yMDAxMDEwNjAwMDBaGA8yMTE5
+MTIwODA2MDAwMFowITEfMB0GA1UEAxMWUUJpdCBURVNUIE9OTFkgUm9vdCBDQTCC
+ASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMyuwvRX9gZCJoJW68JPf8HC
+9rA/WAqSwIgwOi6JUVGfRFkp3DZGvfvfw/SiYkED+Zf0AeVrfOZbNZO4dXoe9Rxq
+YBu4nr79jCfKnlmGsIr/YmWxePUzixvxJ7suHb4y1uah7C36h1EeQKAEYbpFhI7o
+WVQkZonWDr4w0PmcstjS4lIT43lZdbAxX7RRhiBKe9Ph9P+sqbn1Uk4GOPo5YQkg
+5eZSPAU4gVh4K07e4aVej+kRHMqMmP4joY4KHBrZXOHKN/mXDGkipys0bf+z7uti
+/qowu6lNEdF/IihvCgU/fe5wVFbdh7E5t+mpRo+A9B0YrQAtqkJ6gw+Nrwr2TvEC
+AwEAAaNCMEAwHQYDVR0OBBYEFMul052SYQj4mA4NgW+mX5mfSzgyMA4GA1UdDwEB
+/wQEAwIBBjAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBDAUAA4IBAQCAKxnC
+2iBt6cxyh3T/Z11fdBEEFASYU2C/nGqt1FnYhyfR9eluDerNJqsnHmP9pjmf5KAO
+bGYiw9WodHEbLyM9etNPJSCJRouCHFmRyWarfQV95NjkMfVMXdA2zNWmWv0vxZ2y
+dOSQUP3nCegLW1JqBoDsdJCJvzU8lcuUwVd9BNywcXmrQbL0iHETwUUWtIEACv2A
+ja9ZNHYs1oZbaA9YotK3vCcCt0B9xHxMDza9Er7ljTWE6zexTh7IWJ/MbABUdQbQ
+SGDVrVFlk2PoDIO5rwRwS8LwaKkdwuPcAHbhBRN3HVyr06SBD7AiVWhUV7g5R+h3
+qHqj8SDW3k3QL63f
+-----END CERTIFICATE-----

qbit-assistant-provider-vertex/pom.xml

@@ -0,0 +1,146 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Copyright 2026 Kingsrook, LLC
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+   <modelVersion>4.0.0</modelVersion>
+
+   <parent>
+      <groupId>com.kingsrook.qbits</groupId>
+      <artifactId>qbit-assistant-parent</artifactId>
+      <version>${revision}</version>
+   </parent>
+
+   <artifactId>qbit-assistant-provider-vertex</artifactId>
+   <packaging>jar</packaging>
+
+   <name>QBit Assistant - Vertex provider</name>
+   <description>Vertex provider using the Anthropic cloud backend</description>
+   <url>https://github.com/QRun-IO/qbit-assistant</url>
+
+   <dependencies>
+      <dependency>
+         <groupId>com.anthropic</groupId>
+         <artifactId>anthropic-java-vertex</artifactId>
+      </dependency>
+      <dependency>
+         <groupId>com.kingsrook.qbits</groupId>
+         <artifactId>qbit-assistant-provider-anthropic</artifactId>
+      </dependency>
+      <dependency>
+         <groupId>com.kingsrook.qbits</groupId>
+         <artifactId>qbit-assistant-provider-openai</artifactId>
+      </dependency>
+
+      <dependency>
+         <groupId>com.kingsrook.qbits</groupId>
+         <artifactId>qbit-assistant-provider-api</artifactId>
+      </dependency>
+      <dependency>
+         <groupId>com.kingsrook.qbits</groupId>
+         <artifactId>qbit-assistant</artifactId>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>com.kingsrook.qqq</groupId>
+         <artifactId>qqq-backend-core</artifactId>
+      </dependency>
+      <dependency>
+         <groupId>com.fasterxml.jackson.core</groupId>
+         <artifactId>jackson-databind</artifactId>
+      </dependency>
+
+      <dependency>
+         <groupId>com.kingsrook.qbits</groupId>
+         <artifactId>qbit-assistant</artifactId>
+         <type>test-jar</type>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>com.kingsrook.qqq</groupId>
+         <artifactId>qqq-middleware-javalin</artifactId>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>org.junit.jupiter</groupId>
+         <artifactId>junit-jupiter</artifactId>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>org.assertj</groupId>
+         <artifactId>assertj-core</artifactId>
+         <scope>test</scope>
+      </dependency>
+   </dependencies>
+
+   <build>
+      <plugins>
+         <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-surefire-plugin</artifactId>
+            <configuration>
+               <!-- live evals call the real API: opt-in only -->
+               <excludedGroups>${test.excludedGroups}</excludedGroups>
+               <redirectTestOutputToFile>true</redirectTestOutputToFile>
+            </configuration>
+         </plugin>
+         <plugin>
+            <groupId>org.jacoco</groupId>
+            <artifactId>jacoco-maven-plugin</artifactId>
+            <executions>
+               <execution>
+                  <id>prepare-agent</id>
+                  <goals>
+                     <goal>prepare-agent</goal>
+                  </goals>
+               </execution>
+               <execution>
+                  <id>report</id>
+                  <phase>verify</phase>
+                  <goals>
+                     <goal>report</goal>
+                  </goals>
+               </execution>
+               <execution>
+                  <id>check</id>
+                  <goals>
+                     <goal>check</goal>
+                  </goals>
+                  <configuration>
+                     <rules>
+                        <rule>
+                           <element>BUNDLE</element>
+                           <limits>
+                              <limit>
+                                 <counter>INSTRUCTION</counter>
+                                 <value>COVEREDRATIO</value>
+                                 <minimum>0.70</minimum>
+                              </limit>
+                              <limit>
+                                 <counter>CLASS</counter>
+                                 <value>COVEREDRATIO</value>
+                                 <minimum>0.90</minimum>
+                              </limit>
+                           </limits>
+                        </rule>
+                     </rules>
+                  </configuration>
+               </execution>
+            </executions>
+         </plugin>
+      </plugins>
+   </build>
+</project>

qbit-assistant-provider-vertex/src/main/java/com/kingsrook/qbits/assistant/provider/vertex/VertexModelProvider.java

@@ -0,0 +1,166 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.provider.vertex;
+
+
+import java.io.IOException;
+import java.time.Duration;
+import com.anthropic.client.okhttp.AnthropicOkHttpClient;
+import com.anthropic.core.Timeout;
+import com.anthropic.vertex.backends.VertexBackend;
+import com.google.auth.oauth2.GoogleCredentials;
+import com.kingsrook.qbits.assistant.provider.anthropic.AnthropicModelProvider;
+import com.kingsrook.qbits.assistant.provider.openai.OpenAiCompatibleModelProvider;
+import com.kingsrook.qbits.assistant.spi.AssistantModelProvider;
+import com.kingsrook.qbits.assistant.spi.ModelCapabilities;
+import com.kingsrook.qbits.assistant.spi.ModelEventListener;
+import com.kingsrook.qbits.assistant.spi.ModelRequest;
+import com.kingsrook.qbits.assistant.spi.ProviderSettings;
+import com.kingsrook.qbits.assistant.spi.StreamHandle;
+
+
+/*******************************************************************************
+ ** Route Claude to the Anthropic backend and other models to Vertex OpenAI.
+ ** One scoped ADC credential supplies both clients; access tokens stay in memory.
+ *******************************************************************************/
+public class VertexModelProvider implements AssistantModelProvider
+{
+   private final AnthropicModelProvider claude;
+   private final OpenAiCompatibleModelProvider openai;
+
+
+
+   /*******************************************************************************
+    ** Load Application Default Credentials without exposing credential failures.
+    *******************************************************************************/
+   public VertexModelProvider(ProviderSettings settings)
+   {
+      this(settings, applicationCredentials());
+   }
+
+
+
+   /*******************************************************************************
+    ** Credential injection for deterministic, offline contract tests.
+    *******************************************************************************/
+   VertexModelProvider(ProviderSettings settings, GoogleCredentials credentials)
+   {
+      GoogleCredentials scoped = credentials.createScoped("https://www.googleapis.com/auth/cloud-platform");
+      var backend = VertexBackend.builder().googleCredentials(scoped).region(settings.getRegion()).project(settings.getCloudProject());
+      if(settings.getBaseUrl() != null)
+      {
+         backend.baseUrl(settings.getBaseUrl());
+      }
+      claude = AnthropicModelProvider.builder().client(AnthropicOkHttpClient.builder().backend(backend.build())
+         .timeout(Timeout.builder().connect(Duration.ofSeconds(settings.getConnectTimeoutSeconds()))
+            .request(Duration.ofSeconds(settings.getRequestTimeoutSeconds())).build()).build()).build();
+      String base = settings.getBaseUrl() == null ? "https://" + settings.getRegion() + "-aiplatform.googleapis.com/v1/projects/"
+         + settings.getCloudProject() + "/locations/" + settings.getRegion() + "/endpoints/openapi" : settings.getBaseUrl();
+      openai = new OpenAiCompatibleModelProvider(new ProviderSettings().withKind("VERTEX").withBaseUrl(base)
+         .withConnectTimeoutSeconds(settings.getConnectTimeoutSeconds()).withRequestTimeoutSeconds(settings.getRequestTimeoutSeconds())
+         .withTlsCaBundle(settings.getTlsCaBundle()).withSslContext(settings.getSslContext())
+         .withBearerTokenSupplier(() -> accessToken(scoped)));
+   }
+
+
+
+   /*******************************************************************************
+    ** Resolve ADC lazily when a provider is created, not during registration.
+    *******************************************************************************/
+   private static GoogleCredentials applicationCredentials()
+   {
+      try
+      {
+         return (GoogleCredentials.getApplicationDefault());
+      }
+      catch(IOException e)
+      {
+         throw (new IllegalStateException("Google Application Default Credentials are unavailable. Configure GOOGLE_APPLICATION_CREDENTIALS or workload identity."));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Refresh expired credentials on every request; never retain a token in settings.
+    *******************************************************************************/
+   private static String accessToken(GoogleCredentials credentials)
+   {
+      try
+      {
+         credentials.refreshIfExpired();
+         return (credentials.getAccessToken().getTokenValue());
+      }
+      catch(IOException e)
+      {
+         throw (new IllegalStateException("Could not refresh Google Application Default Credentials."));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Provider identity.
+    *******************************************************************************/
+   @Override
+   public String getName()
+   {
+      return ("vertex");
+   }
+
+
+
+   /*******************************************************************************
+    ** Route using the registry's model id; caller requests are never mutated.
+    *******************************************************************************/
+   private AssistantModelProvider route(String model)
+   {
+      return (model != null && model.startsWith("claude-") ? claude : openai);
+   }
+
+
+
+   /*******************************************************************************
+    ** Capabilities follow the selected backend.
+    *******************************************************************************/
+   @Override
+   public ModelCapabilities getCapabilities(String modelId)
+   {
+      return (route(modelId).getCapabilities(modelId));
+   }
+
+
+
+   /*******************************************************************************
+    ** Stream through the existing adapters, preserving their error and tool mapping.
+    *******************************************************************************/
+   @Override
+   public StreamHandle stream(ModelRequest request, ModelEventListener listener)
+   {
+      return (route(request.getModel()).stream(request, listener));
+   }
+
+
+
+   /*******************************************************************************
+    ** Release the Anthropic client and its executor.
+    *******************************************************************************/
+   public void close()
+   {
+      claude.close();
+   }
+}

qbit-assistant-provider-vertex/src/main/java/com/kingsrook/qbits/assistant/provider/vertex/VertexProviderType.java

@@ -0,0 +1,156 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.provider.vertex;
+
+
+import java.util.ArrayList;
+import java.util.List;
+import com.kingsrook.qbits.assistant.spi.AssistantModelProvider;
+import com.kingsrook.qbits.assistant.spi.AssistantProviderType;
+import com.kingsrook.qbits.assistant.spi.DiscoveredModel;
+import com.kingsrook.qbits.assistant.spi.ProviderSettings;
+
+
+/*******************************************************************************
+ ** Google Vertex AI (Claude, Gemini), using server credentials and region-derived endpoints.
+ *******************************************************************************/
+public class VertexProviderType implements AssistantProviderType
+{
+
+
+
+   /*******************************************************************************
+    ** Provider registry contract.
+    *******************************************************************************/
+   @Override
+   public String getType()
+   {
+      return ("vertex");
+   }
+
+
+
+   /*******************************************************************************
+    ** Provider registry contract.
+    *******************************************************************************/
+   @Override
+   public String getLabel()
+   {
+      return ("Google Vertex AI (Claude, Gemini)");
+   }
+
+
+
+   /*******************************************************************************
+    ** Provider registry contract.
+    *******************************************************************************/
+   @Override
+   public List<String> getModels()
+   {
+      return (List.of("claude-sonnet-4-5@20250929", "claude-haiku-4-5@20251001", "gemini-2.5-pro", "gemini-2.5-flash"));
+   }
+
+
+
+   /*******************************************************************************
+    ** Provider registry contract.
+    *******************************************************************************/
+   @Override
+   public String getDefaultApiKeyEnvName()
+   {
+      return (null);
+   }
+
+
+
+   /*******************************************************************************
+    ** Provider registry contract.
+    *******************************************************************************/
+   @Override
+   public String getDefaultBaseUrl()
+   {
+      return (null);
+   }
+
+
+
+   /*******************************************************************************
+    ** Provider registry contract.
+    *******************************************************************************/
+   @Override
+   public boolean requiresBaseUrl(String kind)
+   {
+      return (false);
+   }
+
+
+
+   /*******************************************************************************
+    ** Validate cloud settings without loading credentials.
+    *******************************************************************************/
+   @Override
+   public List<String> validate(ProviderSettings settings)
+   {
+      List<String> errors = new ArrayList<>();
+      if(settings.getRegion() == null || settings.getRegion().isBlank())
+      {
+         errors.add("Region is required for VERTEX.");
+      }
+      if(settings.getApiKeyEnvName() != null && !settings.getApiKeyEnvName().isBlank())
+      {
+         errors.add("Leave API key variable empty: Google Vertex AI (Claude, Gemini) uses Google Application Default Credentials (GOOGLE_APPLICATION_CREDENTIALS or workload identity).");
+      }
+      if(settings.getCloudProject() == null || settings.getCloudProject().isBlank())
+      {
+         errors.add("GCP project id (cloudProject) is required for VERTEX.");
+      }
+      return (errors);
+   }
+
+
+
+   /*******************************************************************************
+    ** Cloud providers require resolved region/project settings.
+    *******************************************************************************/
+   @Override
+   public AssistantModelProvider create(String apiKey, String baseUrl)
+   {
+      throw (new IllegalArgumentException("Use ProviderSettings with the required cloud region and project."));
+   }
+
+
+
+   /*******************************************************************************
+    ** Static defaults; this adapter does not query the Vertex Model Garden.
+    *******************************************************************************/
+   @Override
+   public List<DiscoveredModel> discoverModels(ProviderSettings settings)
+   {
+      return (getModels().stream().map(id -> new DiscoveredModel(id, id, null, null)).toList());
+   }
+
+
+
+   /*******************************************************************************
+    ** Create the provider with server credentials.
+    *******************************************************************************/
+   @Override
+   public AssistantModelProvider create(ProviderSettings settings)
+   {
+      return (new VertexModelProvider(settings));
+   }
+}

qbit-assistant-provider-vertex/src/test/java/com/kingsrook/qbits/assistant/provider/vertex/VertexContractTest.java

@@ -0,0 +1,309 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.provider.vertex;
+
+
+import java.io.IOException;
+import java.time.Clock;
+import java.time.Duration;
+import java.util.Date;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import com.google.auth.oauth2.AccessToken;
+import com.google.auth.oauth2.GoogleCredentials;
+import com.kingsrook.qbits.assistant.AssistantQBitConfig;
+import com.kingsrook.qbits.assistant.engine.ProviderService;
+import com.kingsrook.qbits.assistant.model.AssistantProvider;
+import com.kingsrook.qbits.assistant.spi.ModelMessage;
+import com.kingsrook.qbits.assistant.spi.ModelProviderException;
+import com.kingsrook.qbits.assistant.spi.ModelRequest;
+import com.kingsrook.qbits.assistant.spi.ModelToolDefinition;
+import com.kingsrook.qbits.assistant.spi.ProviderSettings;
+import com.kingsrook.qbits.assistant.testing.CloudProviderTestServer;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+import static com.kingsrook.qbits.assistant.testing.CloudProviderTestServer.JSON;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+
+/*******************************************************************************
+ ** Real Vertex Claude and OpenAI-compatible transports using fake ADC tokens.
+ *******************************************************************************/
+class VertexContractTest
+{
+   static final String CLAUDE = "claude-sonnet-4-5@20250929";
+   static final String GEMINI = "gemini-2.5-flash";
+
+
+
+   /*******************************************************************************
+    ** Fixed fake token, valid well beyond the test duration.
+    *******************************************************************************/
+   static GoogleCredentials credentials()
+   {
+      return (GoogleCredentials.create(new AccessToken("fake-google-token", new Date(System.currentTimeMillis() + 3_600_000))));
+   }
+
+
+
+   /*******************************************************************************
+    ** Scoped connection settings with a loopback override.
+    *******************************************************************************/
+   static ProviderSettings settings(CloudProviderTestServer server)
+   {
+      return (new ProviderSettings().withKind("VERTEX").withRegion("us-east5").withCloudProject("test-project").withBaseUrl(server.url())
+         .withConnectTimeoutSeconds(2).withRequestTimeoutSeconds(5));
+   }
+
+
+
+   /*******************************************************************************
+    ** A strict request verifies that only the Claude backend preserves strict.
+    *******************************************************************************/
+   static ModelRequest request(String model)
+   {
+      return (new ModelRequest().withModel(model).withMaxTokens(1024).withMessages(List.of(ModelMessage.user("Count posts")))
+         .withTools(List.of(new ModelToolDefinition().withName("count_records").withDescription("Count records").withStrict(true)
+            .withInputSchema(Map.of("type", "object", "properties", Map.of("table", Map.of("type", "string")), "required", List.of("table"), "additionalProperties", false)))));
+   }
+
+
+
+   /*******************************************************************************
+    ** Text and a fragmented tool call in a Vertex OpenAI-compatible stream.
+    *******************************************************************************/
+   static String geminiSse(String text, Map<String, Object> input) throws IOException
+   {
+      StringBuilder events = new StringBuilder();
+      events.append("data: ").append(JSON.writeValueAsString(Map.of("choices", List.of(Map.of("delta", Map.of("content", text)))))).append("\n\n");
+      if(input != null)
+      {
+         String arguments = JSON.writeValueAsString(input);
+         Integer middle = arguments.length() / 2;
+         events.append("data: ").append(JSON.writeValueAsString(Map.of("choices", List.of(Map.of("delta", Map.of("tool_calls", List.of(
+            Map.of("index", 0, "id", "count", "type", "function", "function", Map.of("name", "count_records", "arguments", arguments.substring(0, middle)))))))))).append("\n\n");
+         events.append("data: ").append(JSON.writeValueAsString(Map.of("choices", List.of(Map.of("delta", Map.of("tool_calls", List.of(
+            Map.of("index", 0, "function", Map.of("arguments", arguments.substring(middle)))))))))).append("\n\n");
+      }
+      events.append("data: ").append(JSON.writeValueAsString(Map.of("choices", List.of(Map.of("delta", Map.of(), "finish_reason", input == null ? "stop" : "tool_calls")),
+         "usage", Map.of("prompt_tokens", 12, "completion_tokens", 7)))).append("\n\ndata: [DONE]\n\n");
+      return (events.toString());
+   }
+
+
+
+   /*******************************************************************************
+    ** Claude path, ADC bearer, Anthropic version, streaming text, tools and usage.
+    *******************************************************************************/
+   @Test
+   void claudeContract() throws Exception
+   {
+      try(CloudProviderTestServer server = new CloudProviderTestServer())
+      {
+         server.sse(CloudProviderTestServer.anthropicSse(CLAUDE, "Checking.", Map.of("table", "blog_post")));
+         var provider = new VertexModelProvider(settings(server), credentials());
+         try
+         {
+            StringBuilder text = new StringBuilder();
+            var response = provider.stream(request(CLAUDE), text::append).await(Duration.ofSeconds(10));
+            assertThat(provider.getName()).isEqualTo("vertex");
+            assertThat(provider.getCapabilities(CLAUDE).getPromptCaching()).isTrue();
+            assertThat(text.toString()).isEqualTo("Checking.");
+            assertThat(response.getToolUses()).singleElement().satisfies(tool ->
+            {
+               assertThat(tool.getToolUseId()).isEqualTo("count");
+               assertThat(tool.getToolName()).isEqualTo("count_records");
+               assertThat(tool.getInput()).containsEntry("table", "blog_post");
+            });
+            assertThat(response.getUsage().getInputTokens()).isEqualTo(12);
+            assertThat(response.getUsage().getOutputTokens()).isEqualTo(7);
+            var sent = server.requests.getFirst();
+            assertThat(sent.path()).isEqualTo("/v1/projects/test-project/locations/us-east5/publishers/anthropic/models/" + CLAUDE + ":streamRawPredict");
+            assertThat(sent.authorization()).isEqualTo("Bearer fake-google-token");
+            var body = JSON.readTree(sent.body());
+            assertThat(body.path("anthropic_version").asText()).isEqualTo("vertex-2023-10-16");
+            assertThat(body.has("model")).isFalse();
+            assertThat(body.path("tools").get(0).path("strict").asBoolean()).isTrue();
+         }
+         finally
+         {
+            provider.close();
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Gemini, already-prefixed and other ids all use OpenAI without strict.
+    *******************************************************************************/
+   @ParameterizedTest
+   @ValueSource(strings = { "gemini-2.5-flash", "google/gemini-2.5-pro", "other-model" })
+   void geminiContractAndTokenRefresh(String model) throws Exception
+   {
+      try(CloudProviderTestServer server = new CloudProviderTestServer())
+      {
+         var credentials = new RefreshingCredentials();
+         String endpoint = "/v1/projects/test-project/locations/us-east5/endpoints/openapi";
+         var provider = new VertexModelProvider(settings(server).withBaseUrl(server.url() + endpoint), credentials);
+         try
+         {
+            for(int call = 1; call <= 2; call++)
+            {
+               server.sse(geminiSse("Checking.", Map.of("table", "blog_post")));
+               StringBuilder text = new StringBuilder();
+               ModelRequest request = request(model);
+               var response = provider.stream(request, text::append).await(Duration.ofSeconds(10));
+               assertThat(text.toString()).isEqualTo("Checking.");
+               assertThat(request.getModel()).isEqualTo(model);
+               assertThat(response.getToolUses()).singleElement().satisfies(tool ->
+               {
+                  assertThat(tool.getToolName()).isEqualTo("count_records");
+                  assertThat(tool.getInput()).containsEntry("table", "blog_post");
+               });
+               assertThat(response.getUsage().getInputTokens()).isEqualTo(12);
+               assertThat(response.getUsage().getOutputTokens()).isEqualTo(7);
+               var sent = server.requests.get(call - 1);
+               assertThat(sent.path()).isEqualTo(endpoint + "/chat/completions");
+               assertThat(sent.authorization()).isEqualTo("Bearer refreshed-" + call);
+               var body = JSON.readTree(sent.body());
+               assertThat(body.path("model").asText()).isEqualTo(model.contains("/") ? model : "google/" + model);
+               assertThat(body.path("tools").get(0).path("function").has("strict")).isFalse();
+               if(call == 1)
+               {
+                  credentials.refresh();
+               }
+            }
+            assertThat(credentials.refreshes).isEqualTo(2);
+            assertThat(provider.getCapabilities(model).getPromptCaching()).isFalse();
+            assertThat(provider.getCapabilities(null).getTools()).isTrue();
+         }
+         finally
+         {
+            provider.close();
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Start expired so refreshIfExpired must obtain the first token itself.
+    *******************************************************************************/
+   static class RefreshingCredentials extends GoogleCredentials
+   {
+      private Integer refreshes = 0;
+
+      /*******************************************************************************
+       ** An expired fake token cannot authorize the first request.
+       *******************************************************************************/
+      RefreshingCredentials()
+      {
+         super(new AccessToken("expired", new Date(0)));
+      }
+
+      /*******************************************************************************
+       ** Deterministic replacement tokens, without a token-server request.
+       *******************************************************************************/
+      @Override
+      public AccessToken refreshAccessToken() throws IOException
+      {
+         refreshes++;
+         return (new AccessToken("refreshed-" + refreshes, new Date(System.currentTimeMillis() + 3_600_000)));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** ADC refresh failures cannot leak the credential exception's details.
+    *******************************************************************************/
+   @Test
+   void refreshFailureIsSanitized() throws Exception
+   {
+      try(CloudProviderTestServer server = new CloudProviderTestServer())
+      {
+         var credentials = new RefreshingCredentials()
+         {
+            /*******************************************************************************
+             ** Simulate a token service failure containing confidential diagnostics.
+             *******************************************************************************/
+            @Override
+            public AccessToken refreshAccessToken() throws IOException
+            {
+               throw (new IOException("synthetic-private-token"));
+            }
+         };
+         var provider = new VertexModelProvider(settings(server), credentials);
+         try
+         {
+            assertThatThrownBy(() -> provider.stream(request(GEMINI), delta -> {}).await(Duration.ofSeconds(10)))
+               .isInstanceOfSatisfying(ModelProviderException.class, error ->
+               {
+                  assertThat(error.getKind()).isEqualTo(ModelProviderException.Kind.AUTHENTICATION);
+                  assertThat(error.toString()).doesNotContain("synthetic-private-token");
+                  assertThat(error.getCause()).isNull();
+               });
+            assertThat(server.requests).isEmpty();
+         }
+         finally
+         {
+            provider.close();
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Cloud requirements, static discovery and URL allowlists need no ADC lookup.
+    *******************************************************************************/
+   @Test
+   void settingsValidationAndDefaults() throws Exception
+   {
+      var type = new VertexProviderType();
+      var config = new AssistantQBitConfig().withProviderType(type).withAllowedBaseUrls(Set.of("http://127.0.0.1:1234"));
+      var service = new ProviderService(config, null, Clock.systemUTC());
+      var row = new AssistantProvider().withProviderType("vertex");
+      assertThat(service.validate(row)).anyMatch(error -> error.contains("Region is required")).anyMatch(error -> error.contains("project id"));
+      row.withRegion(" ").withCloudProject(" ");
+      assertThat(service.validate(row)).hasSize(2);
+      row.withRegion("us-east5").withCloudProject("test-project");
+      assertThat(service.validate(row)).isEmpty();
+      row.withApiKeyEnvName("GOOGLE_API_KEY");
+      assertThat(service.validate(row)).anyMatch(error -> error.contains("Application Default Credentials"));
+      row.withApiKeyEnvName(" ").withBaseUrl("https://unlisted.example");
+      assertThat(service.validate(row)).anyMatch(error -> error.contains("not allowed"));
+      row.withBaseUrl("http://127.0.0.1:1234");
+      assertThat(service.validate(row)).isEmpty();
+      assertThat(type.getType()).isEqualTo("vertex");
+      assertThat(type.getKinds()).containsExactly("VERTEX");
+      assertThat(type.getLabel()).isEqualTo("Google Vertex AI (Claude, Gemini)");
+      assertThat(type.getDefaultLocation("VERTEX")).isEqualTo("CLOUD");
+      assertThat(type.getDefaultApiKeyEnvName()).isNull();
+      assertThat(type.getDefaultBaseUrl()).isNull();
+      assertThat(type.discoverModels(new ProviderSettings())).extracting(model -> model.modelId()).containsExactlyElementsOf(type.getModels());
+      assertThat(type.checkHealth(new ProviderSettings()).healthy()).isNull();
+      assertThatThrownBy(() -> type.create("key", null)).isInstanceOf(IllegalArgumentException.class);
+      // Exercise endpoint derivation without sending any request to that endpoint.
+      var provider = new VertexModelProvider(new ProviderSettings().withRegion("us-east5").withCloudProject("test-project"), credentials());
+      provider.close();
+   }
+}

qbit-assistant-provider-vertex/src/test/java/com/kingsrook/qbits/assistant/provider/vertex/VertexGoldenTurnTest.java

@@ -0,0 +1,100 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.assistant.provider.vertex;
+
+
+import com.kingsrook.qbits.assistant.AssistantModelRouting;
+import com.kingsrook.qbits.assistant.AssistantQBitConfig;
+import com.kingsrook.qbits.assistant.testing.AssistantTestFixture;
+import com.kingsrook.qbits.assistant.testing.CloudProviderTestServer;
+import com.kingsrook.qbits.assistant.testing.GoldenTasks;
+import com.kingsrook.qbits.assistant.testing.TurnRunner;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import org.junit.jupiter.api.Tag;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+import static com.kingsrook.qbits.assistant.testing.CloudProviderTestServer.JSON;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** Golden task through the cloud adapter, turn engine and permissioned UI tools.
+ *******************************************************************************/
+@Tag("golden")
+class VertexGoldenTurnTest
+{
+   /*******************************************************************************
+    ** A real count_records round trip returns the tool result to the model.
+    *******************************************************************************/
+   @ParameterizedTest
+   @ValueSource(strings = { VertexContractTest.CLAUDE, VertexContractTest.GEMINI })
+   void goldenToolRoundTrip(String model) throws Exception
+   {
+      try(CloudProviderTestServer server = new CloudProviderTestServer())
+      {
+         String answer = "There are " + AssistantTestFixture.PUBLISHED_POSTS + " published posts. /app/blog_post";
+         boolean claude = model.startsWith("claude-");
+         server.sse(claude ? CloudProviderTestServer.anthropicSse(model, "", CloudProviderTestServer.countInput()) : VertexContractTest.geminiSse("", CloudProviderTestServer.countInput()));
+         server.sse(claude ? CloudProviderTestServer.anthropicSse(model, answer, null) : VertexContractTest.geminiSse(answer, null));
+         var provider = new VertexModelProvider(VertexContractTest.settings(server), VertexContractTest.credentials());
+         var config = new AssistantQBitConfig().withProviderName(provider.getName()).withModelProvider(provider)
+            .withModels(new AssistantModelRouting().withMainModel(model));
+         try
+         {
+            var instance = AssistantTestFixture.build(config);
+            var task = GoldenTasks.all().stream().filter(t -> t.id().equals("count-published-posts")).findFirst().orElseThrow();
+            var outcome = new TurnRunner(instance, config).run(task.userId(), task.prompt());
+            assertThat(outcome.errorCode()).isNull();
+            task.check().accept(outcome);
+            assertThat(outcome.text()).endsWith(answer);
+            assertThat(outcome.end()).isNotEmpty();
+            assertThat(server.requests).hasSize(2);
+            var messages = JSON.readTree(server.requests.get(1).body()).path("messages");
+            var assistant = messages.get(messages.size() - 2);
+            var result = messages.get(messages.size() - 1);
+            assertThat(assistant.path("role").asText()).isEqualTo("assistant");
+            if(claude)
+            {
+               assertThat(assistant.path("content").toString()).contains("count_records", "count");
+               assertThat(result.path("role").asText()).isEqualTo("user");
+               var toolResult = result.path("content").get(0);
+               assertThat(toolResult.path("type").asText()).isEqualTo("tool_result");
+               assertThat(toolResult.path("tool_use_id").asText()).isEqualTo("count");
+               assertThat(toolResult.path("is_error").asBoolean()).isFalse();
+               assertThat(toolResult.path("content").toString()).contains("count");
+            }
+            else
+            {
+               assertThat(assistant.path("tool_calls")).hasSize(1);
+               assertThat(assistant.path("tool_calls").get(0).path("id").asText()).isEqualTo("count");
+               assertThat(result.path("role").asText()).isEqualTo("tool");
+               assertThat(result.path("tool_call_id").asText()).isEqualTo("count");
+               assertThat(result.path("content").asText()).contains("count").doesNotStartWith("ERROR:");
+            }
+         }
+         finally
+         {
+            if(config.getRuntime() != null)
+            {
+               config.getRuntime().close();
+            }
+            provider.close();
+            QContext.clear();
+         }
+      }
+   }
+}