diff --git a/docs/design/2026-11-20-flow-setting-schemas.md b/docs/design/2026-11-20-flow-setting-schemas.md index 443aea06..1f751fe9 100644 --- a/docs/design/2026-11-20-flow-setting-schemas.md +++ b/docs/design/2026-11-20-flow-setting-schemas.md @@ -2,7 +2,10 @@ ## Status -Approved (2026-11-20). Implementing. +Implemented (2026-11-20). Deployed to dev in #482 (flow settings), #484 (optional credential +fields), #485 (settings kept on a Datasets save) and #489/#490 (Runs and Results). The Sensemaking +flows were registered on the described pieces the same day. Deviations are recorded under +"Implementation deviations" and "After deploy" below. Checked against `origin/develop` at the time of writing, and against the dev catalog (`mintdevgraphql`) with read-only queries. Paths are relative to the monorepo root unless they @@ -373,12 +376,42 @@ Recorded 2026-11-20, after review. `FLOW_SETTING_INVALID` (flow check) - `FLOW_SETTINGS_UNAVAILABLE` (502 from the relay) - **Migration:** `1771300000047_configuration_flow_settings`. -- **Open:** draft-lexicon `grounding=semantic` and map-and-project `mapping_method=embedding` - cannot run, because the adapter makes every declared secret required (`step_secrets.py`, no - optional flag). Declaring `model_server` on map-and-project would force a credential on keyword - runs. Proposed: separate embedding variants of the two pieces (awaiting the user). -- **Unverified:** Hasura applying the migration; the `text[]` literal written for - `has_accepted_values`; anything live. +- **Resolved (was open):** draft-lexicon `grounding=semantic` and map-and-project + `mapping_method=embedding` could not run, because the adapter made every declared secret + required. The user chose separate variants. Embedding mapping is now its own piece, + `map-and-project-embedding` (r1), which declares `model_server`, while map-and-project stays + credential-free and no longer offers `embedding`. draft-lexicon already declared + `model_server`; it gained the embedding settings, and #484 lets a declaration mark + `embedding_base_url` optional, so keyword grounding needs no embedding address. +- **Verified after deploy:** the migration and metadata applied on dev, the `text[]` + accepted-values write works, and the run form shows explained dropdowns for the Sensemaking + flows and multi-selects for the WERC model. + +### After deploy (2026-11-20) + +- **Piece revisions on dev** (library `wmobley/Semantic-Sensemaking` `feat/setting-schemas`; the + code that runs is still upstream `6f586c7`, fetched by each piece's wrapper): + - ingest-corpus r3 + - score-lexicon, map-and-project, render-report and render-frames-report r2 + - discover-frames r3 + - draft-lexicon r4 + - map-and-project-embedding r1 +- **draft-lexicon r4** requires `problem_statement` and `chat_kind`, so a Formulation run + without them is refused before it starts instead of failing in the step. +- **ingest-corpus r3** fails the step when it keeps no documents, naming how many were skipped and + the minimum length. Before, a run whose documents were all too short was reported as completed + with an empty report. +- **Author defaults.** Narrative and Formulation default to Tejas (`openai_compatible`), with + `Meta-Llama-3.3-70B-Instruct` for chat and `E5-Mistral-7B-Instruct` for embeddings. These are + the stack's `CKAN_LLM_MODEL` and the earlier runs' embedding model. They are author values on + the flows, not library defaults, because they belong to this deployment. +- **Deviation: the ingest r3 swap was made in place.** The three flows' ingest step was pointed + at r3 directly in the catalog (one transaction), instead of registering three more flow + versions. A new version would have meant duplicate flows in the list, or deleting runs that + hold real results. Each past run's adapter plan records the pieces it actually ran, so history + stays accurate. Flows remain insert-only for users. This was an operator change. +- **Old flow versions** (seven, all tests) were deleted with their 11 test runs, at the user's + request. ## User feedback / decisions @@ -388,3 +421,9 @@ Recorded 2026-11-20, after review. - 2026-11-20: asked whether an author can hide a setting entirely: "yes". Asked whether models get dropdowns now or later: "yes now". - 2026-11-20: "ok lets do it": spec approved. +- 2026-11-20: embedding choices that could not run: the user chose separate variants ("a is fine + for now"). Asked that `openai_compatible` be shown as "Tejas". +- 2026-11-20: "we need to default to the CKAN_LLM_MODEL … and the embedding model": the Tejas + model defaults on Narrative and Formulation. +- 2026-11-20: a run that kept no documents: "both solutions are fine" (fail the ingest step; + rebind the RGV thread to the RGV transcripts). diff --git a/ui-react/docs/docs/assets/images/credentials-show-value.png b/ui-react/docs/docs/assets/images/credentials-show-value.png new file mode 100644 index 00000000..8a338bb1 Binary files /dev/null and b/ui-react/docs/docs/assets/images/credentials-show-value.png differ diff --git a/ui-react/docs/docs/assets/images/flow-run-panel.png b/ui-react/docs/docs/assets/images/flow-run-panel.png deleted file mode 100644 index e0b55eda..00000000 Binary files a/ui-react/docs/docs/assets/images/flow-run-panel.png and /dev/null differ diff --git a/ui-react/docs/docs/assets/images/flow-settings-form.png b/ui-react/docs/docs/assets/images/flow-settings-form.png new file mode 100644 index 00000000..809f0998 Binary files /dev/null and b/ui-react/docs/docs/assets/images/flow-settings-form.png differ diff --git a/ui-react/docs/docs/assets/images/results-collection-input.png b/ui-react/docs/docs/assets/images/results-collection-input.png deleted file mode 100644 index 51478867..00000000 Binary files a/ui-react/docs/docs/assets/images/results-collection-input.png and /dev/null differ diff --git a/ui-react/docs/docs/facilitator/run-a-flow.md b/ui-react/docs/docs/facilitator/run-a-flow.md index 6f097c06..3a0db7df 100644 --- a/ui-react/docs/docs/facilitator/run-a-flow.md +++ b/ui-react/docs/docs/facilitator/run-a-flow.md @@ -46,6 +46,8 @@ Review each setting. Each shows a readable title and an explanation. The form fi - **A yes or no** is a tick box. - **Anything else** is a text box. +![The settings of the Narrative flow: two dropdowns with the chosen option explained under each, a number box with its limit and default, and Advanced settings closed](../assets/images/flow-settings-form.png) + Rarely changed settings are inside **Advanced settings**, which is closed until you open it. Settings the flow's author hid are not shown at all, and the run uses the author's value for them. A setting the author has fixed is listed under *Expert modeler has selected the following parameters* with its value, and you cannot change it. If something sends a value for a fixed or hidden setting anyway, the run is refused with *A setting is fixed or hidden by the flow*. If a required setting has no value, the run is not started. The message says *This flow needs a setting filled in*, and names the settings. Fill them in, save, and run again. diff --git a/ui-react/docs/docs/saved-credentials.md b/ui-react/docs/docs/saved-credentials.md index 8dbc040e..44cf502e 100644 --- a/ui-react/docs/docs/saved-credentials.md +++ b/ui-react/docs/docs/saved-credentials.md @@ -24,7 +24,13 @@ The page lists the credentials you have saved. For each one it shows its name, i A credential can hold at most 4096 bytes in total, counting names and values together. -The value box is a password field. After a successful save the form clears every value, and the list shows the credential's name and field names only. +The value box is a password field. To check what you typed before saving, select the eye button beside it; it shows only what is in the box, never a value already saved. Select it again to hide the value. + +Under a value, a note appears if it starts or ends with a space, or with a quote mark. Spaces at either end are removed when you save, because they are never part of a key or an address. A quote mark is kept, so remove it yourself unless it belongs to the value. A key pasted with a stray space or quote is a common reason a model server refuses a key that looks right. + +![Adding a model server credential: the first value shown in clear with the eye button, and the note that it starts with a space](assets/images/credentials-show-value.png) + +After a successful save the form clears every value, and the list shows the credential's name and field names only. ### Add a model server