Neuroverse

🧠 NeuroVerse

📦 從 npm 安裝 | 🐙 GitHub 倉庫

你的 AI 智能體只會說英語。NeuroVerse 解決了這個問題。
你的 AI 智能體什麼都記不住。NeuroVerse 記得。
你的 AI 智能體可能會做出危險操作。NeuroVerse 阻止它。
你的 AI 智能體被鎖定在單一模型上。NeuroVerse 會路由到最優模型。

面向自主 AI 智能體的多語言智能 + 記憶 + 安全 + 語音層。

---

🚀 v4.1 新特性

• OpenRouter 推理：集成 stepfun/step-3.5-flash:free 模型，用於高性能分析任務。使用新的 neuroverse_reason 工具進行深度思考。
• 推理 Token：即時追蹤每個請求的推理 token。
• 語音層（v2.0）：內置對 Whisper STT 和 Coqui TTS 的支持。

---

🚀 NeuroVerse 是什麼？

每次你用 Cursor、VS Code Copilot 或任何兼容 MCP 的 AI 智能體開啟一段新對話時，它都從零開始——沒有記憶、沒有安全保障，也聽不懂你的語言。NeuroVerse 是一個 MCP 服務器，為你的智能體提供：

	特性	描述
🌐	多語言智能	理解混合的印度語言——泰米爾語、印地語、泰盧固語、卡納達語、馬拉雅拉姆語、孟加拉語 + 英語。語碼切換？沒問題。
🎙️	語音層	通過 Whisper 進行 STT，通過 Coqui 進行 TTS。轉寫用戶音頻併合成智能體回覆。
🧠	意圖提取	以 LLM 為主的結構化意圖提取，並帶有確定性的基於規則的兜底。絕不遺漏任何命令。
💾	分層記憶	短期（會話）、情景（近期）、語義（長期事實）——全部帶有重要性評分。
🛡️	三層安全（Kavach）	關鍵詞黑名單 → 意圖風險分類器 → LLM 裁判。在 DROP DATABASE 釀成大禍之前將其攔截。
🤖	多模型路由器（Marga）	OpenAI · Anthropic · Sarvam AI · Ollama · OpenRouter——自動將每項任務路由到最合適的模型。
🔗	智能體到智能體（Setu）	REST+JSON 智能體註冊表，帶自動兜底。智能體調用智能體再調用智能體。
⚡	全部異步	FastAPI + asyncpg + httpx。亞毫秒級安全檢查。零阻塞。

⚡ NeuroVerse 是一個模塊化智能層——而非單體應用。按需插拔。不需要的部分直接忽略。

---

目錄

• 快速開始
• 為什麼選擇 NeuroVerse？
• 工作原理
• 多語言智能（Vani）
• 意圖提取（Bodhi）
• 分層記憶（Smriti）
• 安全層（Kavach）
• 多模型路由器（Marga）
• 智能體到智能體（Setu）
• MCP 工具
• REST API
• 配置
• 測試
• 架構
• 路線圖
• 貢獻指南

---

🚀 快速開始

1. 安裝

方式 A：npm（推薦）——隨處可用

npm install neuroverse

方式 B：從源碼安裝（Python）

git clone https://github.com/joshua400/neuroverse.git
cd neuroverse
python -m pip install -e ".[dev]"

💡 提示： 如果你通過 npm 安裝，路徑是 node_modules/neuroverse/dist/index.js。如果從源碼安裝，請使用你克隆目錄的絕對路徑。

2. 將 NeuroVerse 添加到你的 MCP 配置

NeuroVerse 是一個標準的 MCP 服務器（stdio）。將它添加到你的宿主配置中：

Cursor / VS Code Copilot / Claude Desktop（npm）

{
  "mcpServers": {
    "neuroverse": {
      "command": "npx",
      "args": ["neuroverse"]
    }
  }
}

從源碼（Python）

{
  "mcpServers": {
    "neuroverse": {
      "command": "python",
      "args": ["mcp/server.py"],
      "cwd": "/path/to/neuroverse"
    }
  }
}

3. 讓你的智能體使用 NeuroVerse

將此加入你的智能體規則文件（.md、.cursorrules、系統提示詞等）：

## NeuroVerse 集成
- 使用 `neuroverse_process` 處理任何用戶請求——它會自動檢測語言、提取意圖、檢查安全性並執行。
- 使用 `neuroverse_reason` 處理需要分析推理的複雜任務（由 OpenRouter 驅動）。
- 使用 `neuroverse_store` / `neuroverse_recall` 實現跨會話的持久上下文。
- 使用 `neuroverse_execute` 處理任何有潛在危險的操作——它會攔截破壞性操作。

就這樣。你的智能體只需要知道兩個命令：

命令	何時使用	會發生什麼
neuroverse_process(text, user_id)	任何用戶請求	檢測語言、提取意圖、安全檢查、執行
neuroverse_store(user_id, intent, ...)	工作結束時	保存上下文供下次會話使用

下次會話時，你的智能體會從上次中斷的地方精準繼續——就像從未遺忘一樣。

環境要求

• npm 版： Node.js 18+（零數據庫依賴——使用 JSON 文件）
• Python 版： Python 3.10+ + PostgreSQL（用於持久化記憶）

---

🤔 為什麼選擇 NeuroVerse？

沒有 NeuroVerse	有了 NeuroVerse
智能體只懂英語	智能體理解泰米爾語、印地語、泰盧固語、卡納達語 + 英語語碼切換
"anna file ah csv convert pannu" → ❌ 報錯	"anna file ah csv convert pannu" → ✅ 將文件轉換為 CSV
每次會話從零開始	智能體記住它做過什麼——跨會話、跨智能體
DROP DATABASE → 💀 你的數據沒了	DROP DATABASE → 🛡️ 在 < 1ms 內攔截，零 token
被鎖定在單一 LLM 供應商	自動為每項任務路由到最優模型
兩個智能體 = 混亂	智能體 A 無縫交接給智能體 B

Token 效率

NeuroVerse 的安全層以零 token 成本運行——純正則表達式和規則匹配，不浪費任何 LLM 調用：

安全方案	每次檢查成本	延遲
基於 LLM 的安全	500–2,000 tokens	1–5 秒
基於嵌入	100–500 tokens	200–500ms
NeuroVerse Kavach	0 tokens	< 1ms

在每個會話 100 次工具調用的情況下，相比基於 LLM 的安全方案，可節省 50,000–200,000 tokens。

---

⚙️ 工作原理

用戶輸入（任意語言）
        │
   ┌────┴────┐
   │  Vani   │ ← 語言檢測 + 關鍵詞歸一化
   │ (भाषा)  │   泰米爾語/印地語/泰盧固語 → 歸一化的內部格式
   └────┬────┘
        │
   ┌────┴────┐
   │  Bodhi  │ ← LLM 意圖提取 + 基於規則的兜底
   │ (बोधि)  │   返回帶置信度的結構化 JSON
   └────┬────┘
        │
   ┌────┴────┐
   │ Kavach  │ ← 三層安全：黑名單 → 風險 → LLM 裁判
   │ (कवच)   │   以零 token 成本攔截危險操作
   └────┬────┘
        │
   ┌────┴────┐
   │  Marga  │ ← 路由到最優模型（OpenAI/Anthropic/Sarvam/Ollama）
   │ (मार्ग)  │   基於任務類型：多語言/推理/本地
   └────┬────┘
        │
   ┌────┴────┐
   │ Smriti  │ ← 從分層記憶中存儲/召回
   │ (स्मृति) │   短期 + 情景 + 語義（PostgreSQL）
   └────┬────┘
        │
   工具執行 + 響應

---

🌐 多語言智能 — Vani

問題： 每個 MCP 服務器都只會說英語。而印度有 70% 的人每天都在使用語碼切換。

"anna indha file ah csv convert pannu"
         ↓
"anna this file ah csv convert do"     ← 關鍵詞歸一化（非完整翻譯）
         ↓
Intent: convert_format { output_format: "csv" }

混合流水線（規則 + LLM）

輸入 → 語言檢測（langdetect）→ 語碼切換拆分 → 關鍵詞歸一化 → 輸出

關鍵洞見： 不要做完整翻譯。只歸一化領域關鍵的關鍵詞。其餘內容保持原樣——從而保留上下文、語氣和細微含義。

支持的語言

語言	映射的關鍵詞	示例
🇮🇳 泰米爾語	pannu → do, maathru → change, anuppu → send	"file ah csv convert pannu"
🇮🇳 印地語	karo → do, banao → create, bhejo → send	"report banao sales ka"
🇮🇳 泰盧固語	cheyyi → do, pampu → send, chupinchu → show	"data chupinchu"
🇮🇳 卡納達語	v2 版本將支持	—
🇬🇧 英語	直接通過	"convert json to csv"

語碼切換檢測

{
  "languages": ["ta", "en"],
  "confidence": 0.92,
  "is_code_switched": true,
  "original_text": "anna indha file ah csv convert pannu",
  "normalized_text": "anna this file ah csv convert do"
}

---

🧠 意圖提取 — Bodhi

LLM 優先。基於規則兜底。絕不失敗。

LLM 成功（置信度 ≥ 0.5）？
   ├─ 是 → 使用 LLM 結果
   └─ 否 → 基於規則的解析器（確定性）

LLM 策略

# Prompt to LLM:
"Extract structured intent from the following input.
 Return ONLY valid JSON: {intent, parameters, confidence}"

基於規則的兜底（7 種模式）

模式	意圖	觸發關鍵詞
格式轉換	convert_format	convert, csv, json, excel, pdf
摘要	summarize	summarise, summary, brief, tldr
報告生成	generate_report	report, generate report
刪除	delete_data	delete, remove, drop, clean
數據查詢	query_data	query, search, find, fetch, get
通信	send_message	send, share, email, notify
解釋	explain	explain, describe, what is, how to

輸出

{
  "intent": "convert_format",
  "parameters": { "input_format": "json", "output_format": "csv" },
  "confidence": 0.87,
  "source": "rule"
}

關鍵區別：由代碼決定——而非 LLM。如果 LLM 失敗、產生幻覺或返回垃圾內容，規則引擎會接管。確定性。可靠。

---

💾 分層記憶 — Smriti

問題： 原始日誌毫無用處。存儲一切浪費資源。沒有相關性評分。

NeuroVerse 的方案： 評分 → 過濾 → 壓縮 → 存儲。

三個層級

層級	存儲	生命週期	用途
短期	進程內字典	當前會話	活躍上下文，每用戶上限 50 條
情景	PostgreSQL	近期操作	智能體最近做了什麼
語義	PostgreSQL	長期事實	關於用戶、項目、實體的持久知識

重要性評分

if importance_score >= 0.4:
    persist_to_database()   # worth remembering
else:
    skip()                  # noise

只有重要的記憶才會保留。沒有冗餘。沒有不相關的召回。

上下文壓縮

❌ Bad:  "The user asked about sales data three times in the last hour and seemed frustrated..."
✅ Good: { "intent": "sales_query", "frequency": 3, "sentiment": "frustrated" }

結構化 JSON 負載，而非原始文本堆砌。已壓縮。可索引。可查詢。

記憶結構（PostgreSQL）

CREATE TABLE memory_records (
    id          TEXT PRIMARY KEY,
    user_id     TEXT NOT NULL,
    tier        TEXT NOT NULL,          -- short_term | episodic | semantic
    intent      TEXT NOT NULL,
    language    TEXT DEFAULT 'en',
    data        JSONB DEFAULT '{}',     -- compressed structured payload
    importance  REAL DEFAULT 0.5,
    created_at  TIMESTAMPTZ DEFAULT NOW(),
    updated_at  TIMESTAMPTZ DEFAULT NOW()
);
-- Indexed: user_id, intent, tier

---

🛡️ 安全層 — Kavach

"永不入睡的盾牌。"

三層——縱深防禦

智能體調用工具  →  MCP 服務器接收請求
                            │
                ┌───────────┴───────────┐
                │  第 1 層：黑名單        │  ← 正則 + 關鍵詞，< 0.1ms
                └───────────┬───────────┘
                            │ 通過
                ┌───────────┴───────────┐
                │  第 2 層：風險評分      │  ← 意圖 → 風險分類
                └───────────┬───────────┘
                            │ 通過
                ┌───────────┴───────────┐
                │  第 3 層：LLM 裁判      │  ← 可選的基於模型的檢查
                └───────────┬───────────┘
                            │ 通過
                     執行處理器

第 1 層 — 基於規則的黑名單（零成本）

在 MCP 服務器內部運行。純正則。無網絡。無 token。

攔截的關鍵詞：

delete_all_data, drop_database, drop_table, system_shutdown,
format_disk, rm -rf, truncate, shutdown, reboot, erase_all, destroy

攔截的模式（正則）：

DROP (DATABASE|TABLE|SCHEMA)
DELETE FROM *
TRUNCATE TABLE
FORMAT [drive]:
rm (-rf|--force)

第 2 層 — 意圖風險分類

風險等級	意圖	操作
🟢 低	convert_format, summarize, generate_report, query_data, explain	✅ 允許
🟡 中	send_message, unknown	⚠️ 嚴格模式下攔截
🔴 高	delete_data	❌ 始終攔截
⛔ 嚴重	drop_database, system_shutdown	❌ 始終攔截

第 3 層 — LLM 安全裁判（可選）

如果第 1–2 層通過，可選地詢問 LLM："這個操作安全嗎？"

// LLM returns:
{ "safe": false, "reason": "This action would delete all user data." }

安全判定

{
  "allowed": false,
  "risk_level": "critical",
  "reason": "Blocked keyword detected: 'drop_database'",
  "blocked_by": "rule"
}

Token 成本：零

大多數 AI 安全：  智能體 → "rm -rf /" → 安全 LLM → 消耗 2,000 tokens
NeuroVerse：     智能體 → "rm -rf /" → 正則匹配 → 攔截（0 tokens，< 1ms）

嚴格模式

# .env
SAFETY_STRICT_MODE=true    # 同時攔截中風險（unknown/send）
SAFETY_STRICT_MODE=false   # 僅攔截高風險和嚴重

---

🤖 多模型路由器 — Marga

問題： 供應商鎖定。一個模型包打天下。過度付費。

NeuroVerse 的方案： 將每項任務路由到最優模型。自動完成。

路由邏輯

def route_task(task):
    if task.type == "multilingual":
        return sarvam_model        # Best for Indian languages
    elif task.type == "reasoning":
        return claude_or_openai    # Best for complex analysis
    elif task.type == "local":
        return ollama              # Free, on-device, private
    else:
        return best_available      # Fallback chain

支持的供應商

供應商	默認模型	最適合	成本
🇮🇳 Sarvam AI	sarvam-2b-v0.5	印度語言、多語言	低
🧩 OpenRouter	stepfun/step-3.5-flash:free	高性能推理	免費
🧠 Anthropic	claude-sonnet-4-20250514	推理、分析	中
🤖 OpenAI	gpt-4o	通用任務、代碼	中
🦙 Ollama	llama3	本地、私密、離線	免費

優勢

	沒有 Marga	有了 Marga
成本	一切任務都付 GPT-4 的錢	簡單任務用 Ollama
速度	所有任務延遲相同	快速任務用本地模型
隱私	一切都發往雲端	敏感數據留在本地
供應商鎖定	被單一供應商綁定	隨時切換

兜底鏈

如果你首選的供應商宕機或未配置：

OpenRouter → Anthropic → OpenAI → Sarvam → Ollama（本地，始終可用）

---

🔗 智能體到智能體 — Setu

智能體調用智能體再調用智能體。

智能體註冊表

register_agent({
    "agent_name": "report_agent",
    "endpoint": "http://localhost:8001/generate",
    "capabilities": ["generate_report", "sales_analysis"]
})

路由

{
  "target_agent": "report_agent",
  "task": "generate_sales_report",
  "payload": { "quarter": "Q1", "year": 2026 }
}

兜底

如果目標智能體不可達：

{
  "success": false,
  "error": "Agent unreachable: ConnectError",
  "fallback": true
}

調用方可以回退到本地執行。沒有硬性失敗。

---

🧩 MCP 工具

NeuroVerse 通過 Model Context Protocol 暴露 6 個工具：

#	工具（npm）	工具（Python）	描述
1	neuroverse_process	india_mcp_process_multilingual_input	完整流水線：檢測 → 歸一化 → 意圖 → 安全 → 執行
2	neuroverse_store	india_mcp_store_memory	在分層系統中存儲一條記憶記錄
3	neuroverse_recall	india_mcp_recall_memory	按用戶、意圖或層級檢索記憶
4	neuroverse_execute	india_mcp_safe_execute	端到端安全執行（便捷方法）
5	neuroverse_route	india_mcp_route_agent	將任務路由到已註冊的下游智能體
6	neuroverse_model	india_mcp_model_route	查詢多模型路由器（可選調用）
7	neuroverse_transcribe	india_mcp_transcribe_audio	通過 Whisper STT 將音頻轉寫為文本
8	neuroverse_synthesize	india_mcp_synthesize_speech	通過 Coqui TTS 從文本合成語音
9	neuroverse_reason	N/A	通過 OpenRouter 進行高性能推理

真實示例

── 會話 1（智能體 Alpha，下午 2 點）───────────────────────
india_mcp_process_multilingual_input({
    text: "anna indha sales data ah csv convert pannu",
    user_id: "alpha",
    execute: true
})
→ 語言：泰米爾語 + 英語（語碼切換）
→ 意圖：convert_format { output_format: "csv" }
→ 安全：✅ 允許（低風險）
→ 執行：✅ 成功

india_mcp_store_memory({
    user_id: "alpha",
    intent: "convert_format",
    tier: "episodic",
    data: { "file": "sales_q1.json", "output": "csv" },
    importance_score: 0.8
})

── 會話 2（智能體 Beta，第二天）─────────────────────────
india_mcp_recall_memory({
    user_id: "alpha",
    intent: "convert_format",
    limit: 5
})
→ "智能體 Alpha 昨天把 sales_q1.json 轉換成了 CSV"
→ Beta 從 Alpha 中斷的地方精準繼續

---

🌐 REST API

NeuroVerse 還附帶一個 FastAPI REST 層——用於非 MCP 客戶端：

python app/main.py
# → http://localhost:8000/docs (Swagger UI)

端點	方法	描述
/health	GET	健康檢查
/api/process	POST	完整多語言流水線
/api/memory/store	POST	存儲記憶
/api/memory/recall	POST	檢索記憶

---

⚙️ 配置

所有設置通過環境變量（.env）配置：

# Database (PostgreSQL required for persistent memory)
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/neuroverse

# AI Model API Keys (configure the ones you have)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
SARVAM_API_KEY=...

# Ollama (local, free)
OLLAMA_BASE_URL=http://localhost:11434

# Safety
SAFETY_STRICT_MODE=true     # Block MEDIUM risk actions too

# MCP Transport
MCP_TRANSPORT=stdio          # or streamable_http
MCP_PORT=8000

---

🧪 測試

python -m pytest tests/ -v

tests/test_intent.py     — 10 passed  (rule-based + async + mock LLM + fallback)
tests/test_language.py   — 10 passed  (keyword normalisation + detection + code-switch)
tests/test_pipeline.py   —  8 passed  (full e2e: English, Tamil, Hindi, dangerous, edges)
tests/test_safety.py     — 12 passed  (blocklist, regex, risk classification, pipeline)

============================= 40 passed in 0.87s ==============================

測試內容

類別	測試數	覆蓋範圍
語言檢測	10	泰米爾語、印地語、英語、空輸入、語碼切換標誌
意圖提取	10	全部 7 種規則模式、LLM 模擬、LLM 失敗、空輸入
安全引擎	12	關鍵詞、正則、風險等級、完整流水線、嚴格模式
完整流水線	8	端到端英語、泰米爾語、印地語、危險命令、邊界情況

---

🏗️ 架構

npm 版（Node.js / TypeScript）

npm/
├── src/
│   ├── core/
│   │   ├── language.ts       # Vani  — Language detection (zero deps)
│   │   ├── intent.ts         # Bodhi — Intent extraction (LLM + fallback)
│   │   ├── memory.ts         # Smriti — Tiered memory (JSON files)
│   │   ├── safety.ts         # Kavach — 3-layer safety engine
│   │   └── router.ts         # Marga — Multi-model AI router
│   ├── services/
│   │   ├── executor.ts       # Tool registry + retry engine
│   │   └── agent-router.ts   # Setu — Agent-to-Agent routing
│   ├── types.ts              # TypeScript interfaces & enums
│   ├── constants.ts          # Shared constants
│   └── index.ts              # MCP Server — 6 tools (McpServer + Zod)
├── package.json              # npm publish config
├── tsconfig.json
└── LICENSE                   # Apache-2.0

Python 版

app/
├── core/
│   ├── language.py           # Vani  — Language detection (langdetect)
│   ├── intent.py             # Bodhi — Intent extraction (LLM + fallback)
│   ├── memory.py             # Smriti — Tiered memory (PostgreSQL)
│   ├── safety.py             # Kavach — 3-layer safety engine
│   └── router.py             # Marga — Multi-model AI router
├── models/schemas.py         # 12 Pydantic