@agentix-e/nl2spel 1.2.2 → 1.4.0

package/dist/index.d.ts

@@ -38,6 +38,9 @@ interface LLMProvider {
 }
 /**
  * LLMProvider capability declaration.
+ *
+ * Declares what the provider CAN do — facts the engine can verify.
+ * Provider ordering is user-controlled via {@link ProviderRegistry.register} priority.
  */
 interface LLMCapabilities {
     /** Maximum context window (tokens) */
@@ -48,14 +51,8 @@ interface LLMCapabilities {
     supportsStreaming: boolean;
     /** Whether Structured Output (JSON mode) is supported */
     supportsStructuredOutput: boolean;
-    /** Whether available offline */
+    /** Whether available offline (no network required) */
     offlineAvailable: boolean;
-    /**
-     * Estimated cost per request (USD)
-     */
-    estimatedCostPerRequest?: number;
-    /** Estimated latency (ms) */
-    estimatedLatencyMs: number;
 }
 /**
  * Standardized LLM Prompt structure.
@@ -148,24 +145,36 @@ interface LLMUsage {
 /**
  * ProviderRegistry — manages registered LLMProvider instances.
  *
- * Responsibilities:
- * 1. Register/unregister Providers
- * 2. Sort by priority (offline first > low latency > high accuracy)
- * 3. Look up Providers by name (for forced selection)
+ * Provider ordering is user-controlled:
+ * 1. Offline providers first (engine-enforced — offline capability is a binary fact)
+ * 2. User-assigned priority (lower = preferred; default = registration order)
+ * 3. Registration order (tiebreaker when priorities are equal)
  */
 declare class ProviderRegistry {
     private _providers;
-    /** Register a Provider */
-    register(provider: LLMProvider): void;
+    private _nextIndex;
+    /**
+     * Register a Provider.
+     * @param provider LLMProvider instance
+     * @param options.priority User-assigned priority (lower = preferred). Defaults to registration order.
+     */
+    register(provider: LLMProvider, options?: {
+        priority?: number;
+    }): void;
     /** Unregister a Provider */
     unregister(name: string): void;
     /** Get a Provider by name */
     get(name: string): LLMProvider | undefined;
     /**
      * Get available Providers sorted by priority.
-     * Sort rule: offline > low cost > low latency > high accuracy
+     * Sort rule: offline first → user priority (asc) → registration order (asc)
      */
     getPrioritized(): Promise<LLMProvider[]>;
+    /**
+     * Explicitly reorder providers by name.
+     * Providers not listed retain their position after the reordered ones.
+     */
+    reorder(providerNames: string[]): void;
     /** List all registered Providers */
     list(): LLMProvider[];
     /** Number of registered Providers */
@@ -325,6 +334,25 @@ interface SlotDefinition {
 }
 type SlotTransform = 'toNumber' | 'toBoolean' | 'toString' | 'trim' | 'lowercase' | 'normalize';
 
+/**
+ * How to treat a field word the dictionary does not know.
+ *
+ * `passthrough` emits the word verbatim, which is legal Spring — `Character.isLetter`
+ * accepts any Unicode letter — and is the default, because a caller whose schema
+ * uses Chinese property names depends on it. `strict` refuses instead, for callers
+ * who would rather see an error than an unresolved name.
+ */
+type FieldPolicy = 'passthrough' | 'strict';
+/** Thrown under `strict` when a field word has no dictionary entry. */
+declare class UnmappedFieldError extends Error {
+    /** The field word that could not be resolved. */
+    readonly field: string;
+    constructor(field: string);
+}
+interface PatternMatcherOptions {
+    /** How to treat a field word with no dictionary entry. Default `passthrough`. */
+    fieldPolicy?: FieldPolicy;
+}
 interface PatternMatchResult {
     /** Whether matched */
     matched: boolean;
@@ -338,13 +366,17 @@ interface PatternMatchResult {
     latencyMs: number;
     /** Extracted slot values */
     slots?: Record<string, string>;
+    /**
+     * Field words emitted verbatim because the dictionary had no entry, in
+     * encounter order. Populated under either policy, so a caller can always see
+     * what was not resolved rather than having to infer it.
+     */
+    unmappedFields?: string[];
 }
-/**
- * PatternMatcher — Layer 0 pattern matching core.
- */
 declare class PatternMatcher {
     private _patterns;
-    constructor(patterns?: PatternDefinition[]);
+    private readonly fieldPolicy;
+    constructor(patterns?: PatternDefinition[], options?: PatternMatcherOptions);
     get patternCount(): number;
     register(pattern: PatternDefinition): void;
     registerAll(patterns: PatternDefinition[]): void;
@@ -365,18 +397,29 @@ declare class PatternMatcher {
      * Infer SpEL root object name from Chinese input
      */
     private inferRoot;
+    /**
+     * The first whitespace- or punctuation-delimited chunk of `input`.
+     */
+    private firstWord;
     /**
      * Extract Chinese field names from input and map to SpEL fields
      */
     private extractChineseField;
     /**
-     * Template filling and value transformation
+     * Resolve a captured field word into the identifier to emit, and report whether
+     * the dictionary recognised it.
+     *
+     * An ASCII word is already an identifier and is emitted unchanged. Anything else
+     * is looked up: a word the dictionary knows becomes its English identifier, and a
+     * word it does not know is emitted verbatim and reported as unmapped. Emitting it
+     * verbatim is legal Spring, but it is a guess about the caller's schema, so the
+     * guess is never silent.
      */
-    private fillTemplate;
+    private resolveField;
     /**
-     * Infer SpEL field name from capture group
+     * Template filling and value transformation
      */
-    private inferFieldFromCapture;
+    private fillTemplate;
 }
 
 /**
@@ -390,6 +433,60 @@ declare class PatternMatcher {
  */
 declare const BUILTIN_PATTERNS: PatternDefinition[];
 
+/**
+ * Clause decomposition for compound natural-language rules.
+ *
+ * A single comparison pattern matches a prefix and ignores the rest, so a
+ * sentence that joins two conditions is silently answered with only the first
+ * one: `金额大于1000且订单已确认` used to produce `#amount > 1000`, dropping the
+ * confirmation requirement entirely. The result parses, so nothing downstream
+ * notices — a materially weaker rule than the one that was asked for.
+ *
+ * This module splits such a sentence on its top-level logical connectors, has the
+ * caller convert each clause independently, and joins the results with SpEL's
+ * `and`/`or`. A clause that cannot be converted is reported rather than dropped:
+ * a partial rule is never emitted.
+ */
+interface Clause {
+    /** Clause text, trimmed. */
+    text: string;
+    /**
+     * How this clause attaches to the previous one. The first clause carries
+     * `'and'`, which is never used because a single clause needs no join.
+     */
+    connector: 'and' | 'or';
+}
+/** Raised when a compound sentence contains a clause that cannot be converted. */
+declare class UnconvertibleClauseError extends Error {
+    /** The clause texts that could not be converted. */
+    readonly unconvertible: readonly string[];
+    /** The full input that was being decomposed. */
+    readonly input: string;
+    constructor(input: string, unconvertible: readonly string[]);
+}
+/**
+ * Split `input` on its top-level logical connectors.
+ *
+ * Returns a single clause when there is no top-level connector, so the caller can
+ * treat "one clause" and "no decomposition needed" identically.
+ */
+declare function splitClauses(input: string): Clause[];
+interface Decomposition {
+    /** The joined expression, with every operand parenthesised. */
+    expression: string;
+    /** The clause texts, in order. */
+    clauses: string[];
+}
+/**
+ * Decompose `input` and convert every clause with `convert`.
+ *
+ * Returns `null` when the input has no top-level connector — the caller should
+ * run its ordinary single-pass conversion instead. Throws
+ * {@link UnconvertibleClauseError} when any clause cannot be converted, so a
+ * partially understood sentence is never answered with a partial rule.
+ */
+declare function decompose(input: string, convert: (clause: string) => string | null): Decomposition | null;
+
 /**
  * NLIntent — Natural language intent classification system.
  *
@@ -505,6 +602,22 @@ declare class TemplateEngine {
     generate(input: string, intentResult: IntentResult): TemplateResult | null;
     private selectBestTemplate;
     private fillTemplate;
+    /**
+     * Resolve the SpEL root name for `input`: the configured schema root when one
+     * exists, otherwise a keyword heuristic over the well-known roots.
+     */
+    private resolveRootName;
+    /**
+     * Resolve the field name for `input`.
+     *
+     * The previous implementation only compared schema *keys* and otherwise left
+     * the literal placeholder default in place, which is how "#order.field == null"
+     * reached callers. The lookup now falls back in order: schema key, schema
+     * field description (Chinese inputs name the field by its description),
+     * Chinese field word, first English identifier, and finally "value" — the
+     * neutral default the pattern layer already uses for an unknown field.
+     */
+    private resolveFieldName;
 }
 
 interface PromptBuilderOptions {
@@ -525,6 +638,10 @@ declare class PromptBuilder {
     private buildExamples;
 }
 
+/** Stage a diagnostic was produced by. */
+type ValidationStage = 'parse' | 'type' | 'semantic' | 'context' | 'final';
+/** Whether a diagnostic rejects the expression or merely observes it. */
+type ValidationSeverity = 'error' | 'warning';
 interface ValidationResult {
     /** Whether all validation stages passed */
     valid: boolean;
@@ -534,6 +651,7 @@ interface ValidationResult {
         type: StageResult;
         semantic: StageResult;
         context: StageResult;
+        final: StageResult;
     };
     /** All errors */
     errors: ValidationError[];
@@ -548,28 +666,38 @@ interface StageResult {
 interface ValidationError {
     code: string;
     message: string;
+    /** Severity of this diagnostic — always `error`. */
+    severity?: ValidationSeverity;
     /** Error position in expression */
     position?: number;
     /** Stage the error belongs to */
-    stage: 'parse' | 'type' | 'semantic' | 'context';
+    stage: ValidationStage;
     /** Whether LLM regeneration is needed */
     requiresLLM?: boolean;
 }
 interface ValidationWarning {
     code: string;
     message: string;
+    /** Severity of this diagnostic — always `warning`. */
+    severity?: ValidationSeverity;
     /** Warning position in expression */
     position?: number;
     /** Stage the warning belongs to */
-    stage: 'parse' | 'type' | 'semantic' | 'context';
+    stage: ValidationStage;
 }
 /**
- * ValidationPipeline — four-stage validation pipeline.
+ * ValidationPipeline — five-stage validation pipeline.
+ *
+ * 1. Parse: syntax validity (empty, delimiter balance, JS operators, evaluator)
+ *    2. Type: type checking (operator-operand type matching) — advisory
+ *    3. Semantic: semantic reasonableness — advisory
+ *    4. Context: context references (do all references exist in ContextSchema)
+ *    5. Final: the expression must parse — structural completeness gate
  *
- * 1. Parse: syntax validity (depends on SpelEvaluator)
- * 2. Type: type checking (operator-operand type matching)
- * 3. Semantic: semantic reasonableness (is the expression meaningful)
- * 4. Context: context references (do all references exist in ContextSchema)
+ * Stages 1, 4 and 5 can reject an expression; the type and semantic stages only
+ * observe. Reference checks are only meaningful when a schema is supplied,
+ * because without one an undeclared `#unknownRef` and a legitimate runtime
+ * variable are indistinguishable.
  */
 declare class ValidationPipeline {
     private evaluator;
@@ -581,36 +709,103 @@ declare class ValidationPipeline {
     validate(expression: string, contextSchema?: ContextSchema): Promise<ValidationResult>;
     /**
      * Stage 1: Parse Check — syntax validation
+     *
+     * Delimiter balance and JavaScript operators are checked against a copy of
+     * the expression with string literals blanked out, so literal text can never
+     * be mistaken for syntax.
      */
     private validateParse;
     /**
-     * Stage 2: Type Check — type validation
+     * Stage 2: Type Check — advisory type validation
      */
     private validateTypes;
     /**
-     * Stage 3: Semantic Check — semantic reasonableness validation
+     * Stage 3: Semantic Check — advisory semantic validation
      */
     private validateSemantic;
     /**
      * Stage 4: Context Check — context reference validation
+     *
+     * A supplied schema turns this stage into a real gate: an undeclared bean,
+     * a missing root field or an undeclared variable is an error. Without a
+     * schema nothing can be judged, so the stage stays advisory.
      */
     private validateContext;
     /**
-     * Check if parentheses are balanced
+     * Stage 5: Final Check — the generated expression must parse.
+     *
+     * When an evaluator is configured the parse stage already performed a real
+     * parse; this mandatory final gate adds the structural check that a truncated
+     * tail (an expression ending on an operator) is never accepted, even when no
+     * engine is wired in. It is deliberately conservative: only a trailing
+     * operator or an unterminated literal fails, so no well-formed expression is
+     * rejected.
+     */
+    private validateFinal;
+    /**
+     * Whether the expression is obviously incomplete.
+     *
+     * The last token is obtained from spel-ts's tokenizer, so a trailing
+     * operator keyword or an unterminated string literal is detected exactly,
+     * and text inside a literal is never read as a trailing operator.
+     */
+    private isManifestlyIncomplete;
+    /**
+     * Check if parentheses are balanced. Expects a literal-masked expression.
      */
     private hasBalancedParentheses;
     /**
-     * Extract all identifier references from expression
+     * Extract all identifier references from expression.
+     *
+     * A bare `#x` that is only the head of a dotted reference (`#x.y`) is not
+     * emitted on its own: a dotted reference names a property of some object,
+     * not a variable of that name.
      */
     private extractReferences;
 }
 
 /**
- * AutoFixer — automatically fixes common SpEL syntax errors from LLM output.
+ * AutoFixer — rewrites the JavaScript spellings an LLM commonly emits into the
+ * SpEL equivalents, without ever touching the contents of a string literal.
+ *
+ * Literal boundaries come from a quote-state scan. In SpEL a quote character is
+ * always a string-literal delimiter — the language has no comments and no other
+ * construct that uses `'` or `"` — so the scan is exact by construction rather
+ * than an approximation of the parser. It is also independent of the engine
+ * build: deriving the boundaries from the lexer made every structural check
+ * depend on the lexer being able to tokenize the *whole* expression, which fails
+ * for input the engine cannot lex at all, such as a field name in Chinese on a
+ * build without Unicode identifier support. A whole-string regex (the previous
+ * implementation) rewrote literal contents and appended closers for delimiters
+ * it could only see inside literals, turning valid expressions into broken
+ * ones.
  */
 declare class AutoFixer {
     fix(expression: string): AutoFixResult;
-    private fixAllBrackets;
+    /**
+     * Apply one global replacement rule to every unprotected chunk.
+     *
+     * The replacement is only reported when it actually matched, and the count
+     * is the number of matches across all chunks, so the human-readable change
+     * log is unchanged from the previous implementation.
+     */
+    private applyRule;
+    /**
+     * Normalise the Elvis operator only when it was written with whitespace
+     * between `?` and `:`. A correctly written `?:` must be left untouched so
+     * that `fix()` is a no-op on already-valid input.
+     */
+    private applyElvisRule;
+    /**
+     * Split the expression into alternating protected (string literal) and
+     * unprotected chunks. Ranges come from spel-ts's tokenizer so they agree
+     * exactly with what the parser considers opaque.
+     */
+    private split;
+    /**
+     * Turn protected spans into a chunk list covering the whole expression.
+     */
+    private toChunks;
 }
 interface AutoFixResult {
     expression: string;
@@ -676,6 +871,8 @@ interface StrategyResult {
 interface StrategyMetadata {
     /** Matched pattern ID (pattern strategy only) */
     patternId?: string;
+    /** Clause texts, when a compound sentence was decomposed */
+    clauses?: string[];
     /** Intent type (template strategy only) */
     intent?: string;
     /** Template name (template strategy only) */
@@ -689,6 +886,15 @@ interface StrategyMetadata {
     /** Raw LLM output (llm strategy only) */
     rawOutput?: string;
 }
+/** A compound sentence converted clause by clause. */
+interface DecomposedConversion {
+    /** The joined expression, with every operand parenthesised. */
+    expression: string;
+    /** The clause texts, in order. */
+    clauses: string[];
+    /** The lowest confidence among the converted clauses. */
+    confidence: number;
+}
 interface StrategyRouterConfig {
     /** Pattern confidence threshold (default 0.7) */
     patternMinConfidence?: number;
@@ -718,6 +924,15 @@ declare class StrategyRouter {
     /**
      * Get PatternMatcher (for external testing/debugging)
      */
+    /**
+     * Convert a sentence that joins its clauses with a logical connector.
+     *
+     * Returns `null` when `nl` has no top-level connector, in which case the caller
+     * should use its ordinary single-pass conversion. Throws
+     * {@link UnconvertibleClauseError} when a clause cannot be converted, so the
+     * caller can refuse instead of emitting a partial rule.
+     */
+    decomposeClauses(nl: string): DecomposedConversion | null;
     getPatternMatcher(): PatternMatcher;
     /**
      * Get TemplateEngine
@@ -905,4 +1120,4 @@ declare class ChineseNumberParser {
     static parseSafe(text: string): number | null;
 }
 
-export { type AutoFixResult, AutoFixer, BUILTIN_PATTERNS, ChineseNumberParser, ContextExtractor, type CorrectionLog, type DebugInfo, type ExplainResult, type FewShotExample, type GenerateOptions, type GenerateResult, IntentClassifier, type IntentEntity, type IntentResult, type LLMCapabilities, type LLMGenerateOptions, type LLMPrompt, type LLMProvider, type LLMResponse, type LLMStreamChunk, type LLMUsage, NL2SpelEngine, NLIntent, type PatternDefinition, type PatternMatchResult, PatternMatcher, PromptBuilder, type PromptBuilderOptions, ProviderRegistry, SchemaFormatter, type SelfCorrectionConfig, SelfCorrectionLoop, type SelfCorrectionResult, type SlotDefinition, type SlotTransform, type StageResult, type StrategyMetadata, type StrategyResult, StrategyRouter, type StrategyRouterConfig, type StrategyType, TemplateEngine, type TemplateResult, type ValidationError, ValidationPipeline, type ValidationResult, type ValidationWarning };
+export { type AutoFixResult, AutoFixer, BUILTIN_PATTERNS, ChineseNumberParser, type Clause, ContextExtractor, type CorrectionLog, type DebugInfo, type Decomposition, type ExplainResult, type FewShotExample, type FieldPolicy, type GenerateOptions, type GenerateResult, IntentClassifier, type IntentEntity, type IntentResult, type LLMCapabilities, type LLMGenerateOptions, type LLMPrompt, type LLMProvider, type LLMResponse, type LLMStreamChunk, type LLMUsage, NL2SpelEngine, NLIntent, type PatternDefinition, type PatternMatchResult, PatternMatcher, type PatternMatcherOptions, PromptBuilder, type PromptBuilderOptions, ProviderRegistry, SchemaFormatter, type SelfCorrectionConfig, SelfCorrectionLoop, type SelfCorrectionResult, type SlotDefinition, type SlotTransform, type StageResult, type StrategyMetadata, type StrategyResult, StrategyRouter, type StrategyRouterConfig, type StrategyType, TemplateEngine, type TemplateResult, UnconvertibleClauseError, UnmappedFieldError, type ValidationError, ValidationPipeline, type ValidationResult, type ValidationWarning, decompose, splitClauses };