@agentix-e/nl2spel 1.2.1 → 1.3.0

package/dist/index.d.cts

@@ -0,0 +1,917 @@
+import { ContextSchema, SpelEvaluator } from '@agentix-e/spel-ts';
+export { BeanSchema, ContextSchema, FieldSchema, FunctionSchema, MethodSchema, ParseError, ParseResult, RootObjectSchema, SpelEvaluator, TypeSchema, VariableSchema } from '@agentix-e/spel-ts';
+
+/**
+ * LLMProvider interface — NL2Spel's pluggable LLM contract.
+ *
+ * Design principles:
+ * 1. Minimal interface: only exposes generate + generateStream + lifecycle
+ * 2. Capability declaration: capabilities let StrategyRouter make routing decisions
+ * 3. Async lifecycle: supports Providers that need init/dispose (e.g. WebLLM)
+ * 4. Stream support: optional generateStream for progressive generation
+ */
+interface LLMProvider {
+    /** Provider unique name, used for logging/debugging/Provider selection */
+    readonly name: string;
+    /** Provider capability declaration */
+    readonly capabilities: LLMCapabilities;
+    /**
+     * Generate a SpEL expression (core method)
+     */
+    generate(prompt: LLMPrompt, options?: LLMGenerateOptions): Promise<LLMResponse>;
+    /**
+     * Stream generate a SpEL expression (optional implementation)
+     */
+    generateStream?(prompt: LLMPrompt, options?: LLMGenerateOptions): AsyncIterable<LLMStreamChunk>;
+    /**
+     * Check if the Provider is currently available
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Initialize the Provider (optional)
+     */
+    initialize?(): Promise<void>;
+    /**
+     * Release Provider resources (optional)
+     */
+    dispose?(): Promise<void>;
+}
+/**
+ * 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) */
+    maxContextTokens: number;
+    /** Whether Grammar Constraint (GBNF, etc.) is supported */
+    supportsGrammarConstraint: boolean;
+    /** Whether streaming output is supported */
+    supportsStreaming: boolean;
+    /** Whether Structured Output (JSON mode) is supported */
+    supportsStructuredOutput: boolean;
+    /** Whether available offline (no network required) */
+    offlineAvailable: boolean;
+}
+/**
+ * Standardized LLM Prompt structure.
+ */
+interface LLMPrompt {
+    /** System prompt */
+    system: string;
+    /** User input */
+    user: string;
+    /** Context Schema */
+    contextSchema: ContextSchema;
+    /** Few-Shot example list */
+    examples: FewShotExample[];
+    /** Grammar constraint string (GBNF format) */
+    grammar?: string;
+}
+/**
+ * Few-Shot example
+ */
+interface FewShotExample {
+    /** Natural language input */
+    nl: string;
+    /** Expected SpEL expression */
+    spel: string;
+    /** Difficulty level */
+    difficulty: 'easy' | 'medium' | 'hard';
+    /** Category */
+    category: string;
+}
+/**
+ * LLM generation options
+ */
+interface LLMGenerateOptions {
+    /** Temperature (0-2), default 0.1 */
+    temperature?: number;
+    /** Maximum output tokens */
+    maxTokens?: number;
+    /** Top-p sampling */
+    topP?: number;
+    /** Stop sequences */
+    stopSequences?: string[];
+    /** Whether to enable stream */
+    stream?: boolean;
+    /** Custom model override */
+    model?: string;
+    /** Timeout (ms), default 30000 */
+    timeout?: number;
+    /** Maximum retry count */
+    maxRetries?: number;
+}
+/**
+ * LLM generation response
+ */
+interface LLMResponse {
+    /** Raw generated text */
+    text: string;
+    /** Actual model used */
+    model: string;
+    /** Token usage statistics */
+    usage: LLMUsage;
+    /** Generation latency (ms) */
+    latencyMs: number;
+    /** Finish reason */
+    finishReason: 'stop' | 'length' | 'content_filter' | 'error';
+    /** Provider name */
+    providerName: string;
+}
+/**
+ * LLM Stream Chunk
+ */
+interface LLMStreamChunk {
+    /** Delta text */
+    delta: string;
+    /** Accumulated text */
+    accumulated: string;
+    /** Whether done */
+    done: boolean;
+    /** Finish reason */
+    finishReason?: string;
+}
+/**
+ * Token usage statistics
+ */
+interface LLMUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+
+/**
+ * ProviderRegistry — manages registered LLMProvider instances.
+ *
+ * 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;
+    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 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 */
+    get count(): number;
+}
+
+/**
+ * ContextExtractor — builds a ContextSchema from plain data structures.
+ *
+ * Decoupled from any concrete SpEL implementation, accepts only:
+ *   - rootObject: any object (for extracting property types)
+ *   - variables: Record<string, { type: string; value?: unknown }>
+ *   - beans: string[]
+ *   - types: string[]
+ */
+declare class ContextExtractor {
+    /**
+     * Extract ContextSchema from plain data structures (no spel-ts dependency)
+     */
+    extract(context: {
+        rootObject?: unknown;
+        rootName?: string;
+        variables?: Record<string, {
+            type: string;
+            value?: unknown;
+            description?: string;
+            nullable?: boolean;
+        }>;
+        beans?: Array<{
+            name: string;
+            type: string;
+            description?: string;
+            singleton?: boolean;
+        }>;
+        types?: Array<{
+            name: string;
+            className?: string;
+            description?: string;
+        }>;
+        functions?: Array<{
+            name: string;
+            returnType: string;
+            params: Array<{
+                name: string;
+                type: string;
+            }>;
+            description?: string;
+        }>;
+    }): ContextSchema;
+    /**
+     * Extract root object schema
+     */
+    private extractRoot;
+    /**
+     * Extract object fields
+     */
+    /**
+     * Recursively extract fields from an object, following nested objects
+     * all the way to leaf values. Uses a visited set to prevent circular references.
+     */
+    private extractFields;
+    /**
+     * Infer SpEL type
+     */
+    private inferSpelType;
+    /**
+     * Generate field description
+     */
+    private generateDescription;
+    /**
+     * Safely get example value
+     */
+    private safeExample;
+    /**
+     * Extract variables
+     */
+    private extractVariables;
+    /**
+     * Extract beans
+     */
+    private extractBeans;
+    /**
+     * Extract types
+     */
+    private extractTypes;
+    /**
+     * Extract functions
+     */
+    private extractFunctions;
+}
+
+/**
+ * SchemaFormatter — formats ContextSchema into readable text.
+ *
+ * Two formats:
+ * 1. formatForLLM(): optimized for LLM prompts (compact, key info first)
+ * 2. formatForHuman(): human-readable format (complete, indent-friendly)
+ */
+declare class SchemaFormatter {
+    /**
+     * LLM-optimized format — compact, injected into the User part of the prompt
+     */
+    formatForLLM(schema: ContextSchema): string;
+    /**
+     * Human-readable format
+     */
+    formatForHuman(schema: ContextSchema): string;
+    private formatFieldForLLM;
+}
+
+/**
+ * Pattern definition — core data structures for Layer 0.
+ *
+ * Each PatternDefinition describes a mapping from natural language pattern to SpEL expression.
+ * Supports both Chinese and English languages.
+ */
+interface PatternDefinition {
+    /** Unique identifier */
+    id: string;
+    /**
+     * Match regex (at least one language)
+     * Uses named capture groups (?<slotName>...) to extract slots
+     */
+    match: RegExp;
+    /**
+     * SpEL template string
+     * Uses {slotName} placeholders to reference capture groups
+     */
+    spelTemplate: string;
+    /**
+     * Slot definitions (capture groups mapped to SpEL types)
+     */
+    slots: Record<string, SlotDefinition>;
+    /** Priority (0-100), higher priority matched first */
+    priority: number;
+    /** Tags (for classification and debugging) */
+    tags: string[];
+    /** Example input/output pairs */
+    examples: Array<{
+        nl: string;
+        spel: string;
+    }>;
+    /** Difficulty level */
+    difficulty: 'easy' | 'medium';
+    /** Confidence (0-1) */
+    confidence: number;
+}
+interface SlotDefinition {
+    /** Key appearing in spelTemplate */
+    key: string;
+    /** SpEL value type: 'number' | 'string' | 'boolean' | 'variable' | 'literal' */
+    type: 'number' | 'string' | 'boolean' | 'variable' | 'literal';
+    /** Optional: value transformer (e.g. Chinese numbers → number) */
+    transform?: SlotTransform;
+    /** Optional: default value */
+    defaultValue?: string;
+}
+type SlotTransform = 'toNumber' | 'toBoolean' | 'toString' | 'trim' | 'lowercase' | 'normalize';
+
+interface PatternMatchResult {
+    /** Whether matched */
+    matched: boolean;
+    /** The matching PatternDefinition */
+    pattern?: PatternDefinition;
+    /** Generated SpEL expression (if matched) */
+    spel?: string;
+    /** Confidence (0-1) */
+    confidence: number;
+    /** Match latency (ms) */
+    latencyMs: number;
+    /** Extracted slot values */
+    slots?: Record<string, string>;
+}
+/**
+ * PatternMatcher — Layer 0 pattern matching core.
+ */
+declare class PatternMatcher {
+    private _patterns;
+    constructor(patterns?: PatternDefinition[]);
+    get patternCount(): number;
+    register(pattern: PatternDefinition): void;
+    registerAll(patterns: PatternDefinition[]): void;
+    private sortByPriority;
+    /**
+     * Match natural language input, return the best match
+     */
+    match(nl: string): PatternMatchResult;
+    /**
+     * Batch match
+     */
+    matchAll(nl: string, maxResults?: number): PatternMatchResult[];
+    /**
+     * Input normalization
+     */
+    private normalize;
+    /**
+     * Infer SpEL root object name from Chinese input
+     */
+    private inferRoot;
+    /**
+     * Extract Chinese field names from input and map to SpEL fields
+     */
+    private extractChineseField;
+    /**
+     * Template filling and value transformation
+     */
+    private fillTemplate;
+    /**
+     * Infer SpEL field name from capture group
+     */
+    private inferFieldFromCapture;
+}
+
+/**
+ * Built-in pattern library — covers ≥80% Easy scenarios, 63 PatternDefinitions.
+ *
+ * Core design:
+ * 1. All patterns use named capture groups `(?<field>…)` or `(?<value>…)` to extract parameters
+ * 2. Separate Chinese/English patterns (don't mix keywords, avoids cross-language false matches)
+ * 3. High-specificity patterns have higher priority ("not empty" > "not")
+ * 4. Sorted by priority descending
+ */
+declare const BUILTIN_PATTERNS: PatternDefinition[];
+
+/**
+ * NLIntent — Natural language intent classification system.
+ *
+ * 15 intent types covering all common SpEL usage scenarios.
+ */
+declare enum NLIntent {
+    /** Numeric comparison: "amount > 100", "年龄大于18" */
+    COMPARISON = "COMPARISON",
+    /** Permission check: "hasRole('admin')", "用户是VIP" */
+    PERMISSION_CHECK = "PERMISSION_CHECK",
+    /** Null check: "== null", "!= null", "不为空" */
+    NULL_CHECK = "NULL_CHECK",
+    /** Logical combination: "a and b", "金额大于100且已确认" */
+    LOGICAL = "LOGICAL",
+    /** String matching: "contains('keyword')", "以ORD开头" */
+    STRING_MATCH = "STRING_MATCH",
+    /** Collection operations: "list.contains('x')", "items.isEmpty()" */
+    COLLECTION = "COLLECTION",
+    /** Range check: "between {1, 10}", "年龄在18到60之间" */
+    RANGE = "RANGE",
+    /** Selection (filter): ".?[condition]", "all matching conditions" */
+    SELECTION = "SELECTION",
+    /** Projection: ".![field]", "each item's name" */
+    PROJECTION = "PROJECTION",
+    /** Type check: "instanceof", "是否是Admin类型" */
+    TYPE_CHECK = "TYPE_CHECK",
+    /** Boolean property: "isVIP", "是否已支付" */
+    BOOLEAN = "BOOLEAN",
+    /** Date comparison: "after/before", "after a certain date" */
+    DATE = "DATE",
+    /** Elvis default: "a ?: default", "or default value" */
+    ELVIS = "ELVIS",
+    /** Assignment: "a = value", "set field to" */
+    ASSIGNMENT = "ASSIGNMENT",
+    /** Arithmetic: "amount * price", "total = unit price × quantity" */
+    ARITHMETIC = "ARITHMETIC"
+}
+
+/**
+ * Intent classification result
+ */
+interface IntentResult {
+    /** Primary intent (highest confidence) */
+    primaryIntent: NLIntent;
+    /** All possible intents with confidence scores */
+    intents: Array<{
+        intent: NLIntent;
+        confidence: number;
+    }>;
+    /** Extracted entities */
+    entities: IntentEntity[];
+    /** Recognized operators */
+    operators: string[];
+    /** Recognized logical connectors */
+    logicalConnectors: string[];
+    /** Complexity score (0-100) */
+    complexity: number;
+}
+interface IntentEntity {
+    text: string;
+    type: 'field' | 'value' | 'operator' | 'logic' | 'quantifier';
+    position: {
+        start: number;
+        end: number;
+    };
+}
+declare class IntentClassifier {
+    /**
+     * Main method for classifying natural language input
+     */
+    classify(input: string): IntentResult;
+    /**
+     * Entity extraction
+     */
+    private extractEntities;
+    /**
+     * Operator recognition
+     */
+    private extractOperators;
+    /**
+     * Logical connector recognition
+     */
+    private extractLogicalConnectors;
+    /**
+     * Complexity calculation
+     */
+    private calculateComplexity;
+    /**
+     * Input normalization
+     */
+    private normalize;
+}
+
+interface TemplateResult {
+    /** Generated SpEL expression */
+    expression: string;
+    /** Intent used */
+    intent: NLIntent;
+    /** Template name used */
+    templateName: string;
+    /** Confidence */
+    confidence: number;
+    /** Unfilled slots needing further LLM processing */
+    unfilledSlots: string[];
+}
+declare class TemplateEngine {
+    private contextSchema?;
+    constructor(contextSchema?: ContextSchema);
+    setContext(schema: ContextSchema): void;
+    /**
+     * Generate a SpEL expression based on intent classification results
+     */
+    generate(input: string, intentResult: IntentResult): TemplateResult | null;
+    private selectBestTemplate;
+    private fillTemplate;
+}
+
+interface PromptBuilderOptions {
+    /** Language (zh/en) */
+    language?: 'zh' | 'en';
+    /** Whether to include EBNF grammar block */
+    includeEBNF?: boolean;
+}
+declare class PromptBuilder {
+    private readonly formatter;
+    /**
+     * Build a complete LLM Prompt
+     */
+    build(userInput: string, contextSchema?: ContextSchema, options?: PromptBuilderOptions): LLMPrompt;
+    /**
+     * Build Few-Shot example string
+     */
+    private buildExamples;
+}
+
+interface ValidationResult {
+    /** Whether all validation stages passed */
+    valid: boolean;
+    /** Stage results */
+    stages: {
+        parse: StageResult;
+        type: StageResult;
+        semantic: StageResult;
+        context: StageResult;
+    };
+    /** All errors */
+    errors: ValidationError[];
+    /** All warnings */
+    warnings: ValidationWarning[];
+}
+interface StageResult {
+    passed: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+}
+interface ValidationError {
+    code: string;
+    message: string;
+    /** Error position in expression */
+    position?: number;
+    /** Stage the error belongs to */
+    stage: 'parse' | 'type' | 'semantic' | 'context';
+    /** Whether LLM regeneration is needed */
+    requiresLLM?: boolean;
+}
+interface ValidationWarning {
+    code: string;
+    message: string;
+    /** Warning position in expression */
+    position?: number;
+    /** Stage the warning belongs to */
+    stage: 'parse' | 'type' | 'semantic' | 'context';
+}
+/**
+ * ValidationPipeline — four-stage validation pipeline.
+ *
+ * 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)
+ */
+declare class ValidationPipeline {
+    private evaluator;
+    constructor(evaluator?: SpelEvaluator | null);
+    setEvaluator(evaluator: SpelEvaluator): void;
+    /**
+     * Run the full validation pipeline
+     */
+    validate(expression: string, contextSchema?: ContextSchema): Promise<ValidationResult>;
+    /**
+     * Stage 1: Parse Check — syntax validation
+     */
+    private validateParse;
+    /**
+     * Stage 2: Type Check — type validation
+     */
+    private validateTypes;
+    /**
+     * Stage 3: Semantic Check — semantic reasonableness validation
+     */
+    private validateSemantic;
+    /**
+     * Stage 4: Context Check — context reference validation
+     */
+    private validateContext;
+    /**
+     * Check if parentheses are balanced
+     */
+    private hasBalancedParentheses;
+    /**
+     * Extract all identifier references from expression
+     */
+    private extractReferences;
+}
+
+/**
+ * AutoFixer — automatically fixes common SpEL syntax errors from LLM output.
+ */
+declare class AutoFixer {
+    fix(expression: string): AutoFixResult;
+    private fixAllBrackets;
+}
+interface AutoFixResult {
+    expression: string;
+    wasFixed: boolean;
+    changes: string[];
+}
+
+interface SelfCorrectionResult {
+    /** Final expression */
+    expression: string;
+    /** Whether validation passed */
+    valid: boolean;
+    /** Original LLM output */
+    originalOutput: string;
+    /** Number of correction attempts */
+    correctionAttempts: number;
+    /** Log of each correction round */
+    corrections: CorrectionLog[];
+    /** Total latency (ms) */
+    totalLatencyMs: number;
+}
+interface CorrectionLog {
+    attempt: number;
+    expression: string;
+    valid: boolean;
+    errorCount: number;
+    warningCount: number;
+    autoFixed: boolean;
+    autoFixChanges: string[];
+}
+interface SelfCorrectionConfig {
+    /** Maximum correction attempts (default 3) */
+    maxAttempts?: number;
+    /** Minimum confidence threshold (default 0.7) */
+    minConfidence?: number;
+    /** Whether AutoFix is enabled (default true) */
+    enableAutoFix?: boolean;
+}
+declare class SelfCorrectionLoop {
+    private readonly pipeline;
+    private readonly autoFixer;
+    private readonly config;
+    constructor(config?: SelfCorrectionConfig, pipeline?: ValidationPipeline, autoFixer?: AutoFixer);
+    /**
+     * Execute the self-correction loop
+     */
+    correct(expression: string, contextSchema: ContextSchema, generateFn: (prompt: LLMPrompt) => Promise<LLMResponse>, originalPrompt: LLMPrompt): Promise<SelfCorrectionResult>;
+}
+
+type StrategyType = 'pattern' | 'template' | 'llm-api' | 'llm-fallback' | 'none';
+interface StrategyResult {
+    /** Generated SpEL expression */
+    expression: string;
+    /** Strategy used */
+    strategy: StrategyType;
+    /** Confidence (0-1) */
+    confidence: number;
+    /** Strategy-related metadata */
+    metadata: StrategyMetadata;
+    /** Generation latency (ms) */
+    latencyMs: number;
+}
+interface StrategyMetadata {
+    /** Matched pattern ID (pattern strategy only) */
+    patternId?: string;
+    /** Intent type (template strategy only) */
+    intent?: string;
+    /** Template name (template strategy only) */
+    templateName?: string;
+    /** LLM Provider name (llm strategy only) */
+    providerName?: string;
+    /** LLM model (llm strategy only) */
+    model?: string;
+    /** Correction count (llm strategy + self-correction only) */
+    corrections?: number;
+    /** Raw LLM output (llm strategy only) */
+    rawOutput?: string;
+}
+interface StrategyRouterConfig {
+    /** Pattern confidence threshold (default 0.7) */
+    patternMinConfidence?: number;
+    /** Template confidence threshold (default 0.6) */
+    templateMinConfidence?: number;
+    /** LLM confidence threshold (default 0.5) */
+    llmMinConfidence?: number;
+    /** Whether Self-Correction is enabled (default true) */
+    enableSelfCorrection?: boolean;
+    /** Maximum Self-Correction attempts (default 3) */
+    maxCorrectionAttempts?: number;
+}
+declare class StrategyRouter {
+    private readonly patternMatcher;
+    private readonly intentClassifier;
+    private readonly templateEngine;
+    private readonly promptBuilder;
+    private readonly validationPipeline;
+    private readonly autoFixer;
+    private readonly providerRegistry;
+    private readonly config;
+    constructor(providerRegistry: ProviderRegistry, config?: StrategyRouterConfig);
+    /**
+     * Execute the full generation strategy routing
+     */
+    generate(nl: string, contextSchema?: ContextSchema, forceLLMProvider?: string): Promise<StrategyResult>;
+    /**
+     * Get PatternMatcher (for external testing/debugging)
+     */
+    getPatternMatcher(): PatternMatcher;
+    /**
+     * Get TemplateEngine
+     */
+    getTemplateEngine(): TemplateEngine;
+    /**
+     * Get PromptBuilder
+     */
+    getPromptBuilder(): PromptBuilder;
+    /**
+     * Set SpelEvaluator for validation pipeline.
+     * Must be called before generate() if parse-level validation is needed.
+     */
+    setEvaluator(evaluator: SpelEvaluator): void;
+}
+
+interface GenerateOptions {
+    /** Context Schema (optional) */
+    contextSchema?: ContextSchema;
+    /** Raw context object (auto-extracted to ContextSchema) */
+    context?: {
+        rootObject?: unknown;
+        rootName?: string;
+        variables?: Record<string, {
+            type: string;
+            value?: unknown;
+            description?: string;
+            nullable?: boolean;
+        }>;
+        beans?: Array<{
+            name: string;
+            type: string;
+            description?: string;
+        }>;
+        types?: Array<{
+            name: string;
+            className?: string;
+            description?: string;
+        }>;
+    };
+    /** Force using a specific LLM Provider */
+    preferredProvider?: string;
+    /** Minimum confidence threshold (default 0.5) */
+    minConfidence?: number;
+    /** Offline only (Pattern + Template, no LLM calls) */
+    offlineOnly?: boolean;
+    /** Whether validation is enabled (default true) */
+    enableValidation?: boolean;
+    /** Whether self-correction is enabled (default true) */
+    enableSelfCorrection?: boolean;
+    /** Language (default auto-detect) */
+    language?: 'zh' | 'en';
+    /** Whether to return debug information */
+    debug?: boolean;
+}
+interface GenerateResult {
+    /** Generated SpEL expression */
+    expression: string;
+    /** Strategy used */
+    strategy: string;
+    /** Confidence (0-1) */
+    confidence: number;
+    /** Generation latency (ms) */
+    latencyMs: number;
+    /** Debug info (only when debug=true) */
+    debugInfo?: DebugInfo;
+}
+interface DebugInfo {
+    /** Pattern match result */
+    patternMatch?: {
+        matched: boolean;
+        patternId?: string;
+        spel?: string;
+    };
+    /** Intent classification result */
+    intent?: {
+        primary: string;
+        complexity: number;
+    };
+    /** Template generation result */
+    template?: {
+        expression?: string;
+        templateName?: string;
+    };
+    /** LLM Provider info */
+    provider?: {
+        name: string;
+        model: string;
+    };
+    /** Self-correction info */
+    corrections?: {
+        attempts: number;
+    };
+}
+interface ExplainResult {
+    /** Input text */
+    input: string;
+    /** Strategy used */
+    strategy: string;
+    /** Intent information */
+    intent: {
+        primary: string;
+        complexity: number;
+        all: Array<{
+            intent: string;
+            confidence: number;
+        }>;
+    };
+    /** Whether pattern was matched */
+    patternMatched: boolean;
+    /** Matched Pattern ID */
+    patternId?: string;
+    /** Final expression */
+    expression: string;
+    /** All possible expressions (from different strategies) */
+    alternatives: string[];
+}
+declare class NL2SpelEngine {
+    private readonly router;
+    private readonly providerRegistry;
+    private evaluatorInstance;
+    constructor(config?: StrategyRouterConfig);
+    /**
+     * Register an LLM Provider
+     */
+    registerProvider(provider: LLMProvider): void;
+    /**
+     * Unregister an LLM Provider
+     */
+    unregisterProvider(name: string): void;
+    /**
+     * Register a custom Pattern
+     */
+    registerPattern(pattern: PatternDefinition): void;
+    /**
+     * Set SpelEvaluator for validation pipeline.
+     * Must be called before generate() if parse-level validation is required.
+     */
+    setSpelEvaluator(evaluator: SpelEvaluator): void;
+    /**
+     * Extract ContextSchema from raw context object
+     */
+    extractContextSchema(context: NonNullable<GenerateOptions['context']>): ContextSchema;
+    /**
+     * Core generation API
+     */
+    generate(nl: string, options?: GenerateOptions): Promise<GenerateResult>;
+    /**
+     * Batch generation
+     */
+    generateBatch(nls: string[], options?: GenerateOptions): Promise<GenerateResult[]>;
+    /**
+     * Debug explanation
+     */
+    explain(nl: string, options?: GenerateOptions): Promise<ExplainResult>;
+}
+
+/**
+ * Chinese number parser — converts Chinese number strings to Arabic numerals.
+ *
+ * Supports:
+ * - Basic digits: 零一二三四五六七八九十百千万亿
+ * - Leading "十": "十五" → 15
+ * - Thousands/hundred-millions grouping: "一万二千三百四十五" → 12345
+ * - Zero padding: "一千零一" → 1001
+ */
+declare class ChineseNumberParser {
+    private static readonly DIGITS;
+    private static readonly UNITS;
+    private static readonly CHINESE_NUM_PATTERN;
+    /**
+     * Check if a string is pure Chinese numbers
+     */
+    static isChineseNumber(text: string): boolean;
+    /**
+     * Parse Chinese numbers → Arabic numerals
+     *
+     * @param text Chinese number string
+     * @returns Parsed number, returns NaN on failure
+     */
+    static parse(text: string): number;
+    /**
+     * Safe parse: returns null if parsing fails
+     */
+    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 };