NL2SpEL

Natural Language → Spring Expression Language (SpEL) Generation Engine

>

Four-layer hybrid architecture (Pattern Matching + Semantic Slots + LLM API + WebLLM Local), supporting Chinese & English

What is NL2SpEL?

When should I use it?

- You're building a no-code / low-code platform that needs expression generation from user text

- You want to bridge natural language and SpEL in a rules engine, workflow builder, or chatbot

- You need offline-first expression generation (Layers 0–1 require zero network calls)

- You want multi-LLM flexibility — swap between DeepSeek, OpenAI, GLM, Copilot, or run fully local in the browser

Architecture Overview

                    ┌─────────────────────────────────┐
                    │        NL2SpEL Engine            │
                    │  generate({ offlineOnly, ... }) │
                    │  generateBatch / explain        │
                    └───────────────┬─────────────────┘
                                    │
                    ┌───────────────▼─────────────────┐
                    │       StrategyRouter             │
                    │  Pattern → Template → LLM        │
                    └───────┬───────┬───────┬─────────┘
                            │       │       │
              ┌─────────────▼─┐  ┌──▼───┐  ┌▼──────────┐
              │  Layer 0      │  │Layer1│  │  Layer 2   │
              │  Pattern Match │  │ Templ│  │  LLM API   │
              │  (63 patterns) │  │ (15  │  │  (7 presets│
              │  < 1ms P99     │  │intents│  │  + custom) │
              └────────────────┘  └──────┘  └────────────┘
                                                    │
                                          ┌─────────▼─────────┐
                                          │  Layer 3 (optional)│
                                          │  WebLLM + GBNF     │
                                          │  Browser-only       │
                                          └────────────────────┘

Package Structure

Quick Start

Installation

# Core engine (offline-ready)
npm install @agentix-e/nl2spel
LLM API Provider (optional)
npm install @agentix-e/nl2spel-openai
WebLLM Provider (optional, browser-only)
npm install @agentix-e/nl2spel-webllm

Basic Usage

import { NL2SpelEngine } from '@agentix-e/nl2spel';
const engine = new NL2SpelEngine();
// Pattern matching (offline, < 1ms)
const r1 = await engine.generate('Order amount greater than 1000');
// { expression: "#order.amount > 1000", strategy: "pattern", confidence: 0.95 }
// Semantic slot filling
const r2 = await engine.generate('Age between 18 and 60');
// { expression: "#user.age between {18, 60}", strategy: "template", confidence: 0.9 }

LLM Provider

import { NL2SpelEngine } from '@agentix-e/nl2spel';
import { OpenAICompatibleProvider } from '@agentix-e/nl2spel-openai';
const engine = new NL2SpelEngine();
engine.registerProvider(
  new OpenAICompatibleProvider({
    provider: 'deepseek',
    apiKey: 'sk-...',
  })
);
const result = await engine.generate(
  'Filter orders with amount greater than 1000 and status is shipped'
);

Batch Generation

const results = await engine.generateBatch([
  'Amount greater than 100',
  'User is VIP',
  'Note is not empty and status is confirmed',
]);

Debug / Explain

const explanation = await engine.explain('Order amount greater than 1000 and user is VIP');
console.log(explanation.intent);     // { primary: "LOGICAL", complexity: 25, ... }
console.log(explanation.strategy);   // "pattern" | "template" | "llm-api"

Performance SLO

Strategy & Accuracy

FAQ

What SpEL features can NL2SpEL generate?

Do I need an API key?

Can I run it entirely offline in the browser?

How accurate is it?

Development

pnpm install
pnpm build
pnpm test
pnpm lint

License

Ecosystem