cocoindex-code 0.2.22__tar.gz → 0.2.23__tar.gz

{cocoindex_code-0.2.22 → cocoindex_code-0.2.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cocoindex-code
-Version: 0.2.22
+Version: 0.2.23
 Summary: MCP server for indexing and querying codebases using CocoIndex
 Project-URL: Homepage, https://github.com/cocoindex-io/cocoindex-code
 Project-URL: Repository, https://github.com/cocoindex-io/cocoindex-code
@@ -25,16 +25,21 @@ Requires-Dist: numpy>=1.24.0
 Requires-Dist: pathspec>=0.12.1
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: pyyaml>=6.0
-Requires-Dist: sentence-transformers>=2.2.0
+Requires-Dist: questionary>=2.0.0
 Requires-Dist: sqlite-vec>=0.1.0
 Requires-Dist: typer>=0.9.0
+Provides-Extra: default
+Requires-Dist: cocoindex[sentence-transformers]==1.0.0a43; extra == 'default'
 Provides-Extra: dev
+Requires-Dist: cocoindex[sentence-transformers]==1.0.0a43; extra == 'dev'
 Requires-Dist: mypy>=1.0.0; extra == 'dev'
 Requires-Dist: prek>=0.1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
 Requires-Dist: pytest>=7.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: embeddings-local
+Requires-Dist: cocoindex[sentence-transformers]==1.0.0a43; extra == 'embeddings-local'
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -85,16 +90,18 @@ A lightweight, effective **(AST-based)** semantic code search tool for your code
 
 Using [pipx](https://pipx.pypa.io/stable/installation/):
 ```bash
-pipx install cocoindex-code       # first install
-pipx upgrade cocoindex-code       # upgrade
+pipx install 'cocoindex-code[default]'       # batteries included (local embeddings)
+pipx upgrade cocoindex-code                  # upgrade
 ```
 
 Using [uv](https://docs.astral.sh/uv/getting-started/installation/):
 ```bash
-uv tool install --upgrade cocoindex-code --prerelease explicit --with "cocoindex>=1.0.0a24"
+uv tool install --upgrade 'cocoindex-code[default]' --prerelease explicit --with "cocoindex>=1.0.0a24"
 ```
 
-The default embedding model runs locally ([sentence-transformers/all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2)) — no API key required, completely free.
+Two install styles:
+- `cocoindex-code[default]` — batteries-included. Pulls in `sentence-transformers` so local embeddings (no API key required) work out of the box. The `ccc init` interactive prompt defaults to [Snowflake/snowflake-arctic-embed-xs](https://huggingface.co/Snowflake/snowflake-arctic-embed-xs).
+- `cocoindex-code` — slim. LiteLLM-only; requires a cloud embedding provider and API key. Use when you don't want the local-embedding deps (~1 GB of torch + transformers).
 
 Next, set up your [coding agent integration](#coding-agent-integration) — or jump to [Manual CLI Usage](#manual-cli-usage) if you prefer direct control.
 
@@ -314,8 +321,7 @@ Pass configuration to `docker run` with `-e`:
 # Exclude build artefacts (Scala/SBT example)
 -e COCOINDEX_CODE_EXCLUDE_PATTERNS='["**/target/**","**/.bloop/**","**/.metals/**"]'
 
-# Swap in a code-optimised embedding model
--e COCOINDEX_CODE_EMBEDDING_MODEL=voyage/voyage-code-3
+# Set an API key
 -e VOYAGE_API_KEY=your-key
 ```
 
@@ -330,7 +336,7 @@ docker build -t cocoindex-code:local -f docker/Dockerfile .
 - **Ultra Performant**: ⚡ Built on top of ultra performant [Rust indexing engine](https://github.com/cocoindex-io/cocoindex). Only re-indexes changed files for fast updates.
 - **Multi-Language Support**: Python, JavaScript/TypeScript, Rust, Go, Java, C/C++, C#, SQL, Shell, and more.
 - **Embedded**: Portable and just works, no database setup required!
-- **Flexible Embeddings**: Local SentenceTransformers by default (free!) or 100+ cloud providers via LiteLLM.
+- **Flexible Embeddings**: Local SentenceTransformers via the `[default]` extra (free, no API key!) or 100+ cloud providers via LiteLLM.
 
 ## Configuration
 
@@ -343,7 +349,7 @@ Shared across all projects. Controls the embedding model and environment variabl
 ```yaml
 embedding:
   provider: sentence-transformers                    # or "litellm"
-  model: sentence-transformers/all-MiniLM-L6-v2
+  model: Snowflake/snowflake-arctic-embed-xs
   device: mps                                        # optional: cpu, cuda, mps (auto-detected if omitted)
   min_interval_ms: 300                               # optional: pace LiteLLM embedding requests to reduce 429s; defaults to 5 for LiteLLM
 
@@ -415,7 +421,7 @@ See [`src/cocoindex_code/chunking.py`](./src/cocoindex_code/chunking.py) for the
 
 ## Embedding Models
 
-By default, a local SentenceTransformers model ([sentence-transformers/all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2)) is used — no API key required. To use a different model, edit `~/.cocoindex_code/global_settings.yml`.
+With the `[default]` extra installed, `ccc init` defaults to a local SentenceTransformers model ([Snowflake/snowflake-arctic-embed-xs](https://huggingface.co/Snowflake/snowflake-arctic-embed-xs)) — no API key required. To use a different model, edit `~/.cocoindex_code/global_settings.yml`.
 
 > The `envs` entries below are only needed if the key isn't already in your shell environment — the daemon inherits your environment automatically.
 

{cocoindex_code-0.2.22 → cocoindex_code-0.2.23}/README.md

@@ -46,16 +46,18 @@ A lightweight, effective **(AST-based)** semantic code search tool for your code
 
 Using [pipx](https://pipx.pypa.io/stable/installation/):
 ```bash
-pipx install cocoindex-code       # first install
-pipx upgrade cocoindex-code       # upgrade
+pipx install 'cocoindex-code[default]'       # batteries included (local embeddings)
+pipx upgrade cocoindex-code                  # upgrade
 ```
 
 Using [uv](https://docs.astral.sh/uv/getting-started/installation/):
 ```bash
-uv tool install --upgrade cocoindex-code --prerelease explicit --with "cocoindex>=1.0.0a24"
+uv tool install --upgrade 'cocoindex-code[default]' --prerelease explicit --with "cocoindex>=1.0.0a24"
 ```
 
-The default embedding model runs locally ([sentence-transformers/all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2)) — no API key required, completely free.
+Two install styles:
+- `cocoindex-code[default]` — batteries-included. Pulls in `sentence-transformers` so local embeddings (no API key required) work out of the box. The `ccc init` interactive prompt defaults to [Snowflake/snowflake-arctic-embed-xs](https://huggingface.co/Snowflake/snowflake-arctic-embed-xs).
+- `cocoindex-code` — slim. LiteLLM-only; requires a cloud embedding provider and API key. Use when you don't want the local-embedding deps (~1 GB of torch + transformers).
 
 Next, set up your [coding agent integration](#coding-agent-integration) — or jump to [Manual CLI Usage](#manual-cli-usage) if you prefer direct control.
 
@@ -275,8 +277,7 @@ Pass configuration to `docker run` with `-e`:
 # Exclude build artefacts (Scala/SBT example)
 -e COCOINDEX_CODE_EXCLUDE_PATTERNS='["**/target/**","**/.bloop/**","**/.metals/**"]'
 
-# Swap in a code-optimised embedding model
--e COCOINDEX_CODE_EMBEDDING_MODEL=voyage/voyage-code-3
+# Set an API key
 -e VOYAGE_API_KEY=your-key
 ```
 
@@ -291,7 +292,7 @@ docker build -t cocoindex-code:local -f docker/Dockerfile .
 - **Ultra Performant**: ⚡ Built on top of ultra performant [Rust indexing engine](https://github.com/cocoindex-io/cocoindex). Only re-indexes changed files for fast updates.
 - **Multi-Language Support**: Python, JavaScript/TypeScript, Rust, Go, Java, C/C++, C#, SQL, Shell, and more.
 - **Embedded**: Portable and just works, no database setup required!
-- **Flexible Embeddings**: Local SentenceTransformers by default (free!) or 100+ cloud providers via LiteLLM.
+- **Flexible Embeddings**: Local SentenceTransformers via the `[default]` extra (free, no API key!) or 100+ cloud providers via LiteLLM.
 
 ## Configuration
 
@@ -304,7 +305,7 @@ Shared across all projects. Controls the embedding model and environment variabl
 ```yaml
 embedding:
   provider: sentence-transformers                    # or "litellm"
-  model: sentence-transformers/all-MiniLM-L6-v2
+  model: Snowflake/snowflake-arctic-embed-xs
   device: mps                                        # optional: cpu, cuda, mps (auto-detected if omitted)
   min_interval_ms: 300                               # optional: pace LiteLLM embedding requests to reduce 429s; defaults to 5 for LiteLLM
 
@@ -376,7 +377,7 @@ See [`src/cocoindex_code/chunking.py`](./src/cocoindex_code/chunking.py) for the
 
 ## Embedding Models
 
-By default, a local SentenceTransformers model ([sentence-transformers/all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2)) is used — no API key required. To use a different model, edit `~/.cocoindex_code/global_settings.yml`.
+With the `[default]` extra installed, `ccc init` defaults to a local SentenceTransformers model ([Snowflake/snowflake-arctic-embed-xs](https://huggingface.co/Snowflake/snowflake-arctic-embed-xs)) — no API key required. To use a different model, edit `~/.cocoindex_code/global_settings.yml`.
 
 > The `envs` entries below are only needed if the key isn't already in your shell environment — the daemon inherits your environment automatically.
 

{cocoindex_code-0.2.22 → cocoindex_code-0.2.23}/pyproject.toml

@@ -24,7 +24,6 @@ classifiers = [
 dependencies = [
     "mcp>=1.0.0",
     "cocoindex[litellm]==1.0.0a43",
-    "sentence-transformers>=2.2.0",
     "sqlite-vec>=0.1.0",
     "pydantic>=2.0.0",
     "numpy>=1.24.0",
@@ -33,9 +32,16 @@ dependencies = [
     "msgspec>=0.19.0",
     "pathspec>=0.12.1",
     "pyyaml>=6.0",
+    "questionary>=2.0.0",
 ]
 
 [project.optional-dependencies]
+embeddings-local = [
+    "cocoindex[sentence-transformers]==1.0.0a43",
+]
+default = [
+    "cocoindex[sentence-transformers]==1.0.0a43",
+]
 dev = [
     "pytest>=7.0.0",
     "pytest-asyncio>=0.21.0",
@@ -43,6 +49,7 @@ dev = [
     "ruff>=0.1.0",
     "mypy>=1.0.0",
     "prek>=0.1.0",
+    "cocoindex[sentence-transformers]==1.0.0a43",
 ]
 
 [project.scripts]
@@ -76,6 +83,7 @@ dev = [
     "mypy>=1.0.0",
     "prek>=0.1.0",
     "types-pyyaml>=6.0.12.20250915",
+    "cocoindex[sentence-transformers]==1.0.0a43",
 ]
 
 [tool.uv]

{cocoindex_code-0.2.22 → cocoindex_code-0.2.23}/src/cocoindex_code/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.22'
-__version_tuple__ = version_tuple = (0, 2, 22)
+__version__ = version = '0.2.23'
+__version_tuple__ = version_tuple = (0, 2, 23)
 
 __commit_id__ = commit_id = None

{cocoindex_code-0.2.22 → cocoindex_code-0.2.23}/src/cocoindex_code/cli.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import functools
+import sys
 from collections.abc import Callable
 from pathlib import Path
 from typing import TypeVar
@@ -12,15 +13,16 @@ import typer as _typer
 from .client import DaemonStartError
 from .protocol import DoctorCheckResult, IndexingProgress, ProjectStatusResponse, SearchResponse
 from .settings import (
+    DEFAULT_ST_MODEL,
+    EmbeddingSettings,
     cocoindex_db_path,
     default_project_settings,
-    default_user_settings,
     find_parent_with_marker,
     find_project_root,
     project_settings_path,
     resolve_db_dir,
+    save_initial_user_settings,
     save_project_settings,
-    save_user_settings,
     target_sqlite_db_path,
     user_settings_path,
 )
@@ -282,19 +284,173 @@ def remove_from_gitignore(project_root: Path) -> None:
 # ---------------------------------------------------------------------------
 
 
+_LITELLM_MODELS_URL = "https://docs.litellm.ai/docs/embedding/supported_embedding"
+
+
+def _resolve_embedding_choice(
+    litellm_model_flag: str | None,
+    st_installed: bool,
+    tty: bool,
+) -> EmbeddingSettings:
+    """Resolve the embedding settings per the init control-flow diagram."""
+    if litellm_model_flag is not None:
+        return EmbeddingSettings(provider="litellm", model=litellm_model_flag)
+
+    if not tty:
+        if st_installed:
+            return EmbeddingSettings(provider="sentence-transformers", model=DEFAULT_ST_MODEL)
+        _typer.echo(
+            "Error: sentence-transformers is not installed and stdin is not a TTY.\n"
+            "Either install the extra (`pip install cocoindex-code[embeddings-local]`)\n"
+            "or pass `--litellm-model MODEL` to select a LiteLLM model.",
+            err=True,
+        )
+        raise _typer.Exit(code=1)
+
+    # Interactive
+    import questionary
+
+    if st_installed:
+        provider = questionary.select(
+            "Embedding provider",
+            choices=[
+                questionary.Choice(
+                    title="sentence-transformers (local, free)",
+                    value="sentence-transformers",
+                ),
+                questionary.Choice(
+                    title="litellm (cloud, 100+ providers)",
+                    value="litellm",
+                ),
+            ],
+        ).ask()
+    else:
+        _typer.echo(
+            "sentence-transformers is not installed — only `litellm` is available.\n"
+            "To enable local embeddings, install `cocoindex-code[embeddings-local]`."
+        )
+        provider = "litellm"
+
+    if provider is None:  # user cancelled (Ctrl-C / Esc)
+        raise _typer.Exit(code=1)
+
+    if provider == "sentence-transformers":
+        model = questionary.text("Model name", default=DEFAULT_ST_MODEL).ask()
+    elif provider == "litellm":
+        _typer.echo(f"See supported LiteLLM embedding models: {_LITELLM_MODELS_URL}")
+        model = questionary.text("Model name").ask()
+    else:
+        _typer.echo(f"Error: unknown provider {provider!r}", err=True)
+        raise _typer.Exit(code=1)
+
+    if not model:  # None (cancelled) or empty string
+        raise _typer.Exit(code=1)
+
+    return EmbeddingSettings(provider=provider, model=model.strip())
+
+
+def _ok_fail_tag(ok: bool) -> str:
+    """Return a colored `[OK]` or `[FAIL]` tag string."""
+    import click as _click
+
+    if ok:
+        return _click.style("[OK]", fg="green", bold=True)
+    return _click.style("[FAIL]", fg="red", bold=True)
+
+
+def _run_init_model_check(settings_path: Path) -> None:
+    """Ask the daemon to test the embedding model; print results and a hint on failure.
+
+    Drives the check via `DoctorRequest(project_root=None)`. The daemon loads
+    the model once and stays running, so the user's next `ccc index` starts
+    warm. Both DaemonStartError and generic exceptions are rendered as a
+    synthetic failed DoctorCheckResult — uniform failure-output shape.
+    """
+    from rich.console import Console as _Console
+    from rich.live import Live as _Live
+    from rich.spinner import Spinner as _Spinner
+
+    from . import client as _client
+
+    err_console = _Console(stderr=True)
+    results: list[DoctorCheckResult] = []
+    try:
+        with _Live(
+            _Spinner("dots", "Testing embedding model..."),
+            console=err_console,
+            transient=True,
+        ):
+            results = _client.doctor(project_root=None)
+    except Exception as e:
+        results = [
+            DoctorCheckResult(
+                name="Model Check",
+                ok=False,
+                details=[],
+                errors=[f"{type(e).__name__}: {e}"],
+            )
+        ]
+
+    failed = False
+    for r in results:
+        if r.name == "done":
+            continue
+        _print_doctor_result(r)
+        if not r.ok:
+            failed = True
+
+    if failed:
+        _typer.echo(
+            f"You can edit {settings_path} to change the model or add API keys\n"
+            "under `envs:`. Then run `ccc doctor` to verify.",
+            err=True,
+        )
+
+
+def _setup_user_settings_interactive(litellm_model_flag: str | None) -> None:
+    """Interactive global-settings setup — only runs when settings are missing."""
+    from .shared import is_sentence_transformers_installed
+
+    embedding = _resolve_embedding_choice(
+        litellm_model_flag=litellm_model_flag,
+        st_installed=is_sentence_transformers_installed(),
+        tty=sys.stdin.isatty(),
+    )
+
+    path = save_initial_user_settings(embedding)
+    _typer.echo()
+    _typer.echo(f"Created user settings: {path}")
+
+    _typer.echo()
+    _typer.echo(f"Testing embedding model: {embedding.provider} / {embedding.model}")
+    _run_init_model_check(path)
+    _typer.echo()
+
+
 @app.command()
 def init(
+    litellm_model: str | None = _typer.Option(
+        None,
+        "--litellm-model",
+        help="Use the given LiteLLM model and skip provider/model prompts.",
+    ),
     force: bool = _typer.Option(False, "-f", "--force", help="Skip parent directory warning"),
 ) -> None:
     """Initialize a project for cocoindex-code."""
     cwd = Path.cwd().resolve()
     settings_file = project_settings_path(cwd)
 
-    # Always ensure user settings exist
     user_path = user_settings_path()
-    if not user_path.is_file():
-        save_user_settings(default_user_settings())
-        _typer.echo(f"Created user settings: {user_path}")
+    if user_path.is_file():
+        if litellm_model is not None:
+            _typer.echo(
+                f"Error: global settings already exist at {user_path}.\n"
+                "Edit that file or remove it before passing `--litellm-model`.",
+                err=True,
+            )
+            raise _typer.Exit(code=1)
+    else:
+        _setup_user_settings_interactive(litellm_model)
 
     # Check if already initialized
     if settings_file.is_file():
@@ -489,10 +645,7 @@ def _print_doctor_result(result: DoctorCheckResult) -> None:
 
     if result.name == "done":
         return
-    if result.ok:
-        tag = _click.style("[OK]", fg="green", bold=True)
-    else:
-        tag = _click.style("[FAIL]", fg="red", bold=True)
+    tag = _ok_fail_tag(result.ok)
     _typer.echo(f"\n  {tag} {result.name}")
     for line in result.details:
         _typer.echo(f"    {line}")

{cocoindex_code-0.2.22 → cocoindex_code-0.2.23}/src/cocoindex_code/daemon.py

@@ -61,7 +61,7 @@ from .settings import (
     load_user_settings,
     target_sqlite_db_path,
 )
-from .shared import Embedder, create_embedder
+from .shared import Embedder, check_embedding, create_embedder
 
 logger = logging.getLogger(__name__)
 
@@ -262,22 +262,20 @@ async def _handle_doctor(
 
 async def _check_model(embedder: Embedder) -> DoctorCheckResult:
     """Test the embedding model by embedding a short string."""
-    try:
-        vec = await embedder.embed("hello world")
-        dim = len(vec)
+    result = await check_embedding(embedder)
+    if result.error is None:
         return DoctorCheckResult(
             name="Model Check",
             ok=True,
-            details=[f"Embedding dimension: {dim}"],
+            details=[f"Embedding dimension: {result.dim}"],
             errors=[],
         )
-    except Exception as e:
-        return DoctorCheckResult(
-            name="Model Check",
-            ok=False,
-            details=[],
-            errors=[str(e)],
-        )
+    return DoctorCheckResult(
+        name="Model Check",
+        ok=False,
+        details=[],
+        errors=[result.error],
+    )
 
 
 async def _check_file_walk(project_root_str: str) -> DoctorCheckResult:

{cocoindex_code-0.2.22 → cocoindex_code-0.2.23}/src/cocoindex_code/settings.py

@@ -126,11 +126,14 @@ class ProjectSettings:
 # ---------------------------------------------------------------------------
 
 
+DEFAULT_ST_MODEL = "Snowflake/snowflake-arctic-embed-xs"
+
+
 def default_user_settings() -> UserSettings:
     return UserSettings(
         embedding=EmbeddingSettings(
             provider="sentence-transformers",
-            model="sentence-transformers/all-MiniLM-L6-v2",
+            model=DEFAULT_ST_MODEL,
         )
     )
 
@@ -344,17 +347,20 @@ def load_gitignore_spec(project_root: Path) -> GitIgnoreSpec | None:
 # ---------------------------------------------------------------------------
 
 
-def _user_settings_to_dict(settings: UserSettings) -> dict[str, Any]:
-    d: dict[str, Any] = {}
-    emb: dict[str, Any] = {
-        "provider": settings.embedding.provider,
-        "model": settings.embedding.model,
+def _embedding_settings_to_dict(embedding: EmbeddingSettings) -> dict[str, Any]:
+    d: dict[str, Any] = {
+        "provider": embedding.provider,
+        "model": embedding.model,
     }
-    if settings.embedding.device is not None:
-        emb["device"] = settings.embedding.device
-    if settings.embedding.min_interval_ms is not None:
-        emb["min_interval_ms"] = settings.embedding.min_interval_ms
-    d["embedding"] = emb
+    if embedding.device is not None:
+        d["device"] = embedding.device
+    if embedding.min_interval_ms is not None:
+        d["min_interval_ms"] = embedding.min_interval_ms
+    return d
+
+
+def _user_settings_to_dict(settings: UserSettings) -> dict[str, Any]:
+    d: dict[str, Any] = {"embedding": _embedding_settings_to_dict(settings.embedding)}
     if settings.envs:
         d["envs"] = dict(settings.envs)
     return d
@@ -436,6 +442,46 @@ def save_user_settings(settings: UserSettings) -> Path:
     return path
 
 
+_INITIAL_HEADER = (
+    "# CocoIndex Code — global settings.\n"
+    "# After editing this file, run `ccc doctor` to verify your configuration.\n"
+    "\n"
+)
+
+_INITIAL_ENVS_COMMENT = (
+    "\n"
+    "# Environment variables to inject into the daemon running in the background.\n"
+    "# Uncomment and fill in keys for the LiteLLM providers you plan to use.\n"
+    "#\n"
+    "# envs:\n"
+    "#   OPENAI_API_KEY: ...\n"
+    "#   GEMINI_API_KEY: ...\n"
+    "#   ANTHROPIC_API_KEY: ...\n"
+    "#   VOYAGE_API_KEY: ...\n"
+)
+
+
+def save_initial_user_settings(embedding: EmbeddingSettings) -> Path:
+    """Write the initial global_settings.yml with comment hints and env examples.
+
+    Only used by `ccc init` on first-time setup. Emits only the `embedding:`
+    block from the input; the `envs:` section is a commented-out template.
+    Subsequent programmatic writes use `save_user_settings` and do not
+    preserve comments.
+    """
+    emb_block = _yaml.safe_dump(
+        {"embedding": _embedding_settings_to_dict(embedding)},
+        default_flow_style=False,
+        sort_keys=False,
+    )
+    content = _INITIAL_HEADER + emb_block + _INITIAL_ENVS_COMMENT
+
+    path = user_settings_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content)
+    return path
+
+
 def load_project_settings(project_root: Path) -> ProjectSettings:
     """Read ``$PROJECT_ROOT/.cocoindex_code/settings.yml``.
 

{cocoindex_code-0.2.22 → cocoindex_code-0.2.23}/src/cocoindex_code/shared.py

@@ -2,10 +2,11 @@
 
 from __future__ import annotations
 
+import importlib.util
 import logging
 import pathlib
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Annotated, Union
+from typing import TYPE_CHECKING, Annotated, NamedTuple, Union
 
 import cocoindex as coco
 import numpy as np
@@ -41,6 +42,41 @@ embedder: Embedder | None = None
 query_prompt_name: str | None = None
 
 
+def is_sentence_transformers_installed() -> bool:
+    """Return True if the `sentence_transformers` package can be imported.
+
+    Uses `find_spec` rather than `import` to avoid triggering the slow,
+    torch-loading import as a side effect of the check.
+    """
+    return importlib.util.find_spec("sentence_transformers") is not None
+
+
+class EmbeddingCheckResult(NamedTuple):
+    """Outcome of a single embed-test call. See `check_embedding`.
+
+    Exactly one of ``dim`` / ``error`` is set: ``error is None`` means success.
+    """
+
+    dim: int | None
+    error: str | None
+
+
+async def check_embedding(embedder: Embedder) -> EmbeddingCheckResult:
+    """Run a single embed call against *embedder* and report dim or error.
+
+    Never raises. Used by both the daemon's doctor path (`daemon._check_model`)
+    and the CLI's init flow (`cli._test_embedding_model`).
+    """
+    try:
+        vec = await embedder.embed("hello world")
+        return EmbeddingCheckResult(dim=len(vec), error=None)
+    except Exception as e:
+        msg = f"{type(e).__name__}: {e}".splitlines()[0]
+        if len(msg) > 500:
+            msg = msg[:500] + "…"
+        return EmbeddingCheckResult(dim=None, error=msg)
+
+
 def create_embedder(settings: EmbeddingSettings) -> Embedder:
     """Create and return an embedder instance based on settings.