@agentix-e/nl2spel 1.2.2 → 1.3.0

package/README.md

@@ -4,7 +4,9 @@
 >
 > Zero external deps · Four-layer hybrid architecture · 532 tests · Chinese & English
 
-[![npm](https://img.shields.io/npm/v/@agentix-e/nl2spel)](https://www.npmjs.com/package/@agentix-e/nl2spel)
+[![npm](https://img.shields.io/npm/v/@agentix-e/nl2spel?color=blue)](https://www.npmjs.com/package/@agentix-e/nl2spel)
+[![API Docs](https://img.shields.io/badge/docs-TypeDoc-blue)](https://agentix-e.github.io/nl2spel/api/modules.html)
+[![Coverage](https://img.shields.io/badge/coverage-report-blue)](https://agentix-e.github.io/nl2spel/coverage/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
 
 ---

package/dist/index.cjs

@@ -41,47 +41,69 @@ module.exports = __toCommonJS(index_exports);
 // src/provider/provider-registry.ts
 var ProviderRegistry = class {
   _providers = [];
-  /** Register a Provider */
-  register(provider) {
-    if (this._providers.some((p) => p.name === provider.name)) {
+  _nextIndex = 0;
+  /**
+   * Register a Provider.
+   * @param provider LLMProvider instance
+   * @param options.priority User-assigned priority (lower = preferred). Defaults to registration order.
+   */
+  register(provider, options) {
+    if (this._providers.some((p) => p.provider.name === provider.name)) {
       throw new Error(`Provider '${provider.name}' already registered`);
     }
-    this._providers.push(provider);
+    this._providers.push({
+      provider,
+      priority: options?.priority ?? this._nextIndex,
+      index: this._nextIndex
+    });
+    this._nextIndex++;
   }
   /** Unregister a Provider */
   unregister(name) {
-    this._providers = this._providers.filter((p) => p.name !== name);
+    this._providers = this._providers.filter((p) => p.provider.name !== name);
   }
   /** Get a Provider by name */
   get(name) {
-    return this._providers.find((p) => p.name === name);
+    return this._providers.find((p) => p.provider.name === name)?.provider;
   }
   /**
    * 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)
    */
   async getPrioritized() {
     const available = [];
-    for (const p of this._providers) {
-      if (await p.isAvailable()) {
-        available.push(p);
+    for (const entry of this._providers) {
+      if (await entry.provider.isAvailable()) {
+        available.push(entry);
       }
     }
     return available.sort((a, b) => {
-      const aOffline = a.capabilities.offlineAvailable;
-      const bOffline = b.capabilities.offlineAvailable;
+      const aOffline = a.provider.capabilities.offlineAvailable;
+      const bOffline = b.provider.capabilities.offlineAvailable;
       if (aOffline && !bOffline) return -1;
       if (!aOffline && bOffline) return 1;
-      const costA = a.capabilities.estimatedCostPerRequest ?? Infinity;
-      const costB = b.capabilities.estimatedCostPerRequest ?? Infinity;
-      if (costA < costB) return -1;
-      if (costB < costA) return 1;
-      return a.capabilities.estimatedLatencyMs - b.capabilities.estimatedLatencyMs;
-    });
+      if (a.priority !== b.priority) return a.priority - b.priority;
+      return a.index - b.index;
+    }).map((entry) => entry.provider);
+  }
+  /**
+   * Explicitly reorder providers by name.
+   * Providers not listed retain their position after the reordered ones.
+   */
+  reorder(providerNames) {
+    const orderMap = new Map(providerNames.map((name, i) => [name, i]));
+    const maxExisting = this._providers.reduce(
+      (max, p) => Math.max(max, p.priority),
+      providerNames.length - 1
+    );
+    for (const entry of this._providers) {
+      const explicitIndex = orderMap.get(entry.provider.name);
+      entry.priority = explicitIndex ?? maxExisting + entry.index + 1;
+    }
   }
   /** List all registered Providers */
   list() {
-    return [...this._providers];
+    return this._providers.map((p) => p.provider);
   }
   /** Number of registered Providers */
   get count() {

package/dist/index.d.cts

@@ -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 */

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 */

package/dist/index.js

@@ -1,47 +1,69 @@
 // src/provider/provider-registry.ts
 var ProviderRegistry = class {
   _providers = [];
-  /** Register a Provider */
-  register(provider) {
-    if (this._providers.some((p) => p.name === provider.name)) {
+  _nextIndex = 0;
+  /**
+   * Register a Provider.
+   * @param provider LLMProvider instance
+   * @param options.priority User-assigned priority (lower = preferred). Defaults to registration order.
+   */
+  register(provider, options) {
+    if (this._providers.some((p) => p.provider.name === provider.name)) {
       throw new Error(`Provider '${provider.name}' already registered`);
     }
-    this._providers.push(provider);
+    this._providers.push({
+      provider,
+      priority: options?.priority ?? this._nextIndex,
+      index: this._nextIndex
+    });
+    this._nextIndex++;
   }
   /** Unregister a Provider */
   unregister(name) {
-    this._providers = this._providers.filter((p) => p.name !== name);
+    this._providers = this._providers.filter((p) => p.provider.name !== name);
   }
   /** Get a Provider by name */
   get(name) {
-    return this._providers.find((p) => p.name === name);
+    return this._providers.find((p) => p.provider.name === name)?.provider;
   }
   /**
    * 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)
    */
   async getPrioritized() {
     const available = [];
-    for (const p of this._providers) {
-      if (await p.isAvailable()) {
-        available.push(p);
+    for (const entry of this._providers) {
+      if (await entry.provider.isAvailable()) {
+        available.push(entry);
       }
     }
     return available.sort((a, b) => {
-      const aOffline = a.capabilities.offlineAvailable;
-      const bOffline = b.capabilities.offlineAvailable;
+      const aOffline = a.provider.capabilities.offlineAvailable;
+      const bOffline = b.provider.capabilities.offlineAvailable;
       if (aOffline && !bOffline) return -1;
       if (!aOffline && bOffline) return 1;
-      const costA = a.capabilities.estimatedCostPerRequest ?? Infinity;
-      const costB = b.capabilities.estimatedCostPerRequest ?? Infinity;
-      if (costA < costB) return -1;
-      if (costB < costA) return 1;
-      return a.capabilities.estimatedLatencyMs - b.capabilities.estimatedLatencyMs;
-    });
+      if (a.priority !== b.priority) return a.priority - b.priority;
+      return a.index - b.index;
+    }).map((entry) => entry.provider);
+  }
+  /**
+   * Explicitly reorder providers by name.
+   * Providers not listed retain their position after the reordered ones.
+   */
+  reorder(providerNames) {
+    const orderMap = new Map(providerNames.map((name, i) => [name, i]));
+    const maxExisting = this._providers.reduce(
+      (max, p) => Math.max(max, p.priority),
+      providerNames.length - 1
+    );
+    for (const entry of this._providers) {
+      const explicitIndex = orderMap.get(entry.provider.name);
+      entry.priority = explicitIndex ?? maxExisting + entry.index + 1;
+    }
   }
   /** List all registered Providers */
   list() {
-    return [...this._providers];
+    return this._providers.map((p) => p.provider);
   }
   /** Number of registered Providers */
   get count() {

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@agentix-e/nl2spel",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Natural Language → SpEL Expression Generation Engine — Core",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.cjs",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.cjs"
     }
   },
   "files": [
@@ -33,7 +33,7 @@
     }
   },
   "devDependencies": {
-    "@agentix-e/spel-ts": "^1.1.0",
+    "@agentix-e/spel-ts": "^1.2.2",
     "tsup": "^8.5.1",
     "typescript": "^5.7.3",
     "vitest": "^3.0.0"