local-embed 0.1.0__py3-none-any.whl

local_embed/__init__.py

@@ -0,0 +1,29 @@
+"""local-embed — standalone local embedding server.
+
+Loads a local GGUF (llama-cpp) or HF transformer embedding model ONCE and
+exposes it as an OpenAI-compatible ``/v1/embeddings`` HTTP endpoint plus
+FastMCP tools.  slife's memdb/memfiles plugins both call it over HTTP, so
+the model is never loaded twice in one process tree.
+
+Modules::
+
+    server.py     FastMCP plugin — MCP tools + /v1/embeddings custom route
+    engine.py     Model engine (gguf / transformer), lazy load + encode
+    cli.py        Console entry point (``local-embed``)
+    threads.py    run_daemon — daemon-thread offload for blocking model calls
+    logging.py    Structured logging setup
+
+Usage::
+
+    local-embed --backend gguf --gguf-path /path/to/model.gguf
+    local-embed --backend transformer --model BAAI/bge-m3
+"""
+
+try:
+    from importlib.metadata import version as _version
+
+    __version__ = _version("local-embed")
+except Exception:
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

local_embed/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point for ``python -m local_embed`` — delegates to the CLI."""
+
+import sys
+
+from local_embed.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

local_embed/cli.py

@@ -0,0 +1,88 @@
+"""Console entry point for local-embed.
+
+Two entry paths share this module:
+
+- ``local-embed …`` (console script / ``python -m local_embed``): run the
+  server on an explicit host:port as a standalone service.
+
+- ``python -m local_embed.server``: the **plugin spawn target** used by a
+  host (slife) — binds a free port, serves MCP on ``/mcp`` and embeddings
+  on the same port, and signals the parent.  That path lives in
+  :mod:`local_embed.server` and does NOT go through this CLI.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+
+from local_embed.config import resolve_engine_settings
+from local_embed.engine import Engine, check_backend_runtime
+from local_embed.logging import setup_logging
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="local-embed",
+        description=(
+            "Standalone local embedding server — expose a GGUF (llama-cpp) or "
+            "HF transformer model as an OpenAI-compatible /v1/embeddings service."
+        ),
+    )
+    p.add_argument("--host", default="127.0.0.1", help="bind host (default 127.0.0.1)")
+    p.add_argument("--port", type=int, default=8000, help="bind port (default 8000)")
+    p.add_argument(
+        "--backend",
+        choices=("gguf", "transformer"),
+        default="gguf",
+        help="model backend (default gguf)",
+    )
+    p.add_argument("--model", default="bge-m3", help="model name/id (for metadata and dim guessing)")
+    p.add_argument("--gguf-path", default="", help="path to a GGUF file (backend=gguf)")
+    p.add_argument("--device", default="", help="device for transformer backend: cpu | cuda | '' (auto)")
+    p.add_argument("--log-level", default="INFO", help="logging level (default INFO)")
+    return p
+
+
+def main(argv: "list[str] | None" = None) -> int:
+    args = build_parser().parse_args(argv)
+    setup_logging(getattr(logging, args.log_level.upper(), logging.INFO))
+
+    # CLI flags are one-model overrides on top of local_embed.json5.  A
+    # config file with a ``models`` map wins; explicit flags on a
+    # single-model config override its keys.
+    settings = resolve_engine_settings(
+        overrides={
+            "backend": args.backend,
+            "model": args.model,
+            "gguf_path": args.gguf_path,
+            "device": args.device,
+        }
+    )
+    engine = Engine(specs=settings["specs"], active=settings["active"])
+
+    # Validate the gguf backend actually has a model to load.
+    for spec in settings["specs"]:
+        if spec.backend == "gguf" and not spec.gguf_path:
+            print(
+                f"Error: no gguf_path for model '{spec.name}'. "
+                "Set gguf_path in local_embed.json5 or pass --gguf-path.",
+                file=sys.stderr,
+            )
+            return 2
+        if not check_backend_runtime(spec.backend):
+            print(
+                f"Error: {spec.backend} backend for model '{spec.name}' is not installed. "
+                f"Install with: uv pip install 'local-embed[{spec.backend}]'",
+                file=sys.stderr,
+            )
+            return 2
+
+    from local_embed.server import serve_standalone
+
+    return serve_standalone(engine, host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

local_embed/config.py

@@ -0,0 +1,200 @@
+"""local-embed config — load ``local_embed.json5``, path resolution.
+
+Path precedence (mirrors mcp-plugin / credstore):
+  1. ``$LOCAL_EMBED_FILE`` — a host (slife) exports this =
+     ``<dir of slife.json5>/local_embed.json5`` before it launches the
+     plugin child, so the config sits next to the host's config
+  2. slife project root (dev): CWD is the slife source root
+     (``pyproject.toml`` ``project.name == "slife"``) — ``./local_embed.json5``
+     (credstore's ``is_slife_dev`` pattern)
+  3. ``~/.local-embed/local_embed.json5`` (standalone default, credstore-style)
+
+Config shape::
+
+    {
+      active_model: "bge-m3",
+      models: {
+        "bge-m3": { backend: "gguf", gguf_path: "…", device: "" },
+        "bge-m3-transformer": { backend: "transformer", model: "BAAI/bge-m3" },
+      },
+      host: "127.0.0.1",    // standalone only
+      port: 8000,           // standalone only
+    }
+
+``env`` (optional, top level) is injected into this process's environment
+by :func:`apply_env` before any backend loads — a ``transformer`` ``model``
+given as a HF *repo name* (e.g. ``BAAI/bge-m3``) resolves against the local
+hub cache via ``HF_HUB_CACHE`` / ``HF_HUB_OFFLINE`` without the host
+exporting anything::
+
+    {
+      active_model: "bge-m3-transformer",
+      env: { HF_HUB_CACHE: "C:\\…\\HuggingFace\\hub", HF_HUB_OFFLINE: "1" },
+      models: { "bge-m3-transformer": { backend: "transformer", model: "BAAI/bge-m3" } },
+    }
+
+Single-model convenience (still supported) — ``backend`` / ``model`` /
+``gguf_path`` / ``device`` at the top level, exactly one model::
+
+    { backend: "gguf", model: "bge-m3", gguf_path: "…", device: "" }
+
+Reads are read-only at runtime — local-embed has no config-mutating tools
+(mirrors mcp-plugin's self-hosted config, minus the persistence).
+"""
+
+from __future__ import annotations
+
+import json5
+import logging
+import os
+import tomllib
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8000
+
+
+def default_config_path() -> Path:
+    """Standalone default: ``~/.local-embed/local_embed.json5``."""
+    return Path.home() / ".local-embed" / "local_embed.json5"
+
+
+def resolve_config_path() -> Path:
+    """Return the local_embed.json5 path for this process.
+
+    Precedence (mirrors mcp-plugin's ``resolve_config_path``):
+    ``$LOCAL_EMBED_FILE`` > slife project root (dev) > standalone default.
+    """
+    env = os.environ.get("LOCAL_EMBED_FILE")
+    if env:
+        return Path(env).expanduser()
+    if is_slife_dev():
+        return Path("local_embed.json5")
+    return default_config_path()
+
+
+def is_slife_dev() -> bool:
+    """Whether we're running from the slife source root (credstore-style).
+
+    Returns True when the CWD contains a ``pyproject.toml`` with
+    ``project.name == "slife"``.
+    """
+    try:
+        data = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))
+    except Exception:
+        return False
+    return data.get("project", {}).get("name") == "slife"
+
+
+def load_config(path: "Path | None" = None) -> dict:
+    """Load the local-embed config dict, ``{}`` when the file is absent.
+
+    A file that exists but cannot be parsed raises (a broken config must
+    not be silently replaced by defaults).
+    """
+    if path is None:
+        path = resolve_config_path()
+    try:
+        return json5.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        logger.info("config_not_found path=%s", path)
+        return {}
+    except (ValueError, OSError) as e:
+        logger.error("config_parse_error path=%s err=%s", path, e)
+        raise ValueError(f"Cannot parse config {path}: {e}") from e
+
+
+def apply_env() -> dict:
+    """Inject local-embed's ``env:`` config section into os.environ.
+
+    A transformer backend loads its model by HF *repo name* (e.g.
+    ``BAAI/bge-m3``); huggingface_hub resolves that name against the local
+    hub cache, which defaults to ``~/.cache/huggingface``.  ``env:`` in the
+    config makes the server self-contained — it exports ``HF_HUB_CACHE`` /
+    ``HF_HUB_OFFLINE`` (or anything else) into its *own* process before any
+    backend loads, and no external ``HF_*`` export is needed from the host.
+
+    Precedence mirrors slife.json5's ``env:`` injection: an existing
+    ``os.environ`` value wins, so a host can always override the config
+    file.  Returns the effective env vars (for tests).
+    """
+    cfg = load_config()
+    effective: dict = {}
+    for key, value in (cfg.get("env") or {}).items():
+        if os.environ.get(key):
+            logger.info("env_from_shell key=%s", key)
+            continue
+        os.environ[key] = str(value)
+        effective[key] = str(value)
+        logger.info("env_injected key=%s", key)
+    return effective
+
+
+def resolve_engine_settings(overrides: "dict | None" = None) -> dict:
+    """Merge config file + env overrides into engine settings.
+
+    Precedence: env vars (plugin spawn) > config file > defaults.  Returns
+    ``{"specs": [ModelSpec, ...], "active": str, "host", "port"}``.
+
+    A ``models`` map (multi-model) takes precedence; otherwise the
+    single-model top-level keys build one spec.
+    """
+    from local_embed.engine import ModelSpec
+
+    apply_env()  # config env: → own process env, before any model loads
+    cfg = load_config()
+    overrides = overrides or {}
+
+    def _pick(key: str, default):
+        env_val = os.environ.get(f"LOCAL_EMBED_{key.upper()}")
+        if env_val not in (None, ""):
+            return env_val
+        if key in overrides and overrides[key] not in (None, ""):
+            return overrides[key]
+        if key in cfg and cfg[key] not in (None, ""):
+            return cfg[key]
+        return default
+
+    specs: list = []
+    models_cfg = cfg.get("models")
+    if isinstance(models_cfg, dict) and models_cfg:
+        for name, m in models_cfg.items():
+            if not isinstance(m, dict):
+                continue
+            # env override may point at the single model keyed by its name
+            specs.append(
+                ModelSpec(
+                    name,
+                    backend=m.get("backend", "gguf"),
+                    model=m.get("model") or name,
+                    gguf_path=m.get("gguf_path") or None,
+                    device=m.get("device", ""),
+                    max_tokens=int(m.get("max_tokens", 0) or 0),
+                )
+            )
+        # Precedence: env override > config file > default (mirrors _pick).
+        active = _pick("active_model", specs[0].name)
+        if active not in {s.name for s in specs}:
+            active = specs[0].name
+    else:
+        backend = _pick("backend", "gguf")
+        model = _pick("model", "bge-m3")
+        specs = [
+            ModelSpec(
+                model,
+                backend=backend,
+                model=model,
+                gguf_path=_pick("gguf_path", "") or None,
+                device=_pick("device", ""),
+            )
+        ]
+        active = model
+
+    return {
+        "specs": specs,
+        "active": active,
+        "host": cfg.get("host", overrides.get("host", DEFAULT_HOST)),
+        "port": int(cfg.get("port", overrides.get("port", DEFAULT_PORT))),
+    }