feat(ai): Add form context and custom prompts support

- Add `formContext` parameter to AIFormProvider for global AI context
- Add `formContext` option to useForm AI configuration for form-level overrides
- Implement `systemPrompt` customization for Chrome AI provider
- Support placeholder substitution in custom prompts ({fieldName}, {currentValue}, {formContext}, {fields})
- Pass ChromeAIProvider config to constructor for accessing custom prompt templates
- Update API documentation with new formContext and systemPrompt parameters
- Add comprehensive examples for form context usage in PROVIDERS.md
- Document available placeholders and default prompt behavior
- Enable users to provide contextual information for better AI suggestions

Author: SameedIlyas

docs/API_REFERENCE.md

@@ -423,6 +423,10 @@ Override the order in which providers are tried. Inherits from `AIFormProvider`
 
 Automatically try the next provider if one fails. Default: `true`
 
+#### `formContext?: string | Record<string, any>`
+
+Context information for AI to use when generating suggestions. Can be a string description or an object with contextual data.
+
 **Example:**
 
 ```tsx
@@ -436,7 +440,8 @@ const form = useForm<FormData>({
       { type: 'openai', apiKey: 'sk-...', priority: 5 }
     ],
     executionOrder: ['chrome', 'openai'],
-    fallbackOnError: true
+    fallbackOnError: true,
+    formContext: 'Senior software engineer applying for a tech lead position'
   }
 });
 ```
@@ -477,6 +482,10 @@ Debounce time in milliseconds for AI suggestions. Default: `800`
 
 Array of field names to exclude from AI processing. Default: `[]`
 
+#### `formContext?: string | Record<string, any>`
+
+Global context information for AI to use when generating suggestions. Can be a string description or an object with contextual data. Forms can override this with their own local context.
+
 ---
 
 ## Types
@@ -634,6 +643,10 @@ Set to `false` to disable this provider. Optional.
 
 Higher values are tried first. Optional, default: 0.
 
+#### `systemPrompt?: string`
+
+Custom prompt template for Chrome AI. Use placeholders `{fieldName}`, `{currentValue}`, `{formContext}`, and `{fields}` for dynamic values. If not provided, uses the default prompt.
+
 **Features:**
 - ✅ No API key required
 - ✅ Browser-based and privacy-friendly
@@ -646,7 +659,8 @@ Higher values are tried first. Optional, default: 0.
 ```tsx
 const config: ChromeAIConfig = {
   type: 'chrome',
-  priority: 10
+  priority: 10,
+  systemPrompt: 'You are a professional recruiter. For field {fieldName} with value "{currentValue}", suggest a professional response. Context: {formContext}. Return only the value.'
 };
 ```
 

docs/PROVIDERS.md

@@ -15,7 +15,8 @@ Chrome's experimental on-device AI. Privacy-friendly and free, but requires Chro
 ```tsx
 {
   type: 'chrome',
-  priority: 10  // Optional: higher priority = tried first
+  priority: 10,  // Optional: higher priority = tried first
+  systemPrompt: 'Custom prompt...'  // Optional: custom AI prompt template
 }
 ```
 
@@ -34,6 +35,29 @@ Chrome's experimental on-device AI. Privacy-friendly and free, but requires Chro
 3. Set to "Enabled"
 4. Restart Chrome
 
+### Custom Prompts
+
+Customize how Chrome AI generates suggestions using the `systemPrompt` option:
+
+```tsx
+{
+  type: 'chrome',
+  priority: 10,
+  systemPrompt: `You are a professional form assistant. 
+For the field named {fieldName} with current value "{currentValue}", 
+provide a suggestion based on this context: {formContext}.
+Return only the suggested value, no explanations.`
+}
+```
+
+**Available placeholders:**
+- `{fieldName}` - The name of the field being filled
+- `{currentValue}` - The current value in the field
+- `{formContext}` - The form context as JSON
+- `{fields}` - List of all form fields (for autofill)
+
+If no custom prompt is provided, a sensible default is used.
+
 ### Handling Model Download
 
 The AI model (~1-2GB) downloads on first use. Handle this gracefully:
@@ -225,6 +249,44 @@ Connect to browser-based AI services.
 }
 ```
 
+## Form Context
+
+Provide contextual information to help AI generate better suggestions:
+
+```tsx
+<AIFormProvider
+  providers={[{ type: 'chrome', priority: 10 }]}
+  formContext="Senior software engineer with 8+ years of experience applying for a tech lead position"
+>
+  <App />
+</AIFormProvider>
+```
+
+Or use an object for structured context:
+
+```tsx
+<AIFormProvider
+  providers={[{ type: 'chrome', priority: 10 }]}
+  formContext={{
+    role: 'Senior Engineer',
+    experience: '8+ years',
+    specialization: 'Full-stack development'
+  }}
+>
+  <App />
+</AIFormProvider>
+```
+
+Forms can override the global context:
+
+```tsx
+const form = useForm({
+  ai: {
+    formContext: 'Junior developer with 2 years of experience'
+  }
+});
+```
+
 ## Multi-Provider Setup
 
 Configure multiple providers with automatic fallback:
@@ -255,6 +317,7 @@ Configure multiple providers with automatic fallback:
   ]}
   executionOrder={['chrome', 'openai', 'custom']}
   fallbackOnError={true}
+  formContext="Default context for all forms"
 >
   <App />
 </AIFormProvider>

src/AIFormProvider.tsx

@@ -19,6 +19,8 @@ export interface AIFormProviderProps {
   enabled?: boolean;
   debounceMs?: number;
   excludeFields?: string[];
+  /** Global context for AI to use when filling forms (optional) */
+  formContext?: string | Record<string, any>;
 }
 
 /**

src/aiProviders.ts

@@ -55,6 +55,8 @@ interface AIProviderExecutor {
  * Chrome Built-in AI Provider
  */
 class ChromeAIProvider implements AIProviderExecutor {
+  constructor(private config?: Extract<AIProvider, { type: 'chrome' }>) {}
+
   async checkAvailability() {
     if (typeof window === 'undefined' || typeof LanguageModel === 'undefined') {
       return { available: false, status: 'unavailable', needsDownload: false };
@@ -78,7 +80,7 @@ class ChromeAIProvider implements AIProviderExecutor {
     formContext: Record<string, any>
   ): Promise<AIResponse | null> {
     try {
-      const prompt = `You are assisting with form completion. The user is filling out a field named "${fieldName}".
+      const defaultPrompt = `You are assisting with form completion. The user is filling out a field named "${fieldName}".
 
 Current value: "${currentValue}"
 Form context: ${JSON.stringify(formContext, null, 2)}
@@ -93,6 +95,13 @@ Rules:
 
 Suggested value:`;
 
+      const prompt = this.config?.systemPrompt 
+        ? this.config.systemPrompt
+            .replace('{fieldName}', fieldName)
+            .replace('{currentValue}', currentValue)
+            .replace('{formContext}', JSON.stringify(formContext, null, 2))
+        : defaultPrompt;
+
       const session = await LanguageModel.create();
       const result = await session.prompt(prompt);
       session.destroy();
@@ -111,7 +120,7 @@ Suggested value:`;
     onProgress?: (progress: number) => void
   ): Promise<AutofillData | null> {
     try {
-      const prompt = `You are an intelligent form assistant. Generate realistic example values for a form.
+      const defaultPrompt = `You are an intelligent form assistant. Generate realistic example values for a form.
 
 Form fields: ${fields.join(', ')}
 Context: ${JSON.stringify(formContext, null, 2)}
@@ -124,6 +133,12 @@ Example format:
 
 JSON object:`;
 
+      const prompt = this.config?.systemPrompt 
+        ? this.config.systemPrompt
+            .replace('{fields}', fields.join(', '))
+            .replace('{formContext}', JSON.stringify(formContext, null, 2))
+        : defaultPrompt;
+
       const session = await LanguageModel.create({
         monitor(m) {
           m.addEventListener('downloadprogress', (e) => {
@@ -338,7 +353,7 @@ class CustomServerProvider implements AIProviderExecutor {
 export function createAIProvider(config: AIProvider): AIProviderExecutor {
   switch (config.type) {
     case 'chrome':
-      return new ChromeAIProvider();
+      return new ChromeAIProvider(config);
     case 'openai':
       return new OpenAIProvider(config);
     case 'custom':

src/types/ai.ts

@@ -107,6 +107,7 @@ export interface CustomServerConfig extends AIProviderConfig {
 export interface ChromeAIConfig extends AIProviderConfig {
   /** Must be 'chrome' */
   type: 'chrome';
+  systemPrompt?: string;
 }
 
 /**
@@ -188,6 +189,8 @@ export interface AIFormContextValue {
   debounceMs: number;
   /** Array of field names to exclude from AI processing */
   excludeFields: string[];
+  /** Global context for AI to use when filling forms (optional) */
+  formContext?: string | Record<string, any>;
 }
 
 /**

src/useForm.ts

@@ -51,6 +51,8 @@ export interface AIFormOptions {
   executionOrder?: AIProviderType[];
   /** Override fallback behavior from AIFormProvider */
   fallbackOnError?: boolean;
+  /** Context for AI to use when filling forms (optional) */
+  formContext?: string | Record<string, any>;
 }
 
 /**
@@ -169,6 +171,7 @@ export function useForm<T extends FieldValues>(
       providers: localProviders,
       executionOrder: localOrder,
       fallbackOnError: localFallback,
+      formContext: localFormContext,
     } = aiOptions || {};
 
     return {
@@ -180,6 +183,7 @@ export function useForm<T extends FieldValues>(
       providers: localProviders ?? providerContext?.providers,
       executionOrder: localOrder ?? providerContext?.executionOrder,
       fallbackOnError: localFallback ?? providerContext?.fallbackOnError ?? true,
+      formContext: localFormContext ?? providerContext?.formContext,
     };
   }, [aiOptions, providerContext]);
 
@@ -192,6 +196,7 @@ export function useForm<T extends FieldValues>(
     providers,
     executionOrder,
     fallbackOnError,
+    formContext: configFormContext,
   } = mergedConfig;
 
   const form = useReactHookForm<T>(rhfOptions);
@@ -209,10 +214,20 @@ export function useForm<T extends FieldValues>(
   // Get current form values for context
   const formValues = form.watch();
 
+  // Merge form values with configured context
+  const mergedFormContext = useMemo(() => {
+    if (typeof configFormContext === 'string') {
+      return { ...formValues, _context: configFormContext };
+    } else if (configFormContext) {
+      return { ...formValues, ...configFormContext };
+    }
+    return formValues;
+  }, [formValues, configFormContext]);
+
   // Initialize AI assistant with form context and overrides
   const ai = useAIAssistant({
     enabled: aiEnabled,
-    formContext: formValues,
+    formContext: mergedFormContext,
     apiUrl,
     providers,
     executionOrder,