local-embed 0.2.3__tar.gz → 0.2.4__tar.gz

{local_embed-0.2.3 → local_embed-0.2.4}/.gitignore

@@ -1,5 +1,5 @@
 # Runtime config — personal per-user settings.  The three initial configs
-# (slife.json5 / local_embed.json5 / mcp-plugin.json5) are git-tracked so the
+# (slife.json5 / local_embed.json5 / tools.json5) are git-tracked so the
 # one-click installers can seed them as out-of-the-box defaults.  Copies in a
 # user's data dir (~/.slife/) remain personal and are NOT tracked.
 

{local_embed-0.2.3 → local_embed-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: local-embed
-Version: 0.2.3
+Version: 0.2.4
 Summary: Standalone local embedding server — GGUF / transformer models as an OpenAI-compatible /v1/embeddings service
 Project-URL: Homepage, https://github.com/juzcn/slife
 Project-URL: Repository, https://github.com/juzcn/slife
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Terminals
 Requires-Python: >=3.13
 Requires-Dist: fastmcp>=2.0.0
-Requires-Dist: json5>=0.15.0
+Requires-Dist: json-five>=1.1.2
 Requires-Dist: starlette>=0.37.0
 Provides-Extra: gguf
 Requires-Dist: llama-cpp-python==0.3.34; extra == 'gguf'
@@ -51,15 +51,18 @@ them ([Model weights](#model-weights)).
    vector DB / RAG pipeline ──────┘                          ▼
                                               ┌───────────────────────┐
    slife (plugin host) ─── /mcp ────────────> │       local-embed     │
-                                              │  ONE loaded model     │
+                                              │  models load on demand │
                                               └───────────────────────┘
 ```
 
 ## Features
 
 - **OpenAI-compatible** `/v1/embeddings` + Models API + `/health`.
-- Two backends (GGUF / transformer), **many models configured, one active**.
-- **Lazy load** — startup is fast; the model materialises on first use.
+- Two backends (GGUF / transformer), **many models as peers — each request
+  names the one it wants** (standard OpenAI semantics, no "active model").
+- **Lazy load** — startup is fast; each model materialises on the first
+  request that names it (per-model `autoload: true` preloads a specific
+  model at startup).
 - **Real dimension** reported after load (a guessed width is never served).
 - Runs standalone, and can also be **loaded as a slife plugin** (see
   [Loading as a slife plugin](#loading-as-a-slife-plugin)).
@@ -68,18 +71,36 @@ Requires Python ≥ 3.13.
 
 ## Install
 
-The core package is `fastmcp` + `starlette` + `json5`; the model backends are
+The core package is `fastmcp` + `starlette` + `json-five` (the JSON5 parser,
+imported as `json5`); the model backends are
 optional extras.
 
+One-click installers (install `uv` if needed, then `uv tool install --force
+local-embed` — the backend is **not** included, see below):
+
+```bash
+# macOS / Linux / WSL
+curl -fsSL https://raw.githubusercontent.com/juzcn/slife/main/local-embed/install.sh | bash
+
+# Windows PowerShell
+powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/juzcn/slife/main/local-embed/install.ps1 | iex"
+```
+
+Manual installs are equivalent:
+
 ```bash
 # the app + CLI (standalone tool)
-uv tool install local-embed
+uv tool install --force local-embed
 
 # with a backend:
-uv tool install "local-embed[transformer]"
-uv tool install "local-embed[gguf]"
+uv tool install --force "local-embed[transformer]"
+uv tool install --force "local-embed[gguf]"
 ```
 
+`--force` (used by the installers too) is **idempotent** — the first run
+installs, re-running **updates** to the latest PyPI release.  A plain
+`uv tool install local-embed` no-ops when the tool is already installed.
+
 If you run local-embed inside an *existing* environment (alongside another
 tool), install the backend into **that** environment's interpreter instead of
 creating a separate one:
@@ -140,15 +161,14 @@ Installing does **not** fetch a model — get the weights first.
 
 ## Configuration: `local_embed.json5`
 
-Everything — host, port, models, active model, backend — comes from
+Everything — host, port, models, backend — comes from
 `local_embed.json5`, written by the CLI helpers or by hand. Path resolution:
 `$LOCAL_EMBED_FILE` > slife project root (dev) > `~/.local-embed/local_embed.json5`.
 
 ```json5
 {
-  active_model: "bge-m3",          // model served by default
   models: {
-    "bge-m3": { backend: "gguf", gguf_path: "…", device: "" },
+    "bge-m3": { backend: "gguf", gguf_path: "…", device: "", autoload: false },
     "bge-m3-transformer": { backend: "transformer", model: "BAAI/bge-m3", device: "" }
   },
   env: {                            // injected into this process before any model loads
@@ -160,8 +180,14 @@ Everything — host, port, models, active model, backend — comes from
 }
 ```
 
-- `models` — map of name → `{backend, gguf_path | model, device, max_tokens}`.
-- `active_model` — key into `models`.
+- `models` — map of name → `{backend, gguf_path | model, device, max_tokens, autoload}`.
+  Every configured model is a peer; there is **no `active_model`** — each
+  request names the model it wants (standard OpenAI semantics).
+- `autoload` (per model, default `false`) — a model's weights are large and
+  memory-hungry, so nothing loads until a request names it (**lazy**).
+  `autoload: true` on one model eager-loads just that model in the
+  background at startup (memory paid up front for a warm first embed); every
+  unflagged model stays lazy.
 - `env:` — injected before any backend loads; an existing shell env var wins.
   Without `HF_HUB_CACHE`, transformer repos resolve against the default cache
   and a model downloaded elsewhere is silently re-fetched.
@@ -232,8 +258,8 @@ curl http://127.0.0.1:17347/v1/embeddings \
   -d '{"model": "bge-m3", "input": ["hello world", "another text"]}'
 ```
 
-`input` is a string or a list of strings; `model` names any configured model
-(defaults to the active one). Returns the standard shape:
+`input` is a string or a list of strings; `model` is **required** and names
+any configured model.  Returns the standard shape:
 
 ```json
 {
@@ -247,27 +273,43 @@ curl http://127.0.0.1:17347/v1/embeddings \
 }
 ```
 
-Empty/whitespace inputs get a zero vector of the model's dimension, keeping
-row alignment.
+OpenAI forbids empty-string input, so an empty/whitespace string in the
+batch is rejected with a strict `400` — there is no zero-vector row
+alignment on the wire; filter blanks before batching.
+
+#### Errors — the OpenAI contract
+
+Every error uses the standard envelope
+`{"error": {"message", "type", "param", "code"}}` (`param` / `code` are
+`null` when not applicable):
+
+| Status | `type` | When | `param` / `code` |
+|---|---|---|---|
+| `400` | `invalid_request_error` | unparseable JSON body; `input` not a string/array of strings; missing `model`; empty / whitespace-only input | `input` / `model` |
+| `400` | `invalid_request_error` | input exceeds the model's context length (`max_tokens` — never silently truncated) | `input` / `context_length_exceeded` |
+| `404` | `invalid_request_error` | unknown `model` ("does not exist or you do not have access to it") | — / `model_not_found` |
+| `503` | `server_error` | the model's engine is **still loading** (is_loading — retry shortly) or unavailable (backend dependency missing, load failed) | — |
+| `500` | `server_error` | unexpected internal failure | — |
+
+Split long documents into pieces of at most `max_tokens` tokens client-side
+(slife's semantic drainer does this automatically).
 
 ### `GET /v1/models`
 
 Every configured model, each with its real embedding dimension
-(`dimension` / `dimension_known`), backend, load state, and an `active` flag.
+(`dimension` / `dimension_known`), backend, and load state.  The listing is
+standard — no `active` marker, all models are peers.
 
 ### `GET /v1/models/{id}`
 
 One model's detail (the OpenAI `retrieve` endpoint); 404 with the standard
 error envelope when the id is unknown.
 
-### `POST /v1/models/{id}/activate`
-
-Switch the active model (loads it on demand). A local-embed extension, not an
-OpenAI endpoint.
-
 ### `GET /health`
 
-`{status, active_model, backend, model, dimension, dimension_known, loaded}`.
+Liveness + engine state: `{status, models: [{name, backend, model,
+dimension, dimension_known, loaded, available, max_tokens}]}` — `status`
+is `ok` when any configured model's backend is usable.
 
 ### Any OpenAI client
 
@@ -300,10 +342,11 @@ config.
 
 ### `local-embed set` / `set-gguf` — write the config
 
-`set` (transformer) and `set-gguf` (gguf) upsert a model in the config, make it
-**active**, and pin port (and, for `set`, the HF cache + offline flag). Both
-are **idempotent** — re-running yields the same config — and leave other models
-untouched.
+`set` (transformer) and `set-gguf` (gguf) upsert a model in the config and
+pin port (and, for `set`, the HF cache + offline flag). Both are
+**idempotent** — re-running yields the same config — and leave other models
+untouched.  There is no `active_model`: every configured model is a peer
+and requests name the one they want.
 
 | | `set` (transformer) | `set-gguf` |
 |---|---|---|
@@ -373,84 +416,54 @@ claude mcp add --transport http local-embed http://127.0.0.1:17347/mcp
 > reachable from the desktop app.
 
 **Over MCP you get status, not embeddings.** The only MCP tool is the internal
-`__check` status probe (active model, dimensions, load state) — local-embed is
+`__check` status probe (model list, dimensions, load state) — local-embed is
 a *service-provider* MCP server, not a tool provider. To embed text, point
 your consumer at the OpenAI-compatible `/v1/*` API instead. A client that only
 speaks stdio can reach it through a stdio→HTTP bridge (e.g. `mcp-remote`).
 
-## Loading as a slife plugin
-
-local-embed is a standalone app, but it also conforms to the **slife plugin
-contract** (defined in slife's `slife/server_utils.py`), so slife can load and
-manage it as an external plugin — spawn the process, discover the port, and
-monitor status — without any slife code changes. Conformance is additive:
-none of it constrains standalone use, and local-embed never imports slife. The
-few pieces of the contract it needs are carried as minimal, self-contained
-copies (`local_embed.server_utils`, `local_embed.threads`,
-`local_embed.logging`).
-
-The MCP endpoint's single tool is the internal **`__check`**, which returns
-engine status (active model, model list, dimensions, load state) as JSON. It
-is a **service-provider** surface — slife probes `__check` programmatically and
-consumes embeddings over the HTTP API, never through MCP tools.
-
-How it conforms:
-
-- **Spawn target** — `local_embed/server.py` exposes `main()`, spawnable via
-  `python -m local_embed.server` (the contract's `sys.executable -m <module>`
-  shape).
-- **Port signal** — emits `{"port": N}` on stdout (then closes stdout) only
-  after the FastMCP app is ready to serve (its lifespan completed), so the
-  host's first `initialize` always lands on a ready server.
-- **Readiness = MCP `initialize` handshake** — startup is handshake-fast:
-  backend imports are resolved lazily and the model warms up *after* the first
-  `tools/list` (`warm_after_handshake`), never in the lifespan.
-- **Internal `__check` tool** — `__`-prefixed, so the host's tool registration
-  filters it out of the LLM registry and `system_health` probes it
-  programmatically.
-- **Non-MCP routes on the same port** — the OpenAI endpoints are
-  `@mcp.custom_route` handlers on the same uvicorn app (the "one port, two
-  protocols" pattern).
-- **Logging adoption** — when spawned by slife it adopts `SLIFE_LOG_DIR` /
-  `SLIFE_AGENT_NAME` / `SLIFE_SESSION_ID` / `SLIFE_PLUGIN_NAME`, so the session
-  log lands next to the main log; an uncaught startup exception prints one
-  clean stderr line (the host relays it) with the full traceback in the file.
-  Standalone falls back to `~/.local-embed/logs`.
-- **Config path** — honors `$LOCAL_EMBED_FILE` (slife exports it as
-  `<dir of slife.json5>/local_embed.json5`), else the standalone default.
-- **Stable port** — binds the configured `17347` rather than an OS-assigned
-  port, so slife's `base_url` is fixed; a taken port is a hard error, not a
-  silent fallback.
-
-### Registering with slife
-
-Register local-embed as an external plugin and point slife's embedding config
-at it (the unified OpenAI-compatible format slife uses for every embedding
-model):
+## Running as a slife embedding backend
+
+local-embed is a **plugin** — one row in slife's central plugin spec, so
+slife spawns it, watches it, and reports it like every other child plugin. It
+is also runnable standalone (`local-embed` on PATH), which is what the CLI is
+for; slife still consumes the MODEL SERVICE purely as an OpenAI-compatible
+HTTP endpoint (never through MCP tools).
+
+Because its config pins a port that a static embeddings `base_url` points at,
+it is the one plugin with a **fixed** port: it binds that port itself and a
+taken port is a hard error (no fallback — a second instance would double the
+model in memory and serve nothing new). The host then reports the plugin as
+failed to load, with the reason, and the running instance keeps serving.
+
+Point slife's embedding config at the daemon's stable port:
 
 ```json5
-plugins: {
-  external: [
-    { name: "local-embed", module: "local_embed.server" }
-  ]
-},
 embeddings: {
   providers: {
-    "local-embed": {
+    local: {
       base_url: "http://127.0.0.1:17347/v1",  // stable port from local_embed.json5
       api_key: "local",
+      model: "bge-m3",                        // id POSTed on /v1/embeddings
     }
   },
-  active_model: "local-embed",   // provider-id only, or "local-embed/<model>"
+  active_model: "local",      // provider-id only, or "local/<model>"
   enabled: true
 }
 ```
 
 slife treats every embedding model as a remote OpenAI-compatible endpoint —
-local-embed is one such endpoint. The model is **determined by the plugin's
-active model**: slife discovers it from `GET /v1/models` (the entry flagged
-`active: true`) on load. When the service is unreachable, slife degrades
-gracefully to keyword search.
+local-embed is one such endpoint. The model a request hits is the one the
+caller names; when the config names no model, slife discovers it from
+`GET /v1/models` (the first entry) on load. When the daemon is unreachable,
+slife degrades gracefully to keyword search (`check_embeddings` in
+`system_health` probes the **active** provider's HTTP endpoint and reports it
+down — it never assumes that provider is local-embed).
+
+The MCP surface it still serves is the internal **`__check`** (engine status:
+model list, dimensions, load state) — a service-provider facade
+for direct probing, not a slife plugin contract. It also serves plain OpenAPI
+routes (`/v1/embeddings`, `/v1/models`, `/health`) on the same port via
+`@mcp.custom_route` — one port, two protocols, no slife involvement.
 
 ## License
 

{local_embed-0.2.3 → local_embed-0.2.4}/README.md

@@ -25,15 +25,18 @@ them ([Model weights](#model-weights)).
    vector DB / RAG pipeline ──────┘                          ▼
                                               ┌───────────────────────┐
    slife (plugin host) ─── /mcp ────────────> │       local-embed     │
-                                              │  ONE loaded model     │
+                                              │  models load on demand │
                                               └───────────────────────┘
 ```
 
 ## Features
 
 - **OpenAI-compatible** `/v1/embeddings` + Models API + `/health`.
-- Two backends (GGUF / transformer), **many models configured, one active**.
-- **Lazy load** — startup is fast; the model materialises on first use.
+- Two backends (GGUF / transformer), **many models as peers — each request
+  names the one it wants** (standard OpenAI semantics, no "active model").
+- **Lazy load** — startup is fast; each model materialises on the first
+  request that names it (per-model `autoload: true` preloads a specific
+  model at startup).
 - **Real dimension** reported after load (a guessed width is never served).
 - Runs standalone, and can also be **loaded as a slife plugin** (see
   [Loading as a slife plugin](#loading-as-a-slife-plugin)).
@@ -42,18 +45,36 @@ Requires Python ≥ 3.13.
 
 ## Install
 
-The core package is `fastmcp` + `starlette` + `json5`; the model backends are
+The core package is `fastmcp` + `starlette` + `json-five` (the JSON5 parser,
+imported as `json5`); the model backends are
 optional extras.
 
+One-click installers (install `uv` if needed, then `uv tool install --force
+local-embed` — the backend is **not** included, see below):
+
+```bash
+# macOS / Linux / WSL
+curl -fsSL https://raw.githubusercontent.com/juzcn/slife/main/local-embed/install.sh | bash
+
+# Windows PowerShell
+powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/juzcn/slife/main/local-embed/install.ps1 | iex"
+```
+
+Manual installs are equivalent:
+
 ```bash
 # the app + CLI (standalone tool)
-uv tool install local-embed
+uv tool install --force local-embed
 
 # with a backend:
-uv tool install "local-embed[transformer]"
-uv tool install "local-embed[gguf]"
+uv tool install --force "local-embed[transformer]"
+uv tool install --force "local-embed[gguf]"
 ```
 
+`--force` (used by the installers too) is **idempotent** — the first run
+installs, re-running **updates** to the latest PyPI release.  A plain
+`uv tool install local-embed` no-ops when the tool is already installed.
+
 If you run local-embed inside an *existing* environment (alongside another
 tool), install the backend into **that** environment's interpreter instead of
 creating a separate one:
@@ -114,15 +135,14 @@ Installing does **not** fetch a model — get the weights first.
 
 ## Configuration: `local_embed.json5`
 
-Everything — host, port, models, active model, backend — comes from
+Everything — host, port, models, backend — comes from
 `local_embed.json5`, written by the CLI helpers or by hand. Path resolution:
 `$LOCAL_EMBED_FILE` > slife project root (dev) > `~/.local-embed/local_embed.json5`.
 
 ```json5
 {
-  active_model: "bge-m3",          // model served by default
   models: {
-    "bge-m3": { backend: "gguf", gguf_path: "…", device: "" },
+    "bge-m3": { backend: "gguf", gguf_path: "…", device: "", autoload: false },
     "bge-m3-transformer": { backend: "transformer", model: "BAAI/bge-m3", device: "" }
   },
   env: {                            // injected into this process before any model loads
@@ -134,8 +154,14 @@ Everything — host, port, models, active model, backend — comes from
 }
 ```
 
-- `models` — map of name → `{backend, gguf_path | model, device, max_tokens}`.
-- `active_model` — key into `models`.
+- `models` — map of name → `{backend, gguf_path | model, device, max_tokens, autoload}`.
+  Every configured model is a peer; there is **no `active_model`** — each
+  request names the model it wants (standard OpenAI semantics).
+- `autoload` (per model, default `false`) — a model's weights are large and
+  memory-hungry, so nothing loads until a request names it (**lazy**).
+  `autoload: true` on one model eager-loads just that model in the
+  background at startup (memory paid up front for a warm first embed); every
+  unflagged model stays lazy.
 - `env:` — injected before any backend loads; an existing shell env var wins.
   Without `HF_HUB_CACHE`, transformer repos resolve against the default cache
   and a model downloaded elsewhere is silently re-fetched.
@@ -206,8 +232,8 @@ curl http://127.0.0.1:17347/v1/embeddings \
   -d '{"model": "bge-m3", "input": ["hello world", "another text"]}'
 ```
 
-`input` is a string or a list of strings; `model` names any configured model
-(defaults to the active one). Returns the standard shape:
+`input` is a string or a list of strings; `model` is **required** and names
+any configured model.  Returns the standard shape:
 
 ```json
 {
@@ -221,27 +247,43 @@ curl http://127.0.0.1:17347/v1/embeddings \
 }
 ```
 
-Empty/whitespace inputs get a zero vector of the model's dimension, keeping
-row alignment.
+OpenAI forbids empty-string input, so an empty/whitespace string in the
+batch is rejected with a strict `400` — there is no zero-vector row
+alignment on the wire; filter blanks before batching.
+
+#### Errors — the OpenAI contract
+
+Every error uses the standard envelope
+`{"error": {"message", "type", "param", "code"}}` (`param` / `code` are
+`null` when not applicable):
+
+| Status | `type` | When | `param` / `code` |
+|---|---|---|---|
+| `400` | `invalid_request_error` | unparseable JSON body; `input` not a string/array of strings; missing `model`; empty / whitespace-only input | `input` / `model` |
+| `400` | `invalid_request_error` | input exceeds the model's context length (`max_tokens` — never silently truncated) | `input` / `context_length_exceeded` |
+| `404` | `invalid_request_error` | unknown `model` ("does not exist or you do not have access to it") | — / `model_not_found` |
+| `503` | `server_error` | the model's engine is **still loading** (is_loading — retry shortly) or unavailable (backend dependency missing, load failed) | — |
+| `500` | `server_error` | unexpected internal failure | — |
+
+Split long documents into pieces of at most `max_tokens` tokens client-side
+(slife's semantic drainer does this automatically).
 
 ### `GET /v1/models`
 
 Every configured model, each with its real embedding dimension
-(`dimension` / `dimension_known`), backend, load state, and an `active` flag.
+(`dimension` / `dimension_known`), backend, and load state.  The listing is
+standard — no `active` marker, all models are peers.
 
 ### `GET /v1/models/{id}`
 
 One model's detail (the OpenAI `retrieve` endpoint); 404 with the standard
 error envelope when the id is unknown.
 
-### `POST /v1/models/{id}/activate`
-
-Switch the active model (loads it on demand). A local-embed extension, not an
-OpenAI endpoint.
-
 ### `GET /health`
 
-`{status, active_model, backend, model, dimension, dimension_known, loaded}`.
+Liveness + engine state: `{status, models: [{name, backend, model,
+dimension, dimension_known, loaded, available, max_tokens}]}` — `status`
+is `ok` when any configured model's backend is usable.
 
 ### Any OpenAI client
 
@@ -274,10 +316,11 @@ config.
 
 ### `local-embed set` / `set-gguf` — write the config
 
-`set` (transformer) and `set-gguf` (gguf) upsert a model in the config, make it
-**active**, and pin port (and, for `set`, the HF cache + offline flag). Both
-are **idempotent** — re-running yields the same config — and leave other models
-untouched.
+`set` (transformer) and `set-gguf` (gguf) upsert a model in the config and
+pin port (and, for `set`, the HF cache + offline flag). Both are
+**idempotent** — re-running yields the same config — and leave other models
+untouched.  There is no `active_model`: every configured model is a peer
+and requests name the one they want.
 
 | | `set` (transformer) | `set-gguf` |
 |---|---|---|
@@ -347,84 +390,54 @@ claude mcp add --transport http local-embed http://127.0.0.1:17347/mcp
 > reachable from the desktop app.
 
 **Over MCP you get status, not embeddings.** The only MCP tool is the internal
-`__check` status probe (active model, dimensions, load state) — local-embed is
+`__check` status probe (model list, dimensions, load state) — local-embed is
 a *service-provider* MCP server, not a tool provider. To embed text, point
 your consumer at the OpenAI-compatible `/v1/*` API instead. A client that only
 speaks stdio can reach it through a stdio→HTTP bridge (e.g. `mcp-remote`).
 
-## Loading as a slife plugin
-
-local-embed is a standalone app, but it also conforms to the **slife plugin
-contract** (defined in slife's `slife/server_utils.py`), so slife can load and
-manage it as an external plugin — spawn the process, discover the port, and
-monitor status — without any slife code changes. Conformance is additive:
-none of it constrains standalone use, and local-embed never imports slife. The
-few pieces of the contract it needs are carried as minimal, self-contained
-copies (`local_embed.server_utils`, `local_embed.threads`,
-`local_embed.logging`).
-
-The MCP endpoint's single tool is the internal **`__check`**, which returns
-engine status (active model, model list, dimensions, load state) as JSON. It
-is a **service-provider** surface — slife probes `__check` programmatically and
-consumes embeddings over the HTTP API, never through MCP tools.
-
-How it conforms:
-
-- **Spawn target** — `local_embed/server.py` exposes `main()`, spawnable via
-  `python -m local_embed.server` (the contract's `sys.executable -m <module>`
-  shape).
-- **Port signal** — emits `{"port": N}` on stdout (then closes stdout) only
-  after the FastMCP app is ready to serve (its lifespan completed), so the
-  host's first `initialize` always lands on a ready server.
-- **Readiness = MCP `initialize` handshake** — startup is handshake-fast:
-  backend imports are resolved lazily and the model warms up *after* the first
-  `tools/list` (`warm_after_handshake`), never in the lifespan.
-- **Internal `__check` tool** — `__`-prefixed, so the host's tool registration
-  filters it out of the LLM registry and `system_health` probes it
-  programmatically.
-- **Non-MCP routes on the same port** — the OpenAI endpoints are
-  `@mcp.custom_route` handlers on the same uvicorn app (the "one port, two
-  protocols" pattern).
-- **Logging adoption** — when spawned by slife it adopts `SLIFE_LOG_DIR` /
-  `SLIFE_AGENT_NAME` / `SLIFE_SESSION_ID` / `SLIFE_PLUGIN_NAME`, so the session
-  log lands next to the main log; an uncaught startup exception prints one
-  clean stderr line (the host relays it) with the full traceback in the file.
-  Standalone falls back to `~/.local-embed/logs`.
-- **Config path** — honors `$LOCAL_EMBED_FILE` (slife exports it as
-  `<dir of slife.json5>/local_embed.json5`), else the standalone default.
-- **Stable port** — binds the configured `17347` rather than an OS-assigned
-  port, so slife's `base_url` is fixed; a taken port is a hard error, not a
-  silent fallback.
-
-### Registering with slife
-
-Register local-embed as an external plugin and point slife's embedding config
-at it (the unified OpenAI-compatible format slife uses for every embedding
-model):
+## Running as a slife embedding backend
+
+local-embed is a **plugin** — one row in slife's central plugin spec, so
+slife spawns it, watches it, and reports it like every other child plugin. It
+is also runnable standalone (`local-embed` on PATH), which is what the CLI is
+for; slife still consumes the MODEL SERVICE purely as an OpenAI-compatible
+HTTP endpoint (never through MCP tools).
+
+Because its config pins a port that a static embeddings `base_url` points at,
+it is the one plugin with a **fixed** port: it binds that port itself and a
+taken port is a hard error (no fallback — a second instance would double the
+model in memory and serve nothing new). The host then reports the plugin as
+failed to load, with the reason, and the running instance keeps serving.
+
+Point slife's embedding config at the daemon's stable port:
 
 ```json5
-plugins: {
-  external: [
-    { name: "local-embed", module: "local_embed.server" }
-  ]
-},
 embeddings: {
   providers: {
-    "local-embed": {
+    local: {
       base_url: "http://127.0.0.1:17347/v1",  // stable port from local_embed.json5
       api_key: "local",
+      model: "bge-m3",                        // id POSTed on /v1/embeddings
     }
   },
-  active_model: "local-embed",   // provider-id only, or "local-embed/<model>"
+  active_model: "local",      // provider-id only, or "local/<model>"
   enabled: true
 }
 ```
 
 slife treats every embedding model as a remote OpenAI-compatible endpoint —
-local-embed is one such endpoint. The model is **determined by the plugin's
-active model**: slife discovers it from `GET /v1/models` (the entry flagged
-`active: true`) on load. When the service is unreachable, slife degrades
-gracefully to keyword search.
+local-embed is one such endpoint. The model a request hits is the one the
+caller names; when the config names no model, slife discovers it from
+`GET /v1/models` (the first entry) on load. When the daemon is unreachable,
+slife degrades gracefully to keyword search (`check_embeddings` in
+`system_health` probes the **active** provider's HTTP endpoint and reports it
+down — it never assumes that provider is local-embed).
+
+The MCP surface it still serves is the internal **`__check`** (engine status:
+model list, dimensions, load state) — a service-provider facade
+for direct probing, not a slife plugin contract. It also serves plain OpenAPI
+routes (`/v1/embeddings`, `/v1/models`, `/health`) on the same port via
+`@mcp.custom_route` — one port, two protocols, no slife involvement.
 
 ## License