# 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 = ;`). 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/`. 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:` (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): - `assistant_provider` (with the `api_key_status` column: it is filled on read and never written, but the backend selects it) - `assistant_model_price` - `assistant_usage` Then, to keep answering exactly as before: 1. Register the provider type: `config.withProviderType(new AnthropicProviderType())`. Keep `withModelProvider(AnthropicModelProvider.fromEnvironment())` as the fallback. 2. Add one provider row (or seed it in your migration): type `anthropic`, model = your current main model, enabled, default, `apiKeyEnvName` = `ANTHROPIC_API_KEY` (or leave it empty for the default). No key value is ever written. 3. Run **Test connection** on it. Until a row exists, the provider registered in code answers, as in RC.3. Other changes: the app label is **Assistant**; the nav no longer lists the retention process (it is a table action on conversations) or the audit tables (they are child lists). Grants on `assistant.admin` cover everything new. ## 0.1.0-RC.1 to 0.1.0-RC.3: snake_case names The rename shipped in 0.1.0-RC.3. 0.1.0-RC.2 on Maven Central is an accidental republish of the RC.1 code (see CHANGELOG.md), so upgrading from RC.2 is the same as upgrading from RC.1. RC.3 applies the QRun-IO naming rule (owner decision, 2026-10-12): *"table names should always be lowercase and use _, and qbits should always be prefixed with their name"*. The QQQ table names, the owner security key type and the possible-value source change. Permissions do not. **This is a metadata-only change**: no table, column or index in your database changes, and no Liquibase or DDL step is needed. ### What changed | Kind | RC.1 (and RC.2) name | RC.3 name | |---|---|---| | Table | `assistantConversation` | `assistant_conversation` | | Table | `assistantMessage` | `assistant_message` | | Table | `assistantTurn` | `assistant_turn` | | Table | `assistantTurnEvent` | `assistant_turn_event` | | Table | `assistantToolCall` | `assistant_tool_call` | | Table | `assistantFeedback` | `assistant_feedback` | | Table | `assistantPolicy` | `assistant_policy` | | Table | `assistantUsageDaily` | `assistant_usage_daily` | | Possible-value source (conversations) | `assistantConversation` | `assistant_conversation` | | Permissions | `assistant.hasAccess`, `assistant.admin` | unchanged (QQQ's standard `.hasAccess` suffix; the `assistant` base already follows the rule) | | Security key type | `assistantUserId` | `assistant_user_id` | | All-access key | `assistantUserIdAllAccess` | `assistant_user_id_all_access` | Unchanged: Java class names, field names (`userId`, `conversationId`, ...), the `assistantAdmin` app, the `assistantRetention` process, the `/qqq/v1/assistant` routes and the `assistant` supplemental instance meta-data. The old names stay available as `@Deprecated` constants for one release, so migration code can refer to them: `.LEGACY_TABLE_NAME`, `AssistantQBitConfig.LEGACY_DEFAULT_OWNER_KEY_TYPE` and `AssistantMetaDataBuilder.LEGACY_ALL_ACCESS_SUFFIX`. They will be removed in 0.2.0. ### Physical tables `docs/schema-postgres.sql` already creates `assistant_*` tables. If your RDBMS backend mapped the old QQQ names to those tables (for example with `inferBackendName`), the new QQQ names now equal the physical names and nothing else is needed; the mapping becomes a no-op. If you created tables literally named `assistantConversation` and so on, either rename them: ```sql ALTER TABLE "assistantConversation" RENAME TO assistant_conversation; ALTER TABLE "assistantMessage" RENAME TO assistant_message; ALTER TABLE "assistantTurn" RENAME TO assistant_turn; ALTER TABLE "assistantTurnEvent" RENAME TO assistant_turn_event; ALTER TABLE "assistantToolCall" RENAME TO assistant_tool_call; ALTER TABLE "assistantFeedback" RENAME TO assistant_feedback; ALTER TABLE "assistantPolicy" RENAME TO assistant_policy; ALTER TABLE "assistantUsageDaily" RENAME TO assistant_usage_daily; ``` or keep them and set `RDBMSTableBackendDetails.tableName` to the old name in your table customizer. ### Stored references to update QQQ stores table names, permission names and key names outside this qbit. Update them in the same deployment. The examples are for Postgres with QQQ's default snake_case backend names; adjust the table and column names to your schema. 1. **Security keys.** Permission grants (`assistant.hasAccess`, `assistant.admin`) need no change. If your authentication customizer grants the all-access key itself rather than calling `AssistantSecurity.applySessionKeys`, grant `assistant_user_id_all_access`. If you set `ownerSecurityKeyType` explicitly, the all-access key is now `_all_access`. 2. **Saved views and saved reports** on the assistant tables: ```sql UPDATE saved_view SET table_name = CASE table_name WHEN 'assistantConversation' THEN 'assistant_conversation' WHEN 'assistantMessage' THEN 'assistant_message' WHEN 'assistantTurn' THEN 'assistant_turn' WHEN 'assistantTurnEvent' THEN 'assistant_turn_event' WHEN 'assistantToolCall' THEN 'assistant_tool_call' WHEN 'assistantFeedback' THEN 'assistant_feedback' WHEN 'assistantPolicy' THEN 'assistant_policy' WHEN 'assistantUsageDaily' THEN 'assistant_usage_daily' ELSE table_name END WHERE table_name IN ('assistantConversation', 'assistantMessage', 'assistantTurn', 'assistantTurnEvent', 'assistantToolCall', 'assistantFeedback', 'assistantPolicy', 'assistantUsageDaily'); ``` Run the same statement against `saved_report` (and `quick_saved_view` / `shared_saved_view` only if they store a table name in your schema). 3. **Audit table names.** QQQ audits reference tables through the `audit_table` lookup. Rename the rows so old and new audits stay under one table: ```sql UPDATE audit_table SET name = CASE name WHEN 'assistantConversation' THEN 'assistant_conversation' WHEN 'assistantMessage' THEN 'assistant_message' WHEN 'assistantTurn' THEN 'assistant_turn' WHEN 'assistantTurnEvent' THEN 'assistant_turn_event' WHEN 'assistantToolCall' THEN 'assistant_tool_call' WHEN 'assistantFeedback' THEN 'assistant_feedback' WHEN 'assistantPolicy' THEN 'assistant_policy' WHEN 'assistantUsageDaily' THEN 'assistant_usage_daily' ELSE name END WHERE name IN ('assistantConversation', 'assistantMessage', 'assistantTurn', 'assistantTurnEvent', 'assistantToolCall', 'assistantFeedback', 'assistantPolicy', 'assistantUsageDaily'); ``` If a new-name row was already created (the app ran RC.3 before this update), repoint `audit.audit_table_id` from the old row to the new one first, then delete the old row. 4. **Anything else that stores a table name**: frontend links or bookmarks to `/app/.../assistantConversation`, Quick Search index rows (`quick_search_index.table_name`; reindex instead of editing), ESB topics or reports you configured by table name. ### Order Deploy RC.3 and run the statements above in the same maintenance window. Until the update runs, saved views and reports on the assistant tables do not open, and admins who get the all-access key from their own customizer only see their own rows. ## 0.1.0-RC.6: tools through the UI API Database (see `docs/schema-postgres.sql`): - new tables `assistant_data_access`, `assistant_pending_action`, `assistant_profile`, `assistant_skill` and `assistant_profile_skill`; - new columns `assistant_tool_call.ui_api_operation`, `http_status`, `audit_href`, `pending_action_id`; - new columns `assistant_policy.writes_require_confirmation`, `allowed_tools`, `max_rows_per_call`, `redact_pii`. 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.