n2-qln 3.1.1 → 3.3.0

package/README.ko.md

@@ -349,6 +349,39 @@ module.exports = {
 | **기본** (Ollama 없음) | Stage 1 + 2 | ⭐⭐⭐⭐ 훌륭 | 없음 |
 | **Ollama 포함** | Stage 1 + 2 + 3 | ⭐⭐⭐⭐⭐ 완벽 | Ollama 실행 필요 |
 
+### 다국어 사용자
+
+`nomic-embed-text`는 영어에 최적화되어 있습니다. **한국어, 일본어, 중국어** 등 다른 언어를 사용한다면 다국어 모델로 교체하세요:
+
+```bash
+ollama pull bge-m3
+```
+
+```javascript
+// config.local.js
+module.exports = {
+  embedding: {
+    enabled: true,
+    model: 'bge-m3',  // 다국어 지원 (100개 이상 언어)
+  },
+};
+```
+
+코드 수정 없이 config의 모델명만 바꾸면 됩니다.
+
+### 클라우드 동기화
+
+도구 인덱스를 여러 기기에서 동기화하고 싶다면 `dataDir`을 클라우드 폴더로 지정하세요:
+
+```javascript
+// config.local.js
+module.exports = {
+  dataDir: 'G:/My Drive/n2-qln',  // Google Drive, OneDrive, Dropbox, NAS...
+};
+```
+
+[n2-soul 클라우드 스토리지](https://github.com/choihyunsus/n2-soul#%EF%B8%8F-cloud-storage--store-your-ai-memory-anywhere)와 동일한 방식입니다. SQLite 파일이 해당 폴더에 저장되고, 동기화 서비스가 나머지를 처리합니다.
+
 ---
 
 ## 프로젝트 구조

package/README.md

@@ -369,6 +369,39 @@ module.exports = {
 | **Default** (no Ollama) | Stage 1 + 2 | ⭐⭐⭐⭐ Great | None |
 | **With Ollama** | Stage 1 + 2 + 3 | ⭐⭐⭐⭐⭐ Perfect | Ollama running |
 
+### Multilingual Users
+
+`nomic-embed-text` is optimized for English. For **Korean, Japanese, Chinese**, or other languages, swap to a multilingual model:
+
+```bash
+ollama pull bge-m3
+```
+
+```javascript
+// config.local.js
+module.exports = {
+  embedding: {
+    enabled: true,
+    model: 'bge-m3',  // multilingual (100+ languages)
+  },
+};
+```
+
+No code changes needed — just swap the model name in config.
+
+### Cloud Sync
+
+Want your tool index synced across machines? Point `dataDir` to a cloud folder:
+
+```javascript
+// config.local.js
+module.exports = {
+  dataDir: 'G:/My Drive/n2-qln',  // Google Drive, OneDrive, Dropbox, NAS...
+};
+```
+
+Same approach as [n2-soul Cloud Storage](https://github.com/choihyunsus/n2-soul#%EF%B8%8F-cloud-storage--store-your-ai-memory-anywhere). SQLite file lives in that folder — your sync service handles the rest.
+
 ---
 
 ## Project Structure

package/index.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
-// QLN — Quantum Layer Network MCP server entry point
+// QLN — Query Layer Network MCP server entry point
 // Semantic tool dispatcher: route 1000 tools through 1 router
 const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
 const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
 const { z } = require('zod');
 
 // Core
+const path = require('path');
 const { loadConfig } = require('./lib/config');
 const { Store } = require('./lib/store');
 const { Embedding } = require('./lib/embedding');
@@ -13,6 +14,7 @@ const { Registry } = require('./lib/registry');
 const { VectorIndex } = require('./lib/vector-index');
 const { Router } = require('./lib/router');
 const { Executor } = require('./lib/executor');
+const { loadProviders } = require('./lib/provider-loader');
 
 // MCP Tool (unified)
 const { registerQlnCall } = require('./tools/qln-call');
@@ -31,6 +33,18 @@ async function main() {
     const registry = new Registry(store, embedding);
     registry.load();
 
+    // 1.5. Provider auto-indexing (providers/*.json → registry)
+    if (config.providers?.enabled !== false) {
+        const provDir = config.providers?.dir || path.join(__dirname, 'providers');
+        const provResult = loadProviders(provDir, registry);
+        if (provResult.loaded > 0) {
+            console.error(`[QLN] Providers: ${provResult.loaded} tools from ${provResult.details.filter(d => d.status === 'loaded').length} files`);
+        }
+        if (provResult.failed > 0) {
+            console.error(`[QLN] Provider warnings: ${provResult.failed} files failed to load`);
+        }
+    }
+
     const vectorIndex = new VectorIndex();
     const router = new Router(registry, vectorIndex, embedding);
     const executor = new Executor(config.executor || {});
@@ -46,9 +60,10 @@ async function main() {
     }
 
     // 3. Create MCP server
+    const pkg = require('./package.json');
     const server = new McpServer({
         name: 'n2-qln',
-        version: '3.1.0',
+        version: pkg.version,
     });
 
     // 4. Register unified MCP tool (1 tool, 5 actions)

package/lib/config.js

@@ -20,6 +20,12 @@ const defaults = {
         timeout: 20000,
     },
 
+    /** Provider manifest auto-indexing */
+    providers: {
+        enabled: true,
+        dir: path.join(__dirname, '..', 'providers'),
+    },
+
     /** Search configuration */
     search: {
         defaultTopK: 5,

package/lib/provider-loader.js

@@ -0,0 +1,126 @@
+// QLN — Provider manifest loader (providers/*.json → registry auto-registration)
+const fs = require('fs');
+const path = require('path');
+const { inferCategory } = require('./schema');
+
+/**
+ * Required fields for a valid provider manifest.
+ * @type {string[]}
+ */
+const REQUIRED_MANIFEST_FIELDS = ['provider', 'tools'];
+
+/**
+ * Required fields for each tool entry within a manifest.
+ * @type {string[]}
+ */
+const REQUIRED_TOOL_FIELDS = ['name', 'description'];
+
+/**
+ * Load all provider manifests from a directory and register their tools.
+ *
+ * @param {string} providersDir - Absolute path to providers/ directory
+ * @param {import('./registry').Registry} registry - QLN registry instance
+ * @returns {{ loaded: number, skipped: number, failed: number, details: object[] }}
+ */
+function loadProviders(providersDir, registry) {
+    const result = { loaded: 0, skipped: 0, failed: 0, details: [] };
+
+    if (!fs.existsSync(providersDir)) return result;
+
+    /** @type {string[]} */
+    const files = fs.readdirSync(providersDir)
+        .filter(f => f.endsWith('.json'));
+
+    if (files.length === 0) return result;
+
+    for (const file of files) {
+        const filePath = path.join(providersDir, file);
+        try {
+            const manifest = _parseManifest(filePath);
+            if (!manifest) {
+                result.skipped++;
+                result.details.push({ file, status: 'skipped', reason: 'invalid manifest' });
+                continue;
+            }
+
+            const tools = _normalizeTools(manifest);
+            if (tools.length === 0) {
+                result.skipped++;
+                result.details.push({ file, status: 'skipped', reason: 'no valid tools' });
+                continue;
+            }
+
+            // Idempotent: purge old entries from this provider before re-registering
+            registry.purgeBySource(`provider:${manifest.provider}`);
+
+            const count = registry.registerBatch(tools);
+            result.loaded += count;
+            result.details.push({
+                file,
+                status: 'loaded',
+                provider: manifest.provider,
+                toolCount: count,
+            });
+        } catch (err) {
+            result.failed++;
+            result.details.push({ file, status: 'failed', reason: err.message });
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Parse and validate a manifest JSON file.
+ *
+ * @param {string} filePath - Absolute path to JSON file
+ * @returns {object|null} Parsed manifest or null if invalid
+ */
+function _parseManifest(filePath) {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const manifest = JSON.parse(raw);
+
+    // Validate required fields
+    for (const field of REQUIRED_MANIFEST_FIELDS) {
+        if (!manifest[field]) return null;
+    }
+
+    // tools must be a non-empty array
+    if (!Array.isArray(manifest.tools)) return null;
+
+    return manifest;
+}
+
+/**
+ * Normalize tool entries from a manifest for registry registration.
+ * Injects provider metadata and assigns source = "provider:{name}".
+ *
+ * @param {object} manifest - Validated manifest object
+ * @returns {object[]} Array of normalized tool entries ready for registerBatch()
+ */
+function _normalizeTools(manifest) {
+    const providerName = manifest.provider;
+    const tools = [];
+
+    for (const raw of manifest.tools) {
+        // Skip tools missing required fields
+        if (!raw.name || !raw.description) continue;
+
+        tools.push({
+            name: raw.name,
+            description: raw.description,
+            source: `provider:${providerName}`,
+            category: raw.category || inferCategory(raw.name, 'provider'),
+            provider: providerName,
+            inputSchema: raw.inputSchema || null,
+            triggers: raw.triggers || undefined, // let schema.js extract
+            tags: raw.tags || [],
+            examples: raw.examples || [],
+            endpoint: raw.endpoint || '',
+        });
+    }
+
+    return tools;
+}
+
+module.exports = { loadProviders };

package/lib/registry.js

@@ -156,6 +156,7 @@ class Registry {
         const entry = this._cache.get(name);
         if (!entry) return;
         entry.usageCount++;
+        entry.lastUsedAt = new Date().toISOString();
         const alpha = 0.1;
         entry.successRate = entry.successRate * (1 - alpha) + (success ? 1 : 0) * alpha;
         entry.updatedAt = new Date().toISOString();
@@ -203,6 +204,7 @@ class Registry {
             embedding: _parseJson(row.embedding, null),
             usageCount: row.usage_count || 0,
             successRate: row.success_rate ?? 1.0,
+            lastUsedAt: row.last_used_at || null,
             registeredAt: row.registered_at,
             updatedAt: row.updated_at,
         };

package/lib/router.js

@@ -104,13 +104,20 @@ class Router {
         } catch { /* graceful degradation */ }
     }
 
-    /** Merge all stage results + usage/success bonus → ranking */
+    /** Merge all stage results + usage/success bonus + recency decay → ranking */
     _mergeAndRank(scores, topK, threshold) {
         const results = [];
         for (const [name, s] of scores) {
             const tool = this._registry.get(name);
             if (!tool) continue;
-            const usageBonus = Math.log2((tool.usageCount || 0) + 1) * 0.5;
+
+            // Recency Decay: usage bonus fades over 30-day half-life
+            const daysSinceUse = tool.lastUsedAt
+                ? (Date.now() - new Date(tool.lastUsedAt).getTime()) / 86400000
+                : 0;
+            const recencyFactor = tool.lastUsedAt ? Math.exp(-daysSinceUse / 30) : 1.0;
+            const usageBonus = Math.log2((tool.usageCount || 0) + 1) * 0.5 * recencyFactor;
+
             const successBonus = (tool.successRate ?? 1.0) * 1.0;
             const finalScore = (s.stage1 || 0) + (s.stage2 || 0) + (s.stage3 || 0)
                 + usageBonus + successBonus;
@@ -124,6 +131,7 @@ class Router {
                         semantic: s.stage3 || 0,
                         usage: Math.round(usageBonus * 100) / 100,
                         success: Math.round(successBonus * 100) / 100,
+                        recencyFactor: Math.round(recencyFactor * 1000) / 1000,
                     },
                     description: tool.description,
                     source: tool.source,
@@ -133,7 +141,30 @@ class Router {
             }
         }
         results.sort((a, b) => b.score - a.score);
-        return results.slice(0, topK);
+        const ranked = results.slice(0, topK);
+
+        // 5% Explorer: inject least-used tool into last slot
+        if (ranked.length >= topK && topK >= 2) {
+            const resultNames = new Set(ranked.map(r => r.name));
+            const allTools = this._registry.getAll()
+                .filter(t => !resultNames.has(t.name))
+                .sort((a, b) => (a.usageCount || 0) - (b.usageCount || 0));
+            if (allTools.length > 0) {
+                const explorer = allTools[0];
+                ranked[ranked.length - 1] = {
+                    name: explorer.name,
+                    score: 0,
+                    stages: { trigger: 0, keyword: 0, semantic: 0, usage: 0, success: 0, recencyFactor: 0 },
+                    description: explorer.description,
+                    source: explorer.source,
+                    category: explorer.category,
+                    inputSchema: explorer.inputSchema,
+                    explorer: true,
+                };
+            }
+        }
+
+        return ranked;
     }
 
     /** Build vector index */

package/lib/schema.js

@@ -21,6 +21,7 @@ function createToolEntry(raw) {
         searchText: '',
         usageCount: raw.usageCount || 0,
         successRate: typeof raw.successRate === 'number' ? raw.successRate : 1.0,
+        lastUsedAt: raw.lastUsedAt || null,
         embedding: raw.embedding || null,
         registeredAt: raw.registeredAt || new Date().toISOString(),
         updatedAt: new Date().toISOString(),

package/lib/store.js

@@ -104,6 +104,7 @@ class Store {
         addCol('tools', 'provider', 'TEXT', "''");
         addCol('tools', 'examples', 'TEXT', "'[]'");
         addCol('tools', 'endpoint', 'TEXT', "''");
+        addCol('tools', 'last_used_at', 'TEXT', 'NULL');
 
         // Copy plugin_name → provider (if old schema has plugin_name)
         try {
@@ -130,10 +131,10 @@ class Store {
         this._db.run(`
             INSERT INTO tools (name, description, source, category, provider,
                 input_schema, triggers, tags, examples, endpoint, search_text, embedding,
-                usage_count, success_rate, updated_at)
+                usage_count, success_rate, last_used_at, updated_at)
             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?,
                 ?, COALESCE(?, (SELECT embedding FROM tools WHERE name = ?)),
-                ?, ?, datetime('now'))
+                ?, ?, ?, datetime('now'))
             ON CONFLICT(name) DO UPDATE SET
                 description = excluded.description,
                 source = excluded.source,
@@ -148,6 +149,7 @@ class Store {
                 embedding = COALESCE(excluded.embedding, tools.embedding),
                 usage_count = excluded.usage_count,
                 success_rate = excluded.success_rate,
+                last_used_at = excluded.last_used_at,
                 updated_at = excluded.updated_at
         `, [
             entry.name, entry.description, entry.source, entry.category, entry.provider,
@@ -155,7 +157,7 @@ class Store {
             JSON.stringify(entry.tags), JSON.stringify(entry.examples), entry.endpoint || '',
             entry.searchText,
             entry.embedding ? JSON.stringify(entry.embedding) : null, entry.name,
-            entry.usageCount, entry.successRate,
+            entry.usageCount, entry.successRate, entry.lastUsedAt || null,
         ]);
         this._persist();
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "n2-qln",
-    "version": "3.1.1",
+    "version": "3.3.0",
     "description": "Query Layer Network — Semantic tool dispatcher for MCP. Route 1000 tools through 1 router.",
     "main": "index.js",
     "bin": {
@@ -15,7 +15,13 @@
         "sql.js": "^1.12.0",
         "zod": "~3.24.1"
     },
-    "keywords": ["mcp", "ai", "tool-routing", "semantic-search", "llm"],
+    "keywords": [
+        "mcp",
+        "ai",
+        "tool-routing",
+        "semantic-search",
+        "llm"
+    ],
     "author": "N2",
     "license": "Apache-2.0",
     "repository": {