feat: add extraction schema, sidebar nav, few-shot prompting, and prompt settings
Overhaul extraction pipeline with new TradeItem model, conversation flow, and dedicated extraction endpoint. Add sidebar navigation with NavMenu component and landing page. Introduce few-shot prompting service and tests. Add prompt settings and email upload specs. Update OpenSpec tooling with improved export-spec and extract-feature commands. Archive completed changes and export full specs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
local
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-04-05
|
||||
@@ -0,0 +1,51 @@
|
||||
## Context
|
||||
|
||||
The chat page currently has a single-panel layout: message list + input. The system prompt is absent (no system message in ChatHistory), and model parameters like temperature use Semantic Kernel defaults. For prompt engineering and debugging, these need to be editable in the UI without restarting the server.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Tabbed UI: Chat, System Prompt, Model Settings — all on the same page
|
||||
- System prompt and model settings sent with each chat request
|
||||
- Backend applies them to SK's ChatHistory and OpenAIPromptExecutionSettings
|
||||
- Settings persist in the browser session (survive tab switches, not page reloads)
|
||||
|
||||
**Non-Goals:**
|
||||
- Persisting settings to disk or server (future — save/load prompt profiles)
|
||||
- Phase 2 prompt templates and few-shot examples (scoped in proposal, not implemented here)
|
||||
- Changing the SSE streaming contract
|
||||
|
||||
## Decisions
|
||||
|
||||
### Tabbed layout using MudTabs
|
||||
- Use `MudTabs` with `MudTabPanel` for each section: Chat, System Prompt, Model Settings
|
||||
- **Alternative considered**: MudDrawer panels or separate pages. Rejected because tabs keep everything on one page — switching between prompt and chat should be instant with no navigation.
|
||||
- The Chat tab contains the existing message list and input (unchanged)
|
||||
- System Prompt tab: a `MudTextField` with `Lines="10"` for multi-line editing
|
||||
- Model Settings tab: `MudNumericField` or `MudSlider` for Temperature (0.0–2.0), TopP (0.0–1.0), MaxTokens (1–4096)
|
||||
|
||||
### Settings sent per-request, not stored server-side
|
||||
- `ChatRequest` gains optional `SystemPrompt` (string?) and `Settings` (ModelSettings?) properties
|
||||
- Backend treats them as nullable — if absent, defaults apply (no system prompt, SK default temperature)
|
||||
- This keeps the API stateless and avoids server-side session management
|
||||
- **Alternative considered**: Server-side settings endpoint. Rejected — adds complexity for a single-user debugging tool.
|
||||
|
||||
### ModelSettings as a shared DTO
|
||||
- New `ModelSettings.cs` in Shared/Models with `Temperature` (double?), `TopP` (double?), `MaxTokens` (int?)
|
||||
- All fields nullable — only set values override defaults
|
||||
- Maps directly to `OpenAIPromptExecutionSettings` properties on the backend
|
||||
|
||||
### System prompt applied as ChatHistory system message
|
||||
- `chatHistory.AddSystemMessage(request.SystemPrompt)` as the first entry before user/assistant messages
|
||||
- SK and OpenAI APIs treat the system message as behavioral instructions for the model
|
||||
|
||||
### Tab state persists in component fields
|
||||
- `_systemPrompt` and `_modelSettings` are component-level fields, not per-tab
|
||||
- Switching tabs doesn't reset values (MudTabs preserves panel content by default)
|
||||
- Values are lost on page refresh — acceptable for a debugging tool
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **[Tab switch loses scroll position]** → MudTabs renders all panels but hides inactive ones, so scroll position in the chat tab is preserved
|
||||
- **[Large system prompts inflate request size]** → Acceptable for single-user debugging; no size limit enforced
|
||||
- **[Temperature/TopP interaction]** → Standard OpenAI behavior: setting both is allowed but not recommended. Show a note in the UI, don't enforce.
|
||||
@@ -0,0 +1,35 @@
|
||||
## Why
|
||||
|
||||
When testing and debugging the AI chat agent, the system prompt and model parameters (temperature, top-p, max tokens) are hardcoded or absent. Exposing these in the UI lets the developer iterate on prompt engineering without restarting the server, and makes the app useful as a prompt testing workbench.
|
||||
|
||||
## What Changes
|
||||
|
||||
### Phase 1: Expose system prompt and model parameters
|
||||
- Add tabbed UI to the chat page: **Chat** tab (existing conversation), **System Prompt** tab (editable text area), **Model Settings** tab (temperature, top-p, max tokens sliders/inputs)
|
||||
- Extend the API contract: `ChatRequest` gains optional `SystemPrompt` and `ModelSettings` fields
|
||||
- Backend applies the system prompt as the first message in ChatHistory and passes model settings to execution settings
|
||||
|
||||
### Phase 2: Prompt templates with few-shot examples (future)
|
||||
- System prompt becomes a template with placeholder variables
|
||||
- UI for adding few-shot input/output example pairs
|
||||
- Template engine generates the final system prompt from template + examples
|
||||
- *Phase 2 is scoped but NOT implemented in this change*
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `prompt-settings-ui`: Tabbed interface for system prompt editing and model parameter controls
|
||||
- `prompt-settings-api`: API contract extensions for system prompt and model parameters
|
||||
|
||||
### Modified Capabilities
|
||||
- `chat-ui`: Chat page changes from single-panel to tabbed layout
|
||||
- `chat-streaming`: API accepts optional system prompt and model settings in the request
|
||||
|
||||
## Impact
|
||||
|
||||
- **ChatRequest.cs** (Shared): Add `SystemPrompt` and `ModelSettings` properties
|
||||
- **New ModelSettings.cs** (Shared): Temperature, TopP, MaxTokens model
|
||||
- **ChatController.cs** (API): Apply system prompt to ChatHistory, pass model settings to execution settings
|
||||
- **Chat.razor** (Client): Wrap in MudTabs, add System Prompt and Model Settings tab panels
|
||||
- **ChatApiClient.cs** (Client): Pass new fields in requests
|
||||
- No new packages — MudTabs, MudTextField, MudSlider are all part of MudBlazor
|
||||
@@ -0,0 +1,20 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Chat endpoint proxies to Responses API
|
||||
|
||||
The API backend SHALL expose `POST /api/chat` that accepts a `ChatRequest` containing messages, an optional system prompt, and optional model settings. The request is processed using a Semantic Kernel chat completion service. When a system prompt is provided, it SHALL be added as the first system message in the ChatHistory. When model settings are provided, non-null values SHALL be applied to the execution settings.
|
||||
|
||||
#### Scenario: Successful chat request with system prompt
|
||||
|
||||
- **WHEN** the client sends a POST to `/api/chat` with messages and a system prompt
|
||||
- **THEN** the API creates a ChatHistory with the system prompt as the first message, followed by the conversation messages, and processes them through Semantic Kernel
|
||||
|
||||
#### Scenario: Successful chat request with model settings
|
||||
|
||||
- **WHEN** the client sends a POST to `/api/chat` with messages and model settings (e.g., Temperature=0.3)
|
||||
- **THEN** the API applies the settings to OpenAIPromptExecutionSettings before calling the Semantic Kernel
|
||||
|
||||
#### Scenario: Successful chat request without optional fields
|
||||
|
||||
- **WHEN** the client sends a POST to `/api/chat` with only messages (no system prompt, no settings)
|
||||
- **THEN** the API processes the request with default behavior (no system message, default execution settings)
|
||||
@@ -0,0 +1,15 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Chat page is default route
|
||||
|
||||
The chat page SHALL be routed at `/sales-assistant` (or `/` with redirect). The page content SHALL be wrapped in a MudTabs container with the conversation UI in the first tab panel.
|
||||
|
||||
#### Scenario: Page loads with chat tab active
|
||||
|
||||
- **WHEN** the user navigates to the chat page
|
||||
- **THEN** the Chat tab is active showing the message list and input area
|
||||
|
||||
#### Scenario: Chat functionality unchanged
|
||||
|
||||
- **WHEN** the user sends a message from the Chat tab
|
||||
- **THEN** the assistant response streams in exactly as before, with the same SSE contract and rendering behavior
|
||||
@@ -0,0 +1,43 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: ModelSettings shared model
|
||||
|
||||
The Shared project SHALL define a `ModelSettings` class with nullable properties: `Temperature` (double?), `TopP` (double?), `MaxTokens` (int?). Null values indicate "use server default".
|
||||
|
||||
#### Scenario: All fields null
|
||||
|
||||
- **WHEN** a ModelSettings instance has all null fields
|
||||
- **THEN** the backend uses Semantic Kernel default values for all parameters
|
||||
|
||||
#### Scenario: Partial override
|
||||
|
||||
- **WHEN** a ModelSettings instance has Temperature set but TopP and MaxTokens null
|
||||
- **THEN** only Temperature is overridden; other parameters use defaults
|
||||
|
||||
### Requirement: System prompt in chat request
|
||||
|
||||
The `ChatRequest` SHALL accept an optional `SystemPrompt` (string?) property. When present and non-empty, the backend SHALL insert it as the first system message in the ChatHistory before user/assistant messages.
|
||||
|
||||
#### Scenario: System prompt provided
|
||||
|
||||
- **WHEN** a ChatRequest includes a non-empty SystemPrompt
|
||||
- **THEN** the ChatHistory starts with a system message containing that text, followed by the conversation messages
|
||||
|
||||
#### Scenario: System prompt absent
|
||||
|
||||
- **WHEN** a ChatRequest has a null or empty SystemPrompt
|
||||
- **THEN** the ChatHistory contains only user and assistant messages (no system message)
|
||||
|
||||
### Requirement: Model settings in chat request
|
||||
|
||||
The `ChatRequest` SHALL accept an optional `Settings` (ModelSettings?) property. When present, the backend SHALL apply non-null values to `OpenAIPromptExecutionSettings` before calling the Semantic Kernel.
|
||||
|
||||
#### Scenario: Temperature override
|
||||
|
||||
- **WHEN** a ChatRequest includes Settings with Temperature = 0.5
|
||||
- **THEN** the OpenAIPromptExecutionSettings.Temperature is set to 0.5
|
||||
|
||||
#### Scenario: No settings provided
|
||||
|
||||
- **WHEN** a ChatRequest has null Settings
|
||||
- **THEN** the backend uses default OpenAIPromptExecutionSettings (only FunctionChoiceBehavior.Auto is set)
|
||||
@@ -0,0 +1,53 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: System prompt editor tab
|
||||
|
||||
The chat page SHALL include a "System Prompt" tab with a multi-line text area where the user can enter a system prompt. The system prompt value SHALL persist across tab switches within the same session.
|
||||
|
||||
#### Scenario: User enters a system prompt
|
||||
|
||||
- **WHEN** the user navigates to the System Prompt tab and types text
|
||||
- **THEN** the text is stored in the component state and included in the next chat request
|
||||
|
||||
#### Scenario: System prompt survives tab switch
|
||||
|
||||
- **WHEN** the user enters a system prompt, switches to the Chat tab, then switches back
|
||||
- **THEN** the system prompt text is unchanged
|
||||
|
||||
### Requirement: Model settings tab
|
||||
|
||||
The chat page SHALL include a "Model Settings" tab with controls for Temperature, TopP, and MaxTokens. Each control SHALL display its current value and allow adjustment within valid ranges.
|
||||
|
||||
#### Scenario: Temperature control
|
||||
|
||||
- **WHEN** the user adjusts the Temperature control
|
||||
- **THEN** the value is constrained to 0.0–2.0 and included in the next chat request's settings
|
||||
|
||||
#### Scenario: TopP control
|
||||
|
||||
- **WHEN** the user adjusts the TopP control
|
||||
- **THEN** the value is constrained to 0.0–1.0 and included in the next chat request's settings
|
||||
|
||||
#### Scenario: MaxTokens control
|
||||
|
||||
- **WHEN** the user sets the MaxTokens value
|
||||
- **THEN** the value is constrained to 1–4096 and included in the next chat request's settings
|
||||
|
||||
#### Scenario: Default values
|
||||
|
||||
- **WHEN** the user has not changed any model settings
|
||||
- **THEN** the controls show default values (Temperature: 1.0, TopP: 1.0, MaxTokens: empty/unset) and no overrides are sent to the API
|
||||
|
||||
### Requirement: Tabbed page layout
|
||||
|
||||
The chat page SHALL use MudTabs with three tab panels: "Chat" (the existing conversation UI), "System Prompt" (the prompt editor), and "Model Settings" (the parameter controls).
|
||||
|
||||
#### Scenario: Chat tab is default
|
||||
|
||||
- **WHEN** the page loads
|
||||
- **THEN** the Chat tab is active and the conversation UI is displayed
|
||||
|
||||
#### Scenario: Tab switching
|
||||
|
||||
- **WHEN** the user clicks a different tab
|
||||
- **THEN** the corresponding panel is displayed and the previous panel is hidden but retains its state
|
||||
@@ -0,0 +1,40 @@
|
||||
## 1. Shared Models
|
||||
|
||||
- [x] 1.1 Create `ModelSettings.cs` in Shared/Models — `double? Temperature`, `double? TopP`, `int? MaxTokens`
|
||||
- [x] 1.2 Add `string? SystemPrompt` and `ModelSettings? Settings` properties to `ChatRequest.cs`
|
||||
|
||||
## 2. API Backend
|
||||
|
||||
- [x] 2.1 Update `ChatController.Post()` — if `request.SystemPrompt` is non-empty, call `chatHistory.AddSystemMessage(request.SystemPrompt)` before adding user/assistant messages
|
||||
- [x] 2.2 Update `ChatController.Post()` — if `request.Settings` is non-null, apply non-null Temperature, TopP, MaxTokens to `OpenAIPromptExecutionSettings`
|
||||
|
||||
## 3. Client UI — Tabbed Layout
|
||||
|
||||
- [x] 3.1 Wrap the existing Chat.razor content (chat-container div) inside `<MudTabs>` with three `<MudTabPanel>` elements: "Chat", "System Prompt", "Model Settings"
|
||||
- [x] 3.2 Add component fields: `_systemPrompt` (string), `_temperature` (double?), `_topP` (double?), `_maxTokens` (int?)
|
||||
|
||||
## 4. System Prompt Tab
|
||||
|
||||
- [x] 4.1 Add a `MudTextField` with `Lines="10"`, `Variant="Variant.Outlined"`, bound to `_systemPrompt`, with placeholder text explaining what a system prompt does
|
||||
- [x] 4.2 Include the `_systemPrompt` value in the `ChatRequest` built by `SendMessage()`
|
||||
|
||||
## 5. Model Settings Tab
|
||||
|
||||
- [x] 5.1 Add `MudNumericField<double?>` for Temperature (min 0.0, max 2.0, step 0.1) with label and helper text
|
||||
- [x] 5.2 Add `MudNumericField<double?>` for TopP (min 0.0, max 1.0, step 0.1) with label and helper text
|
||||
- [x] 5.3 Add `MudNumericField<int?>` for MaxTokens (min 1, max 4096) with label and helper text
|
||||
- [x] 5.4 Include the model settings in the `ChatRequest` built by `SendMessage()`
|
||||
|
||||
## 6. Client Service
|
||||
|
||||
- [x] 6.1 Verify `ChatApiClient.SendChatStreamingAsync()` serializes the new `ChatRequest` fields correctly (SystemPrompt, Settings) — no changes expected since it already serializes the full object
|
||||
|
||||
## 7. Styling
|
||||
|
||||
- [x] 7.1 Adjust `Chat.razor.css` — the chat-container height calc needs to account for the MudTabs header height (~48px). The tabs header sits inside the content area below the AppBar.
|
||||
|
||||
## 8. Verification
|
||||
|
||||
- [x] 8.1 Build the solution (`dotnet build`) and confirm no compilation errors
|
||||
- [x] 8.2 Run existing tests (`dotnet test`) and confirm they pass
|
||||
- [x] 8.3 Update any tests that construct `ChatRequest` if the new nullable fields cause issues — no updates needed, nullable fields don't break existing tests
|
||||
Reference in New Issue
Block a user