# AI-Assisted Forms (typdialog-ai)\n\n**Status**: 🔴 Planned (Q2 2025 target)\n\nAI-Assisted Forms is a planned feature that integrates intelligent suggestions, context-aware assistance, and natural language understanding into the\ntypdialog web UI. This enables users to configure infrastructure through interactive forms with real-time AI guidance.\n\n## Feature Overview\n\n### What It Does\n\nEnhance configuration forms with AI-powered assistance:\n\n```\nUser typing in form field: "storage"\n  ↓\nAI analyzes context:\n  - Current form (database configuration)\n  - Field type (storage capacity)\n  - Similar past configurations\n  - Best practices for this workload\n  ↓\nSuggestions appear:\n  ✓ "100 GB (standard production size)"\n  ✓ "50 GB (development environment)"\n  ✓ "500 GB (large-scale analytics)"\n```\n\n### Primary Use Cases\n\n1. **Guided Configuration**: Step-by-step assistance filling complex forms\n2. **Error Explanation**: AI explains validation failures in plain English\n3. **Smart Autocomplete**: Suggestions based on context, not just keywords\n4. **Learning**: New users learn patterns from AI explanations\n5. **Efficiency**: Experienced users get quick suggestions\n\n## Architecture\n\n### User Interface Integration\n\n```\n┌────────────────────────────────────────┐\n│ Typdialog Web UI (React/TypeScript)    │\n│                                        │\n│ ┌──────────────────────────────────┐  │\n│ │ Form Fields                      │  │\n│ │                                  │  │\n│ │ Database Engine: [postgresql  ▼] │  │\n│ │ Storage (GB):    [100 GB    ↓ ?] │  │\n│ │                   AI suggestions  │  │\n│ │ Encryption:      [✓ enabled  ]   │  │\n│ │                   "Required for  │  │\n│ │                    production"   │  │\n│ │                                  │  │\n│ │ [← Back] [Next →]                │  │\n│ └──────────────────────────────────┘  │\n│                  ↓                     │\n│         AI Assistance Panel            │\n│      (suggestions & explanations)      │\n└────────────────────────────────────────┘\n        ↓                    ↑\n   User Input           AI Service\n                      (port 8083)\n```\n\n### Suggestion Pipeline\n\n```\nUser Event (typing, focusing field, validation error)\n        ↓\n┌─────────────────────────────────────┐\n│ Context Extraction                   │\n│ - Current field and value            │\n│ - Form schema and constraints        │\n│ - Other filled fields                │\n│ - User role and workspace            │\n└─────────────────────┬───────────────┘\n                      ↓\n┌─────────────────────────────────────┐\n│ RAG Retrieval                        │\n│ - Find similar configs               │\n│ - Get examples for field type        │\n│ - Retrieve relevant documentation    │\n│ - Find validation rules              │\n└─────────────────────┬───────────────┘\n                      ↓\n┌─────────────────────────────────────┐\n│ Suggestion Generation                │\n│ - AI generates suggestions           │\n│ - Rank by relevance                  │\n│ - Format for display                 │\n│ - Generate explanation               │\n└─────────────────────┬───────────────┘\n                      ↓\n┌─────────────────────────────────────┐\n│ Response Formatting                  │\n│ - Debounce (don't update too fast)   │\n│ - Cache identical results            │\n│ - Stream if long response            │\n│ - Display to user                    │\n└─────────────────────────────────────┘\n```\n\n## Planned Features\n\n### 1. Smart Field Suggestions\n\nIntelligent suggestions based on context:\n\n```\nScenario: User filling database configuration form\n\n1. Engine selection\n   User types: "post" \n   Suggestion: "postgresql" (99% match)\n   Explanation: "PostgreSQL is the most popular open-source relational database"\n\n2. Storage size\n   User has selected: "postgresql", "production", "web-application"\n   Suggestions appear:\n   • "100 GB" (standard production web app database)\n   • "500 GB" (if expected growth > 1000 connections)\n   • "1 TB" (high-traffic SaaS platform)\n   Explanation: "For typical web applications with 1000s of concurrent users, 100 GB is recommended"\n\n3. Backup frequency\n   User has selected: "production", "critical-data"\n   Suggestions appear:\n   • "Daily" (standard for critical databases)\n   • "Hourly" (for data warehouses with frequent updates)\n   Explanation: "Critical production data requires daily or more frequent backups"\n```\n\n### 2. Validation Error Explanation\n\nHuman-readable error messages with fixes:\n\n```\nUser enters: "storage = -100"\n\nCurrent behavior:\n  ✗ Error: Expected positive integer\n\nPlanned AI behavior:\n  ✗ Storage must be positive (1-65535 GB)\n  \n  Why: Negative storage doesn't make sense.\n       Storage capacity must be at least 1 GB.\n  \n  Fix suggestions:\n  • Use 100 GB (typical production size)\n  • Use 50 GB (development environment)\n  • Use your required size in GB\n```\n\n### 3. Field-to-Field Context Awareness\n\nSuggestions change based on other fields:\n\n```\nScenario: Multi-step configuration form\n\nStep 1: Select environment\nUser: "production"\n  → Form shows constraints: (min storage 50GB, encryption required, backup required)\n\nStep 2: Select database engine\nUser: "postgresql"\n  → Suggestions adapted:\n    - PostgreSQL 15 recommended for production\n    - Point-in-time recovery available\n    - Replication options highlighted\n\nStep 3: Storage size\n  → Suggestions show:\n    - Minimum 50 GB for production\n    - Examples from similar production configs\n    - Cost estimate updates in real-time\n\nStep 4: Encryption\n  → Suggestion appears: "Recommended: AES-256"\n  → Explanation: "Required for production environments"\n```\n\n### 4. Inline Documentation\n\nQuick access to relevant docs:\n\n```\nField: "Backup Retention Days"\n\nSuggestion popup:\n  ┌─────────────────────────────────┐\n  │ Suggested value: 30              │\n  │                                 │\n  │ Why: 30 days is industry-standard│\n  │ standard for compliance (PCI-DSS)│\n  │                                 │\n  │ Learn more:                      │\n  │ → Backup best practices guide    │\n  │ → Your compliance requirements   │\n  │ → Cost vs retention trade-offs   │\n  └─────────────────────────────────┘\n```\n\n### 5. Multi-Field Suggestions\n\nSuggest multiple related fields together:\n\n```\nUser selects: environment = "production"\n\nAI suggests completing:\n  ┌─────────────────────────────────┐\n  │ Complete Production Setup        │\n  │                                 │\n  │ Based on production environment │\n  │ we recommend:                    │\n  │                                 │\n  │ Encryption: enabled              │ ← Auto-fill\n  │ Backups: daily                   │ ← Auto-fill\n  │ Monitoring: enabled              │ ← Auto-fill\n  │ High availability: enabled       │ ← Auto-fill\n  │ Retention: 30 days              │ ← Auto-fill\n  │                                 │\n  │ [Accept All] [Review] [Skip]    │\n  └─────────────────────────────────┘\n```\n\n## Implementation Components\n\n### Frontend (typdialog-ai JavaScript/TypeScript)\n\n```\n// React component for field with AI assistance\ninterface AIFieldProps {\n  fieldName: string;\n  fieldType: string;\n  currentValue: string;\n  formContext: Record<string, any>;\n  schema: FieldSchema;\n}\n\nfunction AIAssistedField({fieldName, formContext, schema}: AIFieldProps) {\n  const [suggestions, setSuggestions] = useState<Suggestion[]>([]);\n  const [explanation, setExplanation] = useState<string>("");\n  \n  // Debounced suggestion generation\n  useEffect(() => {\n    const timer = setTimeout(async () => {\n      const suggestions = await ai.suggestFieldValue({\n        field: fieldName,\n        context: formContext,\n        schema: schema,\n      });\n      setSuggestions(suggestions);\n| setExplanation(suggestions[0]?.explanation |  | ""); |\n    }, 300);  // Debounce 300ms\n    \n    return () => clearTimeout(timer);\n  }, [formContext[fieldName]]);\n  \n  return (\n    <div className="ai-field">\n      <input \n        value={formContext[fieldName]}\n        onChange={(e) => handleChange(e.target.value)}\n      />\n      \n      {suggestions.length > 0 && (\n        <div className="ai-suggestions">\n          {suggestions.map((s) => (\n            <button key={s.value} onClick={() => accept(s.value)}>\n              {s.label}\n            </button>\n          ))}\n          {explanation && (\n            <p className="ai-explanation">{explanation}</p>\n          )}\n        </div>\n      )}\n    </div>\n  );\n}\n```\n\n### Backend Service Integration\n\n```\n// In AI Service: field suggestion endpoint\nasync fn suggest_field_value(\n    req: SuggestFieldRequest,\n) -> Result<Vec<Suggestion>> {\n    // Build context for the suggestion\n    let context = build_field_context(&req.form_context, &req.field_name)?;\n    \n    // Retrieve relevant examples from RAG\n    let examples = rag.search_by_field(&req.field_name, &context)?;\n    \n    // Generate suggestions via LLM\n    let suggestions = llm.generate_suggestions(\n        &req.field_name,\n        &req.field_type,\n        &context,\n        &examples,\n    ).await?;\n    \n    // Rank and format suggestions\n    let ranked = rank_suggestions(suggestions, &context);\n    \n    Ok(ranked)\n}\n```\n\n## Configuration\n\n### Form Assistant Settings\n\n```\n# In provisioning/config/ai.toml\n[ai.forms]\nenabled = true\n\n# Suggestion delivery\nsuggestions_enabled = true\nsuggestions_debounce_ms = 300\nmax_suggestions_per_field = 3\n\n# Error explanations\nerror_explanations_enabled = true\nexplain_validation_errors = true\nsuggest_fixes = true\n\n# Field context awareness\nfield_context_enabled = true\ncross_field_suggestions = true\n\n# Inline documentation\ninline_docs_enabled = true\ndocs_link_type = "modal"  # or "sidebar", "tooltip"\n\n# Performance\ncache_suggestions = true\ncache_ttl_seconds = 3600\n\n# Learning\ntrack_accepted_suggestions = true\ntrack_rejected_suggestions = true\n```\n\n## User Experience Flow\n\n### Scenario: New User Configuring PostgreSQL\n\n```\n1. User opens typdialog form\n   - Form title: "Create Database"\n   - First field: "Database Engine"\n   - AI shows: "PostgreSQL recommended for relational data"\n\n2. User types "post"\n   - Autocomplete shows: "postgresql"\n   - AI explains: "PostgreSQL is the most stable open-source database"\n\n3. User selects "postgresql"\n   - Form progresses\n   - Next field: "Version"\n   - AI suggests: "PostgreSQL 15 (latest stable)"\n   - Explanation: "Version 15 is current stable, recommended for new deployments"\n\n4. User selects version 15\n   - Next field: "Environment"\n   - User selects "production"\n   - AI note appears: "Production environment requires encryption and backups"\n\n5. Next field: "Storage (GB)"\n   - Form shows: Minimum 50 GB (production requirement)\n   - AI suggestions:\n     • 100 GB (standard production)\n     • 250 GB (high-traffic site)\n   - User accepts: 100 GB\n\n6. Validation error on next field\n   - Old behavior: "Invalid backup_days value"\n   - New behavior: \n     "Backup retention must be 1-35 days. Recommended: 30 days.\n     30-day retention meets compliance requirements for production systems."\n\n7. User completes form\n   - Summary shows all AI-assisted decisions\n   - Generate button creates configuration\n```\n\n## Integration with Natural Language Generation\n\nNLC and form assistance share the same backend:\n\n```\nNatural Language Generation    AI-Assisted Forms\n        ↓                              ↓\n    "Create a PostgreSQL db"    Select field values\n        ↓                              ↓\n    Intent Extraction         Context Extraction\n        ↓                              ↓\n    RAG Search              RAG Search (same results)\n        ↓                              ↓\n    LLM Generation          LLM Suggestions\n        ↓                              ↓\n    Config Output           Form Field Population\n```\n\n## Success Criteria (Q2 2025)\n\n- ✅ Suggestions appear within 300ms of user action\n- ✅ 80% suggestion acceptance rate in user testing\n- ✅ Error explanations clearly explain issues and fixes\n- ✅ Cross-field context awareness works for 5+ database scenarios\n- ✅ Form completion time reduced by 40% with AI\n- ✅ User satisfaction > 8/10 in testing\n- ✅ No false suggestions (all suggestions are valid)\n- ✅ Offline mode works with cached suggestions\n\n## Related Documentation\n\n- [Architecture](architecture.md) - AI system overview\n- [Natural Language Config](natural-language-config.md) - Related generation feature\n- [RAG System](rag-system.md) - Suggestion retrieval\n- [Configuration](configuration.md) - Setup guide\n- [ADR-015](../architecture/adr/adr-015-ai-integration-architecture.md) - Design decisions\n\n---\n\n**Status**: 🔴 Planned\n**Target Release**: Q2 2025\n**Last Updated**: 2025-01-13\n**Component**: typdialog-ai\n**Architecture**: Complete\n**Implementation**: In Design Phase
