provisioning/docs/src/ai/ai-assisted-forms.md

# AI-Assisted Forms (typdialog-ai)

**Status**: 🔴 Planned (Q2 2025 target)

AI-Assisted Forms is a planned feature that integrates intelligent suggestions, context-aware assistance, and natural language understanding into the
typdialog web UI. This enables users to configure infrastructure through interactive forms with real-time AI guidance.

## Feature Overview

### What It Does

Enhance configuration forms with AI-powered assistance:

```text
User typing in form field: "storage"
  ↓
AI analyzes context:
  - Current form (database configuration)
  - Field type (storage capacity)
  - Similar past configurations
  - Best practices for this workload
  ↓
Suggestions appear:
  ✓ "100 GB (standard production size)"
  ✓ "50 GB (development environment)"
  ✓ "500 GB (large-scale analytics)"
```

### Primary Use Cases

1. **Guided Configuration**: Step-by-step assistance filling complex forms
2. **Error Explanation**: AI explains validation failures in plain English
3. **Smart Autocomplete**: Suggestions based on context, not just keywords
4. **Learning**: New users learn patterns from AI explanations
5. **Efficiency**: Experienced users get quick suggestions

## Architecture

### User Interface Integration

```text
┌────────────────────────────────────────┐
│ Typdialog Web UI (React/TypeScript)    │
│                                        │
│ ┌──────────────────────────────────┐  │
│ │ Form Fields                      │  │
│ │                                  │  │
│ │ Database Engine: [postgresql  ▼] │  │
│ │ Storage (GB):    [100 GB    ↓ ?] │  │
│ │                   AI suggestions  │  │
│ │ Encryption:      [✓ enabled  ]   │  │
│ │                   "Required for  │  │
│ │                    production"   │  │
│ │                                  │  │
│ │ [← Back] [Next →]                │  │
│ └──────────────────────────────────┘  │
│                  ↓                     │
│         AI Assistance Panel            │
│      (suggestions & explanations)      │
└────────────────────────────────────────┘
        ↓                    ↑
   User Input           AI Service
                      (port 8083)
```

### Suggestion Pipeline

```text
User Event (typing, focusing field, validation error)
        ↓
┌─────────────────────────────────────┐
│ Context Extraction                   │
│ - Current field and value            │
│ - Form schema and constraints        │
│ - Other filled fields                │
│ - User role and workspace            │
└─────────────────────┬───────────────┘
                      ↓
┌─────────────────────────────────────┐
│ RAG Retrieval                        │
│ - Find similar configs               │
│ - Get examples for field type        │
│ - Retrieve relevant documentation    │
│ - Find validation rules              │
└─────────────────────┬───────────────┘
                      ↓
┌─────────────────────────────────────┐
│ Suggestion Generation                │
│ - AI generates suggestions           │
│ - Rank by relevance                  │
│ - Format for display                 │
│ - Generate explanation               │
└─────────────────────┬───────────────┘
                      ↓
┌─────────────────────────────────────┐
│ Response Formatting                  │
│ - Debounce (don't update too fast)   │
│ - Cache identical results            │
│ - Stream if long response            │
│ - Display to user                    │
└─────────────────────────────────────┘
```

## Planned Features

### 1. Smart Field Suggestions

Intelligent suggestions based on context:

```text
Scenario: User filling database configuration form

1. Engine selection
   User types: "post" 
   Suggestion: "postgresql" (99% match)
   Explanation: "PostgreSQL is the most popular open-source relational database"

2. Storage size
   User has selected: "postgresql", "production", "web-application"
   Suggestions appear:
   • "100 GB" (standard production web app database)
   • "500 GB" (if expected growth > 1000 connections)
   • "1 TB" (high-traffic SaaS platform)
   Explanation: "For typical web applications with 1000s of concurrent users, 100 GB is recommended"

3. Backup frequency
   User has selected: "production", "critical-data"
   Suggestions appear:
   • "Daily" (standard for critical databases)
   • "Hourly" (for data warehouses with frequent updates)
   Explanation: "Critical production data requires daily or more frequent backups"
```

### 2. Validation Error Explanation

Human-readable error messages with fixes:

```text
User enters: "storage = -100"

Current behavior:
  ✗ Error: Expected positive integer

Planned AI behavior:
  ✗ Storage must be positive (1-65535 GB)
  
  Why: Negative storage doesn't make sense.
       Storage capacity must be at least 1 GB.
  
  Fix suggestions:
  • Use 100 GB (typical production size)
  • Use 50 GB (development environment)
  • Use your required size in GB
```

### 3. Field-to-Field Context Awareness

Suggestions change based on other fields:

```text
Scenario: Multi-step configuration form

Step 1: Select environment
User: "production"
  → Form shows constraints: (min storage 50GB, encryption required, backup required)

Step 2: Select database engine
User: "postgresql"
  → Suggestions adapted:
    - PostgreSQL 15 recommended for production
    - Point-in-time recovery available
    - Replication options highlighted

Step 3: Storage size
  → Suggestions show:
    - Minimum 50 GB for production
    - Examples from similar production configs
    - Cost estimate updates in real-time

Step 4: Encryption
  → Suggestion appears: "Recommended: AES-256"
  → Explanation: "Required for production environments"
```

### 4. Inline Documentation

Quick access to relevant docs:

```text
Field: "Backup Retention Days"

Suggestion popup:
  ┌─────────────────────────────────┐
  │ Suggested value: 30              │
  │                                 │
  │ Why: 30 days is industry-standard│
  │ standard for compliance (PCI-DSS)│
  │                                 │
  │ Learn more:                      │
  │ → Backup best practices guide    │
  │ → Your compliance requirements   │
  │ → Cost vs retention trade-offs   │
  └─────────────────────────────────┘
```

### 5. Multi-Field Suggestions

Suggest multiple related fields together:

```text
User selects: environment = "production"

AI suggests completing:
  ┌─────────────────────────────────┐
  │ Complete Production Setup        │
  │                                 │
  │ Based on production environment │
  │ we recommend:                    │
  │                                 │
  │ Encryption: enabled              │ ← Auto-fill
  │ Backups: daily                   │ ← Auto-fill
  │ Monitoring: enabled              │ ← Auto-fill
  │ High availability: enabled       │ ← Auto-fill
  │ Retention: 30 days              │ ← Auto-fill
  │                                 │
  │ [Accept All] [Review] [Skip]    │
  └─────────────────────────────────┘
```

## Implementation Components

### Frontend (typdialog-ai JavaScript/TypeScript)

```text
// React component for field with AI assistance
interface AIFieldProps {
  fieldName: string;
  fieldType: string;
  currentValue: string;
  formContext: Record<string, any>;
  schema: FieldSchema;
}

function AIAssistedField({fieldName, formContext, schema}: AIFieldProps) {
  const [suggestions, setSuggestions] = useState<Suggestion[]>([]);
  const [explanation, setExplanation] = useState<string>("");
  
  // Debounced suggestion generation
  useEffect(() => {
    const timer = setTimeout(async () => {
      const suggestions = await ai.suggestFieldValue({
        field: fieldName,
        context: formContext,
        schema: schema,
      });
      setSuggestions(suggestions);
| setExplanation(suggestions[0]?.explanation |  | ""); |
    }, 300);  // Debounce 300ms
    
    return () => clearTimeout(timer);
  }, [formContext[fieldName]]);
  
  return (
    <div className="ai-field">
      <input 
        value={formContext[fieldName]}
        onChange={(e) => handleChange(e.target.value)}
      />
      
      {suggestions.length > 0 && (
        <div className="ai-suggestions">
          {suggestions.map((s) => (
            <button key={s.value} onClick={() => accept(s.value)}>
              {s.label}
            </button>
          ))}
          {explanation && (
            <p className="ai-explanation">{explanation}</p>
          )}
        </div>
      )}
    </div>
  );
}
```

### Backend Service Integration

```text
// In AI Service: field suggestion endpoint
async fn suggest_field_value(
    req: SuggestFieldRequest,
) -> Result<Vec<Suggestion>> {
    // Build context for the suggestion
    let context = build_field_context(&req.form_context, &req.field_name)?;
    
    // Retrieve relevant examples from RAG
    let examples = rag.search_by_field(&req.field_name, &context)?;
    
    // Generate suggestions via LLM
    let suggestions = llm.generate_suggestions(
        &req.field_name,
        &req.field_type,
        &context,
        &examples,
    ).await?;
    
    // Rank and format suggestions
    let ranked = rank_suggestions(suggestions, &context);
    
    Ok(ranked)
}
```

## Configuration

### Form Assistant Settings

```text
# In provisioning/config/ai.toml
[ai.forms]
enabled = true

# Suggestion delivery
suggestions_enabled = true
suggestions_debounce_ms = 300
max_suggestions_per_field = 3

# Error explanations
error_explanations_enabled = true
explain_validation_errors = true
suggest_fixes = true

# Field context awareness
field_context_enabled = true
cross_field_suggestions = true

# Inline documentation
inline_docs_enabled = true
docs_link_type = "modal"  # or "sidebar", "tooltip"

# Performance
cache_suggestions = true
cache_ttl_seconds = 3600

# Learning
track_accepted_suggestions = true
track_rejected_suggestions = true
```

## User Experience Flow

### Scenario: New User Configuring PostgreSQL

```text
1. User opens typdialog form
   - Form title: "Create Database"
   - First field: "Database Engine"
   - AI shows: "PostgreSQL recommended for relational data"

2. User types "post"
   - Autocomplete shows: "postgresql"
   - AI explains: "PostgreSQL is the most stable open-source database"

3. User selects "postgresql"
   - Form progresses
   - Next field: "Version"
   - AI suggests: "PostgreSQL 15 (latest stable)"
   - Explanation: "Version 15 is current stable, recommended for new deployments"

4. User selects version 15
   - Next field: "Environment"
   - User selects "production"
   - AI note appears: "Production environment requires encryption and backups"

5. Next field: "Storage (GB)"
   - Form shows: Minimum 50 GB (production requirement)
   - AI suggestions:
     • 100 GB (standard production)
     • 250 GB (high-traffic site)
   - User accepts: 100 GB

6. Validation error on next field
   - Old behavior: "Invalid backup_days value"
   - New behavior: 
     "Backup retention must be 1-35 days. Recommended: 30 days.
     30-day retention meets compliance requirements for production systems."

7. User completes form
   - Summary shows all AI-assisted decisions
   - Generate button creates configuration
```

## Integration with Natural Language Generation

NLC and form assistance share the same backend:

```text
Natural Language Generation    AI-Assisted Forms
        ↓                              ↓
    "Create a PostgreSQL db"    Select field values
        ↓                              ↓
    Intent Extraction         Context Extraction
        ↓                              ↓
    RAG Search              RAG Search (same results)
        ↓                              ↓
    LLM Generation          LLM Suggestions
        ↓                              ↓
    Config Output           Form Field Population
```

## Success Criteria (Q2 2025)

- ✅ Suggestions appear within 300ms of user action
- ✅ 80% suggestion acceptance rate in user testing
- ✅ Error explanations clearly explain issues and fixes
- ✅ Cross-field context awareness works for 5+ database scenarios
- ✅ Form completion time reduced by 40% with AI
- ✅ User satisfaction > 8/10 in testing
- ✅ No false suggestions (all suggestions are valid)
- ✅ Offline mode works with cached suggestions

## Related Documentation

- [Architecture](architecture.md) - AI system overview
- [Natural Language Config](natural-language-config.md) - Related generation feature
- [RAG System](rag-system.md) - Suggestion retrieval
- [Configuration](configuration.md) - Setup guide
- [ADR-015](../architecture/adr/adr-015-ai-integration-architecture.md) - Design decisions

---

**Status**: 🔴 Planned
**Target Release**: Q2 2025
**Last Updated**: 2025-01-13
**Component**: typdialog-ai
**Architecture**: Complete
**Implementation**: In Design Phase