14 KiB
14 KiB
\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 - AI system overview\n- Natural Language Config - Related generation feature\n- RAG System - Suggestion retrieval\n- Configuration - Setup guide\n- ADR-015 - Design decisions\n\n---\n\nStatus: 🔴 Planned\nTarget Release: Q2 2025\nLast Updated: 2025-01-13\nComponent: typdialog-ai\nArchitecture: Complete\nImplementation: In Design Phase