busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat(ui): add chat-driven dataset review flow

Browse Source 
Move dataset review clarification into the assistant workspace and
rework the review page into a chat-centric layout with execution rails.

Add session-scoped assistant actions for mappings, semantic fields,
and SQL preview generation. Introduce optimistic locking for dataset
review mutations, propagate session versions through API responses,
and mask imported filter values before assistant exposure.

Refresh tests, i18n, and spec artifacts to match the new workflow.

BREAKING CHANGE: dataset review mutation endpoints now require the
X-Session-Version header, and clarification is no longer handled
through ClarificationDialog-based flows
This commit is contained in:
busya
2026-03-26 13:33:12 +03:00
parent d7911fb2f1
commit 7c85552132
74 changed files with 6122 additions and 2970 deletions
Download Patch File Download Diff File Expand all files Collapse all files

93
specs/027-dataset-llm-orchestration/contracts/modules.md
View File

@@ -19,6 +19,7 @@ This document defines the semantic contracts for the core components of the Data
# @RELATION: [DEPENDS_ON] ->[SupersetContextExtractor]
# @RELATION: [DEPENDS_ON] ->[SupersetCompilationAdapter]
# @RELATION: [DEPENDS_ON] ->[TaskManager]
# @RELATION: [EXPOSES_STATE_TO] ->[AssistantApi]
# @PRE: session mutations must execute inside a persisted session boundary scoped to one authenticated user.
# @POST: state transitions are persisted atomically and emit observable progress for long-running steps.
# @SIDE_EFFECT: creates task records, updates session aggregates, triggers upstream Superset calls, persists audit artifacts.
@@ -148,15 +149,16 @@ This document defines the semantic contracts for the core components of the Data
# [DEF:ClarificationEngine:Module]
# @COMPLEXITY: 4
# @PURPOSE: Manage one-question-at-a-time clarification sessions, including prioritization, answer persistence, and readiness impact updates.
# @PURPOSE: Manage mixed-initiative clarification sessions, including prioritized agent prompts, answer persistence, assistant routing, and readiness impact updates.
# @LAYER: Domain
# @RELATION: [DEPENDS_ON] ->[ClarificationSession]
# @RELATION: [DEPENDS_ON] ->[ClarificationQuestion]
# @RELATION: [DEPENDS_ON] ->[ClarificationAnswer]
# @RELATION: [DEPENDS_ON] ->[ValidationFinding]
# @RELATION: [DISPATCHES] ->[AssistantChatPanel]
# @PRE: target session contains unresolved or contradictory review state.
# @POST: every recorded answer updates the clarification session and associated session state deterministically.
# @SIDE_EFFECT: creates clarification questions, persists answers, updates findings/profile state.
# @POST: every recorded answer updates the clarification session and associated session state deterministically, and the next agent prompt is routable through assistant chat.
# @SIDE_EFFECT: creates clarification questions, persists answers, updates findings/profile state, emits assistant-routable clarification prompts.
# @DATA_CONTRACT: Input[ClarificationSessionState | ClarificationAnswerCommand] -> Output[ClarificationQuestionPayload | ClarificationProgressSnapshot | SessionReadinessDelta]
# @INVARIANT: Clarification answers are persisted before the current question pointer or readiness state is advanced.
# @TEST_CONTRACT: next_question_selection -> returns only one highest-priority unresolved question at a time
@@ -170,7 +172,7 @@ This document defines the semantic contracts for the core components of the Data
# @PURPOSE: Open clarification mode on the highest-priority unresolved question.
#### ƒ **build_question_payload**
# @PURPOSE: Return question, why-it-matters text, current guess, and suggested options.
# @PURPOSE: Return question, why-it-matters text, current guess, and suggested options for assistant-chat delivery.
#### ƒ **record_answer**
# @PURPOSE: Persist one answer and compute state impact.
@@ -253,19 +255,20 @@ This document defines the semantic contracts for the core components of the Data
<!-- [DEF:DatasetReviewWorkspace:Component] -->
<!-- @COMPLEXITY: 5 -->
<!-- @PURPOSE: Main dataset review workspace coordinating session state, progressive recovery, semantic review, clarification, preview, and launch UX. -->
<!-- @PURPOSE: Main dataset review workspace coordinating session state, progressive recovery, semantic review, assistant-chat clarification, preview, and launch UX. -->
<!-- @LAYER: UI -->
<!-- @RELATION: [BINDS_TO] ->[api_module] -->
<!-- @RELATION: [BINDS_TO] ->[assistantChat] -->
<!-- @RELATION: [BINDS_TO] ->[AssistantApi] -->
<!-- @RELATION: [BINDS_TO] ->[AssistantChatPanel] -->
<!-- @RELATION: [BINDS_TO] ->[taskDrawer] -->
<!-- @UX_STATE: Empty -> Show source intake with Superset link and dataset-selection entry actions. -->
<!-- @UX_STATE: Importing -> Show progressive recovery milestones as context is assembled. -->
<!-- @UX_STATE: Review -> Show summary, findings, semantic layer, filters, mapping, and next action. -->
<!-- @UX_STATE: Clarification -> Focus the user on one current clarification question while preserving wider session context. -->
<!-- @UX_STATE: Clarification -> Focus the user on one current assistant-led clarification thread while preserving wider session context. -->
<!-- @UX_STATE: Ready -> Show launch summary and unambiguous run-ready signal without hiding warnings. -->
<!-- @UX_FEEDBACK: Main CTA changes by readiness state and reflects current highest-value next action. -->
<!-- @UX_RECOVERY: Users can save, resume, or reopen an unfinished session without losing context. -->
<!-- @UX_REACTIVITY: Uses Svelte runes for session, readiness, preview, and task state derivation. -->
<!-- @UX_REACTIVITY: Uses Svelte runes for session, readiness, preview, task state derivation, and assistant/workspace focus synchronization. -->
<!-- @INVARIANT: Navigation away from dirty session state must require explicit confirmation. -->
<!-- @TEST_CONTRACT: workspace_state_machine -> one and only one major readiness-driven CTA is primary at a time -->
<!-- @TEST_SCENARIO: resume_preserves_state -> reopening unfinished session restores current panel state and next action -->
@@ -291,6 +294,55 @@ This document defines the semantic contracts for the core components of the Data
---
<!-- [DEF:AssistantChatPanel:Component] -->
<!-- @COMPLEXITY: 4 -->
<!-- @PURPOSE: Provide the mixed-initiative assistant drawer for clarification, free-form dataset questions, contextual actions, and confirmation cards tied to the active dataset review session. -->
<!-- @LAYER: UI -->
<!-- @RELATION: [DEPENDS_ON] ->[AssistantApi] -->
<!-- @RELATION: [BINDS_TO] ->[DatasetReviewWorkspace] -->
<!-- @RELATION: [BINDS_TO] ->[ClarificationEngine] -->
<!-- @UX_STATE: Idle -> Drawer is closed or shows starter prompts for the active session. -->
<!-- @UX_STATE: ClarificationQueue -> Assistant presents the next prioritized clarification prompt with suggested answers. -->
<!-- @UX_STATE: Freeform -> User asks context questions about filters, findings, mappings, or SQL preview state. -->
<!-- @UX_STATE: NeedsConfirmation -> Chat renders confirmation cards for dangerous or audit-relevant actions. -->
<!-- @UX_STATE: Error -> Drawer preserves session context and shows retry guidance without hiding the workspace. -->
<!-- @UX_FEEDBACK: Context actions and assistant prompts highlight the referenced workspace filter, field, mapping, or finding. -->
<!-- @UX_RECOVERY: Users can skip, defer, resume, or abandon a clarification thread without losing session state. -->
#### ƒ **submitSessionScopedMessage**
<!-- @PURPOSE: Send a free-form or guided assistant message bound to the active dataset review session. -->
#### ƒ **renderConfirmationCard**
<!-- @PURPOSE: Present assistant-driven confirmation UI for state-changing actions such as mapping approval, preview generation, or launch. -->
#### ƒ **highlightWorkspaceTarget**
<!-- @PURPOSE: Synchronize assistant focus with the referenced workspace element. -->
<!-- [/DEF:AssistantChatPanel:Component] -->
---
<!-- [DEF:AssistantApi:Module] -->
<!-- @COMPLEXITY: 4 -->
<!-- @PURPOSE: Accept session-scoped assistant messages and route grounded dataset-review intents to orchestration contracts without bypassing approval gates. -->
<!-- @LAYER: UI -->
<!-- @RELATION: [DEPENDS_ON] ->[DatasetReviewOrchestrator] -->
<!-- @RELATION: [DEPENDS_ON] ->[ClarificationEngine] -->
<!-- @RELATION: [DEPENDS_ON] ->[DatasetReviewSessionRepository] -->
<!-- @PRE: Assistant requests are authenticated and may include an active dataset review session identifier. -->
<!-- @POST: Responses stay grounded in the current session context and return deterministic confirmation or action states for frontend rendering. -->
<!-- @SIDE_EFFECT: Reads session state, may dispatch approved orchestration commands, and records assistant interaction outcomes through existing audit pathways. -->
#### ƒ **handleSessionScopedMessage**
<!-- @PURPOSE: Load active dataset review context and answer or route a user assistant message against that session. -->
#### ƒ **dispatchDatasetReviewIntent**
<!-- @PURPOSE: Route approved dataset-review commands such as mapping approval or preview generation to orchestration services. -->
<!-- [/DEF:AssistantApi:Module] -->
---
<!-- [DEF:SourceIntakePanel:Component] -->
<!-- @COMPLEXITY: 3 -->
<!-- @PURPOSE: Collect initial dataset source input through Superset link paste or dataset selection entry paths. -->
@@ -356,28 +408,9 @@ This document defines the semantic contracts for the core components of the Data
---
<!-- [DEF:ClarificationDialog:Component] -->
<!-- @COMPLEXITY: 3 -->
<!-- @PURPOSE: One-question-at-a-time clarification surface for unresolved or contradictory dataset meanings. -->
<!-- @LAYER: UI -->
<!-- @RELATION: [BINDS_TO] ->[api_module] -->
<!-- @RELATION: [BINDS_TO] ->[assistantChat] -->
<!-- @UX_STATE: Question -> Show current question, why-it-matters text, current guess, and selectable answers. -->
<!-- @UX_STATE: Saving -> Disable controls while persisting answer. -->
<!-- @UX_STATE: Completed -> Show clarification summary and impact on readiness. -->
<!-- @UX_FEEDBACK: Each answer updates profile and findings without forcing a full page reload. -->
<!-- @UX_RECOVERY: Users can skip, defer to expert review, pause, and resume later. -->
### Retired Contract: `ClarificationDialog`
#### ƒ **submitAnswer**
<!-- @PURPOSE: Save selected or custom clarification answer. -->
#### ƒ **skipQuestion**
<!-- @PURPOSE: Defer the current question while keeping it unresolved. -->
#### ƒ **pauseClarification**
<!-- @PURPOSE: Exit clarification mode without losing prior answers. -->
<!-- [/DEF:ClarificationDialog:Component] -->
`ClarificationDialog` is retired for feature 027 rebaseline. Its responsibilities move into `AssistantChatPanel`, which now owns clarification presentation, free-form dataset questions, and confirmation-card interactions inside the global assistant drawer.
---
@@ -460,4 +493,4 @@ These contracts are intended to align directly with:
- [`specs/027-dataset-llm-orchestration/spec.md`](../spec.md)
- [`specs/027-dataset-llm-orchestration/ux_reference.md`](../ux_reference.md)
- [`specs/027-dataset-llm-orchestration/research.md`](../research.md)
- [`specs/027-dataset-llm-orchestration/data-model.md`](../data-model.md)
- [`specs/027-dataset-llm-orchestration/data-model.md`](../data-model.md)