@houtini/lm 2.13.2 → 3.1.0

package/README.md

@@ -40,6 +40,8 @@ Claude's the architect. Your local model's the drafter. Claude QAs everything.
 
 ## Quick start
 
+> New to local models? See **[docs/GETTING-STARTED.md](./docs/GETTING-STARTED.md)** — installing LM Studio or a Docker endpoint, getting an OpenAI-compatible URL for houtini, what the smaller models are good at, and which models fit on 16/32/64/96/128 GB of VRAM.
+
 ### Claude Code
 
 ```bash
@@ -125,7 +127,7 @@ Available models (downloaded, not loaded):
     HuggingFace: text-generation, 12.9K downloads, Apache-2.0
 ```
 
-For models we know well - Qwen, Nemotron, Granite, LLaMA, GLM, GPT-OSS - there's a curated profile built in with specific strengths and weaknesses. For everything else, the HuggingFace lookup fills the gaps. Cache refreshes every 7 days. Zero friction - `sql.js` is pure WASM, no native dependencies, no build tools needed.
+For models we know well - Qwen, Nemotron, Granite, LLaMA, GLM, GPT-OSS - there's a curated profile built in with specific strengths and weaknesses. For everything else, the HuggingFace lookup fills the gaps. Cache refreshes every 7 days. Zero friction - the cache uses `node:sqlite` (Node's built-in SQLite, so no third-party native dependency and no build tools) in WAL mode, which lets several houtini-lm processes share one cache safely. Requires Node ≥ 22.5.
 
 ## What gets offloaded
 
@@ -289,7 +291,7 @@ Example output:
 
 ```
 ## Houtini LM stats
-**Endpoint**: http://hopper:1234 (LM Studio)
+**Endpoint**: http://gpu-box:1234 (LM Studio)
 **First call on this workstation**: 2026-04-14
 
 ### Totals
@@ -362,7 +364,7 @@ The canonical way to verify an install and get an honest read on what the loaded
 npm run shakedown
 ```
 
-This runs [`shakedown.mjs`](./shakedown.mjs) — an end-to-end test that exercises all seven tools (`discover` → `list_models` → `chat` → `custom_prompt` → `code_task` → `code_task_files` → `embed`) and prints a summary table with real TTFT, tok/s, token counts, and reasoning-token split for each call. Takes under a minute on a decent rig.
+This runs [`shakedown.mjs`](./shakedown.mjs) — an end-to-end test that exercises seven of the eight tools (`discover` → `list_models` → `chat` → `custom_prompt` → `code_task` → `code_task_files` → `embed`; `stats` is not covered) and prints a summary table with real TTFT, tok/s, token counts, and reasoning-token split for each call. Takes under a minute on a decent rig.
 
 Sample output tail:
 
@@ -446,6 +448,15 @@ On **remote** providers (OpenRouter, DeepSeek, Groq, Cerebras, and anything dete
 | `HOUTINI_LM_MODEL` | *(auto-detect)* | Model identifier — leave blank to use whatever's loaded. Legacy alias: `LM_STUDIO_MODEL`. |
 | `HOUTINI_LM_PROVIDER` | *(auto-detect)* | Force provider-specific handling. Set to `openrouter` for OpenRouter attribution headers, `reasoning.exclude`, and no inference serialisation. Otherwise auto-detected from the endpoint URL. |
 | `HOUTINI_LM_CONTEXT_WINDOW` | `100000` | Fallback context window if the API doesn't report it. Legacy alias: `LM_CONTEXT_WINDOW`. |
+| `HOUTINI_LM_FILE_ROOTS` | *(unset)* | Optional `:`/`,`-separated allowlist of directory roots `code_task_files` may read from (symlink-resolved). Unset = any absolute path. |
+| `HOUTINI_LM_MAX_FILE_MB` | `10` | Per-file size cap for `code_task_files`. |
+| `HOUTINI_LM_CROSS_PROCESS_LOCK` | `1` | Set to `0` to disable just the cross-process inference lock (keeps the in-process semaphore). |
+| `HOUTINI_LM_SERIALISE` | `1` | Set to `0` to disable inference serialisation entirely (both the in-process semaphore and the cross-process lock). Use for backends that batch natively (vLLM, TGI, SGLang) where one-at-a-time only throttles throughput. |
+| `HOUTINI_LM_MIN_TOKENS` | `4096` | Floor for caller-supplied `max_tokens`. Values below the floor are ignored and the dynamic budget (25% of the model's context window) applies — MCP clients habitually pass tiny caps like 256 that strangle reasoning models. Set to `0` to honour any value (e.g. deliberate micro-chunking on slow hardware). |
+
+**Per-request sampling** — `chat`, `custom_prompt`, `code_task`, and `code_task_files` also accept optional `seed`, `stop`, `top_p`, `top_k`, `repeat_penalty`, `frequency_penalty`, and `presence_penalty`. Out-of-range values are ignored; the backend default applies.
+
+> **Requires Node ≥ 22.5** (≥ 22.13 recommended) — the model cache uses Node's built-in `node:sqlite`. On older Node the server still runs, without the cache.
 
 ## Compatible endpoints
 
@@ -473,7 +484,7 @@ If the connection stalls (no new tokens for an extended period), you get a parti
 
 ```
 index.ts          Main MCP server - tools, streaming, session tracking
-model-cache.ts    SQLite-backed model profile cache (sql.js / WASM)
+model-cache.ts    SQLite-backed model profile cache (node:sqlite, WAL)
                   Auto-profiles models via HuggingFace API at startup
                   Persists to ~/.houtini-lm/model-cache.db
 

package/dist/index.d.ts

@@ -5,4 +5,4 @@
  * Connects to LM Studio (or any OpenAI-compatible endpoint) and exposes
  * chat, custom prompts, code tasks, and model discovery as MCP tools.
  */
-export {};
+import './suppress-experimental-warnings.js';