Skip to content

structured-output-enhanced-ui.md

Latest commit

 

History

History
245 lines (173 loc) · 6.67 KB

structured-output-enhanced-ui.md

File metadata and controls

245 lines (173 loc) · 6.67 KB

Structured Output Enhanced UI Implementation

Overview

This document describes the enhanced user interface implementation for the structured output feature, addressing all user requirements for a seamless experience.

Features Implemented

1. Always-Visible Button

The structured output button is now always visible in the chat input, providing different states based on context:

  • Purpose: Educate users about the feature and guide them through the requirements
  • Behavior: Shows appropriate icon and tooltip based on current state
  • Implementation: Removed conditional hiding logic

2. State-Based User Experience

No VT+ Subscription

  • Icon: 🔒 Lock
  • Tooltip: "Structured Output requires VT+ subscription"
  • Click Action: Shows upgrade dialog with pricing page redirect

No Document Attached

  • Icon: 📤 Upload
  • Tooltip: "Upload a PDF document to extract structured data"
  • Click Action: Shows guide dialog explaining how to use the feature

Non-Gemini Model

  • Icon: ℹ️ Info
  • Tooltip: "Switch to Gemini model to use structured output"
  • Click Action: Shows dialog explaining Gemini requirement

Unsupported Document Type

  • Icon: 💡 Lightbulb (dimmed)
  • Tooltip: "Only PDF documents are supported"
  • Click Action: Shows toast notification about PDF requirement

Ready to Extract

  • Icon: 💡 Lightbulb
  • Tooltip: "Extract structured data from PDF (Gemini only)"
  • Click Action: Executes extraction with predefined prompt

Extraction Complete

  • Icon: ✅ Green Lightbulb
  • Tooltip: "Structured data extracted from [filename]"
  • Click Action: Re-extracts or shows options

3. Human-in-the-Loop Pattern

Following the AI SDK's human-in-the-loop pattern:

// User action required for each state
if (!hasStructuredOutputAccess) {
    // Show upgrade dialog
    setShowDialog(true);
    return;
}

if (!hasDocument) {
    // Show guide dialog
    setShowDialog(true);
    return;
}

if (!isGeminiModel) {
    // Show model switch dialog
    setShowDialog(true);
    return;
}

// All checks passed - proceed with extraction
extractStructuredOutput();

4. Predefined Prompt Integration

The feature uses the specified predefined prompt:

const basePrompt = 'Extract structured data from the document and return it in JSON format';

// Enhanced with context
const { object } = await generateObject({
    model: google(chatMode),
    schema,
    prompt: `${basePrompt}

Please extract structured data from the following ${type} document.
Be thorough and accurate, extracting all relevant information.
If any field is not present in the document, omit it or mark it as optional.
${customSchema ? 'Follow the provided custom schema structure exactly.' : ''}

Document content:
${documentText}`,
});

5. Custom Schema Builder Integration

VT+ Exclusive Feature

  • Access: Only available for VT+ subscribers
  • Integration: Seamless modal experience within the structured output flow
  • Validation: Proper Zod schema validation and error handling

User Flow

  1. Click structured output button (when eligible)
  2. View information dialog with feature explanation
  3. Optional: Click "Create Custom Schema (VT+ Only)" button
  4. Build custom schema in modal dialog
  5. Apply custom schema for extraction

6. Progressive Disclosure

The implementation follows progressive disclosure principles:

  1. Always Show Button: Users always see the feature exists
  2. Contextual Information: Click reveals what's needed to use the feature
  3. Step-by-Step Guidance: Clear path to enable the feature
  4. Educational Content: Explains how the feature works

Technical Implementation

Component Structure

export const StructuredOutputButton = () => {
    // State management
    const [showDialog, setShowDialog] = useState(false);
    const [showSchemaBuilder, setShowSchemaBuilder] = useState(false);

    // Feature access checks
    const hasStructuredOutputAccess = useFeatureAccess(FeatureSlug.STRUCTURED_OUTPUT);

    // Context-aware rendering
    const getDialogContent = () => {
        // Returns appropriate content based on current state
    };

    // Always render button with appropriate state
    return (
        <>
            <Button onClick={handleClick}>
                {/* State-based icon */}
            </Button>

            {/* Information Dialog */}
            <Dialog>{/* ... */}</Dialog>

            {/* Custom Schema Builder */}
            <Dialog>{/* ... */}</Dialog>
        </>
    );
};

Hook Updates

Updated useStructuredExtraction to support:

  • Custom schema parameter: extractStructuredOutput(customSchema?: z.ZodTypeAny)
  • Predefined prompt integration
  • Enhanced error handling

User Experience Benefits

1. Discoverability

  • Feature is always visible to all users
  • Clear visual indication of availability status
  • Educational tooltips guide users

2. Progressive Enhancement

  • Free users see upgrade prompts
  • VT+ users get full feature access
  • Custom schemas available for advanced users

3. Guided Onboarding

  • Step-by-step guidance to enable feature
  • Clear explanations of requirements
  • Contextual help and information

4. Accessibility

  • Proper ARIA labels for dialogs
  • Keyboard navigation support
  • Screen reader friendly tooltips

Testing Considerations

Manual Testing Scenarios

  1. Free User: Should see lock icon and upgrade prompt
  2. VT+ User, No Document: Should see upload guidance
  3. VT+ User, Image Document: Should see PDF requirement
  4. VT+ User, PDF, Non-Gemini: Should see model switch prompt
  5. VT+ User, PDF, Gemini: Should extract successfully
  6. Custom Schema: VT+ users should access schema builder

Automated Testing

  • Component state transitions
  • Dialog content accuracy
  • Subscription access validation
  • Schema builder integration

Deployment Notes

Requirements Met

✅ Always Visible Icon: Button shows in all states ✅ VT+ Gating: Properly restricted to Plus subscribers ✅ Document Validation: Checks for PDF attachment ✅ Model Validation: Requires Gemini model ✅ Predefined Prompt: Uses specified extraction prompt ✅ Custom Schemas: VT+ exclusive schema builder ✅ Human-in-Loop: User action required for all states ✅ Seamless Experience: Guided, educational workflow

Production Ready

The enhanced structured output feature is now production-ready with:

  • Comprehensive error handling
  • Accessibility compliance
  • Progressive disclosure UX
  • VT+ subscription gating
  • Browser-compatible PDF processing
  • Custom schema support

Implemented: June 18, 2025 Status: Production Ready ✅