# laya-mcp — Laya × MiMo Desktop

**English** | [中文](#中文)

Bridge [Laya](https://github.com/NandhaKishorM/laya) typed-decision engine into MiMo Desktop. The LLM decides *whether* to engage Laya (skill rules + tool descriptions); when it does, a local stdio MCP server runs one forward pass and returns `choice` / `score` / `noul` answers with calibrated confidence — no text generation, no hallucination.

## Architecture

```
MiMo Desktop (LLM)
  ├─ skill: ~/.config/mimocode/skills/laya-mcp/   when to use / not use
  └─ MCP stdio: laya_mcp/server.py               4 tools
       └─ laya.Router (english + multilingual)
```

Tools: `laya_predict` · `laya_route` · `laya_preset` · `laya_status`. Contracts: `docs/compose/spec/laya-mcp-integration.md`.

## Cold-start install

```powershell
cd <this-repo>
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# RTX 50-series (sm_120) needs the CUDA 12.8 wheel; otherwise CPU-only torch
pip install torch --index-url https://download.pytorch.org/whl/cu128
pip install -r requirements.txt

python scripts\download_models.py   # pre-download weights
python -m pytest tests -q           # unit tests (no model download)
python scripts\smoke.py             # integration smoke (real model)
```

## Register the MCP server

Edit `C:\Users\<you>\.config\mimocode\mimocode.json` — only the top-level `mcp` section:

```json
{
  "mcp": {
    "laya": {
      "type": "local",
      "command": ["cmd", "/c", "C:\\...\\.venv\\Scripts\\python.exe", "C:\\...\\laya_mcp\\server.py"],
      "environment": { "LAYA_DEVICE": "cuda", "LAYA_PRELOAD": "1" },
      "enabled": true
    }
  }
}
```

**Restart the MiMo Desktop engine (or open a new session) for changes to take effect.**

## Environment variables

| Variable | Default | Description |
|---|---|---|
| `LAYA_DEVICE` | auto | Force `cuda` / `cpu` |
| `LAYA_PRELOAD` | `1` | Preload english+multilingual at startup |
| `LAYA_EAGER_LOAD` | `1` | Load Router in the server process (vs first tool call) |

## Confidence gating

`≥0.85` auto-execute · `0.60–0.85` LLM review · `<0.60` escalate / fallback.

## Troubleshooting

| Symptom | Fix |
|---|---|
| `torch.cuda.is_available() == False` / `nvidia-smi` NVML error | Install the CUDA wheel; otherwise fall back to `LAYA_DEVICE=cpu` |
| First tool call is very slow | Run `python scripts\download_models.py`, keep `LAYA_PRELOAD=1` |
| >20-option choice accuracy drops | Raise `agent.cfg["head_max_len"]` or split the question |
| MCP tools not listed | Validate JSON, use absolute paths, restart the engine |
| Poor Chinese / non-Latin results | Use `model="auto"` (Router) or `multilingual` |

## Development

Unit tests: `tests/` (mocked laya, no network) · Smoke: `scripts/smoke.py` · Spec: `docs/compose/spec/laya-mcp-integration.md`

## License

MIT — see [LICENSE](LICENSE).

---

## 中文

把 [Laya](https://github.com/NandhaKishorM/laya) typed-decision 引擎接进 MiMo Desktop。由 LLM **自行判断**是否调用 Laya（skill 判据 + 工具 description 双保险）；调用时本地 stdio MCP 做一次前向，返回带校准置信度的 `choice` / `score` / `noul` —— 无文本生成、无幻觉。

### 架构

```
MiMo Desktop (LLM)
  ├─ skill: ~/.config/mimocode/skills/laya-mcp/   何时该用 / 不该用
  └─ MCP stdio: laya_mcp/server.py               4 个工具
       └─ laya.Router（english + multilingual）
```

工具：`laya_predict` · `laya_route` · `laya_preset` · `laya_status`。契约见 `docs/compose/spec/laya-mcp-integration.md`。

### 冷启动安装

```powershell
cd <本仓库>
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# RTX 50 系（sm_120）必须用 CUDA 12.8 wheel，否则会装成 CPU 版
pip install torch --index-url https://download.pytorch.org/whl/cu128
pip install -r requirements.txt

python scripts\download_models.py   # 预下载权重
python -m pytest tests -q           # 单测（不下载模型）
python scripts\smoke.py             # 集成冒烟（真实模型）
```

### 注册 MCP

编辑 `C:\Users\<你>\.config\mimocode\mimocode.json`，**只改顶层 `mcp` 段**：

```json
{
  "mcp": {
    "laya": {
      "type": "local",
      "command": ["cmd", "/c", "C:\\...\\.venv\\Scripts\\python.exe", "C:\\...\\laya_mcp\\server.py"],
      "environment": { "LAYA_DEVICE": "cuda", "LAYA_PRELOAD": "1" },
      "enabled": true
    }
  }
}
```

**重启 MiMo Desktop 引擎（或新开会话）后生效。**

### 环境变量

| 变量 | 默认 | 说明 |
|---|---|---|
| `LAYA_DEVICE` | 自动 | 强制 `cuda` / `cpu` |
| `LAYA_PRELOAD` | `1` | 启动时预加载 english+multilingual |
| `LAYA_EAGER_LOAD` | `1` | 在 server 进程启动即加载（而非首次工具调用） |

### 置信度门控

`≥0.85` 自动执行 · `0.60–0.85` LLM 复核 · `<0.60` 转人工。

### 排障

| 现象 | 处理 |
|---|---|
| `torch.cuda.is_available() == False` / `nvidia-smi` 报 NVML 错 | 装 CUDA wheel；否则降级 `LAYA_DEVICE=cpu` |
| 首次工具调用极慢 | 执行 `python scripts\download_models.py`，保持 `LAYA_PRELOAD=1` |
| >20 选项 choice 准确率掉 | 调大 `agent.cfg["head_max_len"]` 或拆分问题 |
| MCP 工具没出现 | 检查 JSON、绝对路径，重启引擎 |
| 中文等非拉丁文结果差 | 用 `model="auto"`（Router）或 `multilingual` |

### 开发

单测：`tests/`（mock laya，无网络）· 冒烟：`scripts/smoke.py` · 设计文档：`docs/compose/spec/laya-mcp-integration.md`

### 许可证

MIT — 见 [LICENSE](LICENSE)。