@elizaos/plugin-form 2.0.0-alpha.3 → 2.0.0-alpha.4

package/dist/evaluators/extractor.d.ts

@@ -1,91 +0,0 @@
-/**
- * @module evaluators/extractor
- * @description Form evaluator for field extraction and intent handling
- *
- * ## Role in Form Plugin
- *
- * The evaluator is the "brain" of the form plugin. It runs AFTER
- * each user message and:
- *
- * 1. Detects user intent (submit, cancel, undo, etc.)
- * 2. Extracts field values from natural language
- * 3. Updates session state accordingly
- * 4. Triggers lifecycle transitions
- * 5. **Emits events** for widgets and other listeners
- *
- * ## Event Emission
- *
- * The evaluator emits standardized events as it processes messages:
- *
- * - `FORM_FIELD_EXTRACTED`: Value extracted for a simple field
- * - `FORM_SUBFIELD_UPDATED`: Value extracted for a composite subfield
- * - `FORM_SUBCONTROLS_FILLED`: All subcontrols of composite type filled
- * - `FORM_EXTERNAL_ACTIVATED`: External type activated
- *
- * Widgets DON'T parse messages - they react to these events.
- * This keeps parsing logic centralized in the evaluator.
- *
- * ## Processing Flow
- *
- * ```
- * User Message → Evaluator.validate() → Should we run?
- *                        ↓ Yes
- *              Evaluator.handler() →
- *                        ↓
- *              quickIntentDetect() → Fast path for English
- *                        ↓ No match
- *              llmIntentAndExtract() → LLM fallback
- *                        ↓
- *              Handle intent (submit, stash, cancel, undo, etc.)
- *                        ↓
- *              Process extractions (update fields OR subfields)
- *                        ↓
- *              Emit events (FORM_FIELD_EXTRACTED, etc.)
- *                        ↓
- *              Check composite types → Activate if all subfields filled
- *                        ↓
- *              Save session
- * ```
- *
- * ## Why Evaluator (Not Action)
- *
- * We use an evaluator because:
- *
- * 1. **Runs Always**: Evaluators run on every message, not just when
- *    explicitly invoked. Form extraction should happen automatically.
- *
- * 2. **Post-Processing**: Evaluators run after actions, allowing the
- *    provider to set context and REPLY action to generate response.
- *
- * 3. **No Response Generation**: Evaluators don't generate responses,
- *    they just update state. The agent (REPLY) handles responses.
- *
- * ## Intent Handling
- *
- * Different intents are handled differently:
- *
- * - **Lifecycle** (submit, stash, cancel): Change session status
- * - **UX** (undo, skip, autofill): Modify session without status change
- * - **Info** (explain, example, progress): No state change, just context
- * - **Data** (fill_form): Extract and update field values
- *
- * ## FORM_RESTORE Exception
- *
- * The 'restore' intent is handled by FORM_RESTORE action, not here.
- * This is because restore needs to happen BEFORE the provider runs,
- * so the agent has the restored form context for its response.
- */
-import type { Evaluator } from "@elizaos/core";
-/**
- * Form Evaluator
- *
- * Runs after each message to:
- * 1. Detect user intent (fast path for English, LLM fallback for other languages)
- * 2. Extract field values from natural language
- * 3. Handle lifecycle intents (submit, stash, cancel)
- * 4. Handle UX intents (undo, skip, explain, example, progress, autofill)
- * 5. Update session state
- */
-export declare const formEvaluator: Evaluator;
-export default formEvaluator;
-//# sourceMappingURL=extractor.d.ts.map

package/dist/evaluators/extractor.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"extractor.d.ts","sourceRoot":"","sources":["../../src/evaluators/extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AAEH,OAAO,KAAK,EAGV,SAAS,EAMV,MAAM,eAAe,CAAC;AAavB;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,EAAE,SA+N3B,CAAC;AA2UF,eAAe,aAAa,CAAC"}

package/dist/extraction.d.ts

@@ -1,105 +0,0 @@
-/**
- * @module extraction
- * @description LLM-based field extraction from natural language
- *
- * ## Design Philosophy
- *
- * Unlike traditional forms where users fill in specific fields, agent-native
- * forms let users provide information naturally. The user might say:
- *
- * "I'm John, 25 years old, and my email is john@example.com"
- *
- * This module extracts: { name: "John", age: 25, email: "john@example.com" }
- *
- * ## Why LLM Extraction
- *
- * 1. **Natural Language**: Users don't think in form fields
- * 2. **Babble Support**: One message can fill multiple fields
- * 3. **Correction Handling**: "Actually, my name is Jon not John"
- * 4. **Ambiguity Resolution**: LLM can ask for clarification
- *
- * ## Extraction Flow
- *
- * 1. Build a prompt with field definitions and user message
- * 2. Ask LLM to extract values and assess confidence
- * 3. Parse LLM's structured response
- * 4. Validate extracted values against control rules
- * 5. Return results with confidence scores
- *
- * ## Confidence Scores
- *
- * Each extraction has a confidence score (0-1):
- * - 0.9-1.0: High confidence, auto-accept
- * - 0.7-0.9: Medium confidence, might auto-accept
- * - 0.5-0.7: Low confidence, ask for confirmation
- * - 0.0-0.5: Very low, probably wrong
- *
- * The threshold is configurable per-field (FormControl.confirmThreshold).
- *
- * ## Bundled Intent + Extraction
- *
- * We detect intent AND extract values in a single LLM call because:
- * - Reduces latency (one call vs two)
- * - Context helps with both tasks
- * - Intent affects what to extract
- */
-import type { IAgentRuntime, JsonValue } from "@elizaos/core";
-import type { FormControl, FormDefinition, ExtractionResult, IntentResult } from "./types";
-import type { TemplateValues } from "./template";
-/**
- * Extract field values and detect intent from user message using LLM.
- *
- * This is the main extraction function called by the evaluator.
- * It combines intent detection with field extraction in a single call.
- *
- * WHY single call:
- * - LLM calls are expensive (latency and cost)
- * - Intent and extraction share context
- * - More accurate when done together
- *
- * @param runtime - Agent runtime for model access
- * @param text - User message text
- * @param form - Form definition for context
- * @param controls - Fields to extract
- * @returns Intent result with extractions
- */
-export declare function llmIntentAndExtract(runtime: IAgentRuntime, text: string, form: FormDefinition, controls: FormControl[], templateValues?: TemplateValues): Promise<IntentResult>;
-/**
- * Extract a specific field value from user message.
- *
- * Used when asking for a specific field and expecting direct answer.
- * Simpler prompt than full intent+extraction.
- *
- * WHY separate function:
- * - When context is clear, full extraction is overkill
- * - "What's your email?" -> "john@example.com" is simple
- * - Faster, more focused extraction
- *
- * @param runtime - Agent runtime for model access
- * @param text - User message text
- * @param control - The field to extract
- * @param debug - Enable debug logging
- * @returns Extraction result or null if not found
- */
-export declare function extractSingleField(runtime: IAgentRuntime, text: string, control: FormControl, debug?: boolean, templateValues?: TemplateValues): Promise<ExtractionResult | null>;
-/**
- * Detect if user is correcting a previous value.
- *
- * Looks for patterns like:
- * - "Actually, my name is Jon not John"
- * - "Sorry, I meant jon@gmail.com"
- * - "Change my age to 26"
- *
- * WHY separate from main extraction:
- * - Correction detection needs current values as context
- * - More focused prompt for better accuracy
- * - Can be skipped if no values exist
- *
- * @param runtime - Agent runtime for model access
- * @param text - User message text
- * @param currentValues - Currently filled values
- * @param controls - Field definitions
- * @returns Array of corrections (empty if no corrections)
- */
-export declare function detectCorrection(runtime: IAgentRuntime, text: string, currentValues: Record<string, JsonValue>, controls: FormControl[], templateValues?: TemplateValues): Promise<ExtractionResult[]>;
-//# sourceMappingURL=extraction.d.ts.map

package/dist/extraction.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"extraction.d.ts","sourceRoot":"","sources":["../src/extraction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE9D,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,YAAY,EAEb,MAAM,SAAS,CAAC;AAGjB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AA2CjD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,WAAW,EAAE,EACvB,cAAc,CAAC,EAAE,cAAc,GAC9B,OAAO,CAAC,YAAY,CAAC,CAsHvB;AA6GD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,WAAW,EACpB,KAAK,CAAC,EAAE,OAAO,EACf,cAAc,CAAC,EAAE,cAAc,GAC9B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAuElC;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EACxC,QAAQ,EAAE,WAAW,EAAE,EACvB,cAAc,CAAC,EAAE,cAAc,GAC9B,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAwG7B"}

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAA+B,MAAM,eAAe,CAAC;AAOzE,cAAc,SAAS,CAAC;AAOxB,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AAOpB,OAAO,EACL,aAAa,EACb,WAAW,EACX,UAAU,EACV,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAOtB,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,UAAU,EACV,gBAAgB,GACjB,MAAM,UAAU,CAAC;AAOlB,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,cAAc,EACd,cAAc,EACd,eAAe,EACf,gBAAgB,GACjB,MAAM,WAAW,CAAC;AAOnB,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAOtB,OAAO,EACL,YAAY,EACZ,WAAW,EACX,cAAc,EACd,SAAS,EACT,mBAAmB,EACnB,mBAAmB,EACnB,YAAY,GACb,MAAM,OAAO,CAAC;AAOf,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAO/E,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,WAAW,CAAC;AAOjE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAQxC,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAG1D,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAGvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAUtD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU,EAAE,MAoFxB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/intent.d.ts

@@ -1,116 +0,0 @@
-/**
- * @module intent
- * @description Two-tier intent detection for form interactions
- *
- * ## Design Rationale
- *
- * Intent detection determines what the user wants to do:
- * - Fill form fields? Submit? Cancel? Undo?
- *
- * We use a two-tier approach:
- *
- * ### Tier 1: Fast Path (English Keywords)
- *
- * Simple regex matching for common English phrases. This is:
- * - **Fast**: No LLM call, instant response
- * - **Reliable**: Simple patterns rarely fail
- * - **Limited**: Only works for English, explicit commands
- *
- * Used for: "submit", "undo", "cancel", "skip", etc.
- *
- * ### Tier 2: LLM Fallback
- *
- * When fast path returns null, we use LLM for:
- * - **Non-English**: "enviar" (Spanish for "submit")
- * - **Ambiguous**: "I think I'm done?" (submit or just commenting?)
- * - **Complex**: Multi-part messages with intent + data
- *
- * The LLM call also extracts field values, so we bundle
- * intent detection with extraction to save latency.
- *
- * ## Why Fast Path First
- *
- * 1. **Latency**: LLM calls take 500ms-2s. Fast path is <1ms.
- * 2. **Cost**: Each LLM call has token cost. Fast path is free.
- * 3. **Reliability**: Regex patterns are deterministic. LLM can be unpredictable.
- *
- * ## Intent Categories
- *
- * **Lifecycle Intents** - Change session state:
- * - submit, stash, restore, cancel
- *
- * **UX Intents** - Helper actions:
- * - undo, skip, explain, example, progress, autofill
- *
- * **Data Intents** - Provide information:
- * - fill_form (with extractions)
- *
- * **Fallback**:
- * - other (unknown intent, may still have data)
- */
-import type { FormIntent } from "./types";
-/**
- * Quick intent detection using English keywords.
- *
- * Fast path for common English phrases - avoids LLM call for obvious intents.
- * Returns null if no match found, triggering LLM fallback.
- *
- * WHY regex-based:
- * - Deterministic - same input always gives same output
- * - Fast - no API calls, no parsing
- * - Easy to add patterns
- *
- * WHY word boundaries (\b):
- * - Prevents false matches ("undoing" matching "undo")
- * - Allows matching in context ("I want to cancel")
- *
- * @param text - User message text
- * @returns Detected intent or null if no fast-path match
- */
-export declare function quickIntentDetect(text: string): FormIntent | null;
-/**
- * Check if intent is a lifecycle intent (affects session state).
- *
- * Lifecycle intents:
- * - submit: Completes the form
- * - stash: Saves for later
- * - restore: Resumes a saved form
- * - cancel: Abandons the form
- *
- * WHY this helper:
- * - Lifecycle intents need special handling
- * - Often preempt normal message processing
- * - May need confirmation (e.g., cancel)
- */
-export declare function isLifecycleIntent(intent: FormIntent): boolean;
-/**
- * Check if intent is a UX intent (doesn't directly provide data).
- *
- * UX intents:
- * - undo: Revert last change
- * - skip: Skip optional field
- * - explain: "Why do you need this?"
- * - example: "Give me an example"
- * - progress: "How far am I?"
- * - autofill: "Use my saved values"
- *
- * WHY this helper:
- * - UX intents are helper actions
- * - Don't extract data, just modify session or provide info
- * - Agent response is informational
- */
-export declare function isUXIntent(intent: FormIntent): boolean;
-/**
- * Check if intent likely contains data to extract.
- *
- * Data intents:
- * - fill_form: User is providing field values
- * - other: Unknown intent, may have data
- *
- * WHY this helper:
- * - Determines if we should run extraction
- * - fill_form and other may have inline data
- * - Lifecycle and UX intents don't have data
- */
-export declare function hasDataToExtract(intent: FormIntent): boolean;
-//# sourceMappingURL=intent.d.ts.map

package/dist/intent.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"intent.d.ts","sourceRoot":"","sources":["../src/intent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAgIjE;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAE7D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAStD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAE5D"}