HCI Ambiguity-Aware NL2SQL Frontend

A React frontend for an HCI-powered, interactive ambiguity-aware NL2SQL workflow. Phase 3 adds a progressively revealed intention-tree viewer beside the existing one-question-at-a-time clarification flow.

The real tree API is not finalized. The current implementation therefore uses a deterministic pancreas waiting-list mock behind the stable Nl2SqlService and intention-tree adapter boundaries; it does not invent browser endpoints or backend fields.

Phase 3 Demo

Use the Transplant Allocation PostgreSQL database and submit:

I need the pancreas waiting list, sorted correctly for all the pending matches. Show me the patient's ID, region, urgency status, the HLA mismatch number, and their rank.

This is a fixed mock, not a branching inference demo. Any structurally valid answer advances through the same 16 questions, tree snapshots, GT SQL, and five-row result fixture. Submitted answers still appear in expandable history nodes, and either escape option marks that answered node as an issue.

The exact presentation selections are documented in ../3rd iteration/demo happy path.txt.

Current Flow

1. Select a database and SQL dialect.
2. Enter the pancreas waiting-list query.
3. Answer one clarification question at a time.
4. Follow the green Answering node as each successful response replaces the full tree snapshot.
5. Expand gray Answered nodes to inspect the original options, submitted answer, and an available source-backed SQL snippet.
6. Pan or zoom the fixed tree canvas, or use Zoom in, Zoom out, Fit tree, and Locate current question.
7. After question 16, inspect the final read-only SQL and five-row result preview beside the completed tree.

The initial snapshot contains all nine top-level intentions and question 1, but does not reveal the later 8.x or 9.x details. The viewer uses a white grid canvas and lays hierarchy depth out from left to right while keeping a fixed desktop/mobile height. Grouping questions place each full option label above its group selector and stack their two main sections when the component becomes narrow.

Tech Stack

• React 19, Vite, and TypeScript
• Local shadcn-compatible UI components under src/components/ui
• @xyflow/react for the read-only tree viewport and controls
• Lucide React icons
• useReducer workflow state
• Vitest, React Testing Library, and Oxlint

Key Boundaries

src/
├── App.tsx
├── app/query-reducer.ts
├── components/intention-tree/
│   ├── intention-tree-panel.tsx
│   ├── intention-tree-node.tsx
│   ├── question-tree-node.tsx
│   ├── answered-question-details.tsx
│   ├── tree-controls.tsx
│   └── tree-layout.ts
├── mocks/
│   ├── catalog.ts
│   └── pancreas-intention-tree.ts
└── services/nl2sql/
    ├── intention-tree-adapter.ts
    ├── mock-service.ts
    └── types.ts

• query-reducer.ts owns session transitions, pending submissions, history, and the latest complete tree snapshot.
• intention-tree-adapter.ts validates snapshot references and status invariants while dropping raw agent or trace fields.
• pancreas-intention-tree.ts holds the stable 16-question catalog and builds each complete snapshot from per-step visibility.
• components/intention-tree is the only layer that depends on React Flow types.
• App.tsx composes the full-row original query and the responsive 45/55 task/Answer progress workspace.

Data Boundaries

• Only successful analyze or resolve responses update the tree.
• A submitted answer stays pending until resolve succeeds; failed responses do not advance history or the tree.
• Snapshots with duplicate IDs, broken references, an invalid answering node, or an invalid status are rejected.
• Revisions must increase before a snapshot can replace the current tree.
• SQL snippets are optional. The mock includes only the seven snippets explicitly provided by the motivating example and does not infer 8.x or 9.x snippets from the final SQL.
• The result has the five GT SQL projection columns and a fixed five-row fixture sampled and correlated from organ_transplant_large.sql. The browser neither reads that dump nor runs a database at demo time.
• Agent names, schema, KB context, SQL diffs, and diagnostic traces do not enter the rendered domain model.

Commands

npm install
npm run dev
npm test
npm run lint
npm run build

Backend Integration

The frontend continues to depend on:

interface Nl2SqlService {
  listDatabases(): Promise<DatabaseOption[]>
  analyze(input: AnalyzeInput): Promise<TurnResponse>
  resolve(input: ResolveInput): Promise<TurnResponse>
  executeReadonly(input: ExecuteInput): Promise<QueryExecution>
}

http-service.ts remains an unconfigured skeleton until the backend publishes the browser API, session behavior, full tree payload, and error contract. If the backend later returns patches, the service/adapter layer must reconstruct a complete validated snapshot before the reducer or UI receives it.

Not Implemented

• real HTTP tree endpoints or incremental tree merging;
• branching mock behavior;
• editing, moving, deleting, or reconnecting individual tree nodes;
• MiniMap, tree search, cross-query tree history, or HCI telemetry;
• modifying submitted answers, rationale collection, or retry UX;
• inferred SQL snippets or fabricated patient rows.