cocoindex-code 0.2.33__tar.gz → 0.2.35__tar.gz

{cocoindex_code-0.2.33 → cocoindex_code-0.2.35}/.gitignore

@@ -33,6 +33,9 @@ ENV/
 *.swp
 *.swo
 
+# Claude Code local config and state
+/.claude/
+
 # Testing
 .tox/
 .coverage

{cocoindex_code-0.2.33 → cocoindex_code-0.2.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cocoindex-code
-Version: 0.2.33
+Version: 0.2.35
 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
@@ -17,7 +17,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
-Requires-Dist: cocoindex[litellm]<1.1.0,>=1.0.0
+Requires-Dist: cocoindex[litellm]<1.1.0,>=1.0.6
 Requires-Dist: einops>=0.8.2
 Requires-Dist: mcp>=1.0.0
 Requires-Dist: msgspec>=0.19.0
@@ -29,7 +29,7 @@ Requires-Dist: questionary>=2.0.0
 Requires-Dist: sqlite-vec>=0.1.0
 Requires-Dist: typer>=0.9.0
 Provides-Extra: dev
-Requires-Dist: cocoindex[sentence-transformers]<1.1.0,>=1.0.0; extra == 'dev'
+Requires-Dist: cocoindex[sentence-transformers]<1.1.0,>=1.0.6; 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'
@@ -37,9 +37,9 @@ 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.1.0,>=1.0.0; extra == 'embeddings-local'
+Requires-Dist: cocoindex[sentence-transformers]<1.1.0,>=1.0.6; extra == 'embeddings-local'
 Provides-Extra: full
-Requires-Dist: cocoindex[sentence-transformers]<1.1.0,>=1.0.0; extra == 'full'
+Requires-Dist: cocoindex[sentence-transformers]<1.1.0,>=1.0.6; extra == 'full'
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -568,6 +568,23 @@ envs:
 
 </details>
 
+<details>
+<summary>OpenAI-compatible (custom endpoint)</summary>
+
+Many providers (vLLM, LM Studio, LocalAI, Together, Fireworks, DeepInfra, …) expose an OpenAI-compatible embedding API. Use the `openai/` prefix and point `OPENAI_BASE_URL` at your endpoint:
+
+```yaml
+embedding:
+  model: openai/your-model-name
+envs:
+  OPENAI_BASE_URL: https://your-endpoint/v1
+  OPENAI_API_KEY: your-api-key
+```
+
+Don't append `/embeddings` to the base URL — LiteLLM handles that.
+
+</details>
+
 <details>
 <summary>Azure OpenAI</summary>
 
@@ -656,7 +673,7 @@ envs:
 
 </details>
 
-Any [LiteLLM-supported model](https://docs.litellm.ai/docs/embedding/supported_embedding) works. When using a LiteLLM model, set `provider: litellm` (or omit `provider` — LiteLLM is the default for non-`sentence-transformers` models).
+Any [LiteLLM-supported model](https://docs.litellm.ai/docs/embedding/supported_embedding) works. When using a LiteLLM model, set `provider: litellm` (or omit `provider` — LiteLLM is the default for non-`sentence-transformers` models). For the full list of env vars each provider reads (API keys, base URLs, regions, …), see LiteLLM's [Setting API Keys](https://docs.litellm.ai/docs/set_keys).
 
 ### Local SentenceTransformers Models
 
@@ -776,6 +793,18 @@ If you previously configured `cocoindex-code` via environment variables, the `co
 | `COCOINDEX_CODE_EXCLUDED_PATTERNS` | `exclude_patterns` in project `settings.yml` |
 | `COCOINDEX_CODE_EXTRA_EXTENSIONS` | `include_patterns` + `language_overrides` in project `settings.yml` |
 
+## Telemetry
+
+`cocoindex-code` sends anonymous usage telemetry through CocoIndex so we can see how the tool is used in aggregate and prioritize improvements. The events identify themselves as `application: cocoindex-code`.
+
+We **do not** collect your source code, file paths, queries, search results, embeddings, settings, or any other content from your codebase or environment.
+
+To opt out, set:
+
+```bash
+export COCOINDEX_DISABLE_USAGE_TRACKING=1
+```
+
 ## Large codebase / Enterprise
 [CocoIndex](https://github.com/cocoindex-io/cocoindex) is an ultra efficient indexing engine that also works on large codebases at scale for enterprises. In enterprise scenarios it is a lot more efficient to share indexes with teammates when there are large or many repos. We also have advanced features like branch dedupe etc designed for enterprise users.
 

{cocoindex_code-0.2.33 → cocoindex_code-0.2.35}/README.md

@@ -524,6 +524,23 @@ envs:
 
 </details>
 
+<details>
+<summary>OpenAI-compatible (custom endpoint)</summary>
+
+Many providers (vLLM, LM Studio, LocalAI, Together, Fireworks, DeepInfra, …) expose an OpenAI-compatible embedding API. Use the `openai/` prefix and point `OPENAI_BASE_URL` at your endpoint:
+
+```yaml
+embedding:
+  model: openai/your-model-name
+envs:
+  OPENAI_BASE_URL: https://your-endpoint/v1
+  OPENAI_API_KEY: your-api-key
+```
+
+Don't append `/embeddings` to the base URL — LiteLLM handles that.
+
+</details>
+
 <details>
 <summary>Azure OpenAI</summary>
 
@@ -612,7 +629,7 @@ envs:
 
 </details>
 
-Any [LiteLLM-supported model](https://docs.litellm.ai/docs/embedding/supported_embedding) works. When using a LiteLLM model, set `provider: litellm` (or omit `provider` — LiteLLM is the default for non-`sentence-transformers` models).
+Any [LiteLLM-supported model](https://docs.litellm.ai/docs/embedding/supported_embedding) works. When using a LiteLLM model, set `provider: litellm` (or omit `provider` — LiteLLM is the default for non-`sentence-transformers` models). For the full list of env vars each provider reads (API keys, base URLs, regions, …), see LiteLLM's [Setting API Keys](https://docs.litellm.ai/docs/set_keys).
 
 ### Local SentenceTransformers Models
 
@@ -732,6 +749,18 @@ If you previously configured `cocoindex-code` via environment variables, the `co
 | `COCOINDEX_CODE_EXCLUDED_PATTERNS` | `exclude_patterns` in project `settings.yml` |
 | `COCOINDEX_CODE_EXTRA_EXTENSIONS` | `include_patterns` + `language_overrides` in project `settings.yml` |
 
+## Telemetry
+
+`cocoindex-code` sends anonymous usage telemetry through CocoIndex so we can see how the tool is used in aggregate and prioritize improvements. The events identify themselves as `application: cocoindex-code`.
+
+We **do not** collect your source code, file paths, queries, search results, embeddings, settings, or any other content from your codebase or environment.
+
+To opt out, set:
+
+```bash
+export COCOINDEX_DISABLE_USAGE_TRACKING=1
+```
+
 ## Large codebase / Enterprise
 [CocoIndex](https://github.com/cocoindex-io/cocoindex) is an ultra efficient indexing engine that also works on large codebases at scale for enterprises. In enterprise scenarios it is a lot more efficient to share indexes with teammates when there are large or many repos. We also have advanced features like branch dedupe etc designed for enterprise users.
 

{cocoindex_code-0.2.33 → cocoindex_code-0.2.35}/pyproject.toml

@@ -23,7 +23,7 @@ classifiers = [
 
 dependencies = [
     "mcp>=1.0.0",
-    "cocoindex[litellm]>=1.0.0,<1.1.0",
+    "cocoindex[litellm]>=1.0.6,<1.1.0",
     "sqlite-vec>=0.1.0",
     "pydantic>=2.0.0",
     "numpy>=1.24.0",
@@ -39,7 +39,7 @@ dependencies = [
 # `embeddings-local` is the primary feature extra: it pulls in
 # `sentence-transformers` (via cocoindex) so local embeddings work without
 # an API key.
-embeddings-local = ["cocoindex[sentence-transformers]>=1.0.0,<1.1.0"]
+embeddings-local = ["cocoindex[sentence-transformers]>=1.0.6,<1.1.0"]
 # `full` is the umbrella "batteries-included" alias. Today it's just
 # `embeddings-local`, but we expect to bundle more optional niceties under
 # it over time — users who want everything can keep using `[full]` and pick
@@ -47,7 +47,7 @@ embeddings-local = ["cocoindex[sentence-transformers]>=1.0.0,<1.1.0"]
 # `:full` image variant for consistency across install paths. Contents are
 # inlined rather than self-referencing `cocoindex-code[embeddings-local]`
 # to avoid resolver edge cases with older pip.
-full = ["cocoindex[sentence-transformers]>=1.0.0,<1.1.0"]
+full = ["cocoindex[sentence-transformers]>=1.0.6,<1.1.0"]
 dev = [
     "pytest>=7.0.0",
     "pytest-asyncio>=0.21.0",
@@ -55,7 +55,7 @@ dev = [
     "ruff>=0.1.0",
     "mypy>=1.0.0",
     "prek>=0.1.0",
-    "cocoindex[sentence-transformers]>=1.0.0,<1.1.0",
+    "cocoindex[sentence-transformers]>=1.0.6,<1.1.0",
 ]
 
 [project.scripts]
@@ -89,7 +89,7 @@ dev = [
     "mypy>=1.0.0",
     "prek>=0.1.0",
     "types-pyyaml>=6.0.12.20250915",
-    "cocoindex[sentence-transformers]>=1.0.3,<1.1.0",
+    "cocoindex[sentence-transformers]>=1.0.7,<1.1.0",
 ]
 
 [tool.ruff]

{cocoindex_code-0.2.33 → cocoindex_code-0.2.35}/src/cocoindex_code/__init__.py

@@ -3,8 +3,14 @@
 from __future__ import annotations
 
 import logging
+import os
 from typing import TYPE_CHECKING, Any
 
+# Identify this application in cocoindex's telemetry payloads. Must be set
+# before any `import cocoindex` runs (the value is read once at telemetry
+# init time). See cocoindex-io/cocoindex#1992.
+os.environ.setdefault("COCOINDEX_APPLICATION_FOR_TRACKING", "cocoindex-code")
+
 logging.basicConfig(level=logging.WARNING)
 
 from ._version import __version__  # noqa: E402

{cocoindex_code-0.2.33 → cocoindex_code-0.2.35}/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.33'
-__version_tuple__ = version_tuple = (0, 2, 33)
+__version__ = version = '0.2.35'
+__version_tuple__ = version_tuple = (0, 2, 35)
 
 __commit_id__ = commit_id = None

{cocoindex_code-0.2.33 → cocoindex_code-0.2.35}/src/cocoindex_code/cli.py

@@ -321,12 +321,35 @@ def remove_from_gitignore(project_root: Path) -> None:
 _LITELLM_MODELS_URL = "https://docs.litellm.ai/docs/embedding/supported_embedding"
 
 
+def _st_model_rejection_reason(model: str) -> str | None:
+    """Why ``model`` can't be a sentence-transformers model, or None if it's fine.
+
+    sentence-transformers loads HuggingFace model ids. An ``ollama/`` prefix is a
+    LiteLLM/Ollama route that ST tries (and fails) to resolve as a HuggingFace
+    repo — the user wants the litellm provider instead (issue #181). Real
+    HuggingFace ids that contain an ``org/`` slash (``Snowflake/...``,
+    ``openai/...``) are left alone.
+    """
+    if model.strip().lower().startswith("ollama/"):
+        return (
+            "ollama/… models run via litellm, not sentence-transformers — "
+            "go back and pick the litellm provider instead."
+        )
+    return None
+
+
 def _resolve_embedding_choice(
     litellm_model_flag: str | None,
     st_installed: bool,
     tty: bool,
+    previous: EmbeddingSettings | None = None,
 ) -> EmbeddingSettings:
-    """Resolve the embedding settings per the init control-flow diagram."""
+    """Resolve the embedding settings per the init control-flow diagram.
+
+    On a retry, ``previous`` holds the choice from the last attempt; its
+    provider and model become the prompt defaults so the user only edits
+    what was wrong instead of retyping everything.
+    """
     if litellm_model_flag is not None:
         return EmbeddingSettings(provider="litellm", model=litellm_model_flag)
 
@@ -349,14 +372,15 @@ def _resolve_embedding_choice(
             "Embedding provider",
             choices=[
                 questionary.Choice(
-                    title="sentence-transformers (local, free)",
+                    title="sentence-transformers (local, free — built-in HuggingFace models)",
                     value="sentence-transformers",
                 ),
                 questionary.Choice(
-                    title="litellm (cloud, 100+ providers)",
+                    title="litellm (100+ providers — cloud APIs & local Ollama)",
                     value="litellm",
                 ),
             ],
+            default=previous.provider if previous is not None else None,
         ).ask()
     else:
         _typer.echo(
@@ -369,10 +393,16 @@ def _resolve_embedding_choice(
         raise _typer.Exit(code=1)
 
     if provider == "sentence-transformers":
-        model = questionary.text("Model name", default=DEFAULT_ST_MODEL).ask()
+        default_model = previous.model if previous is not None else DEFAULT_ST_MODEL
+        model = questionary.text(
+            "Model name",
+            default=default_model,
+            validate=lambda m: _st_model_rejection_reason(m) or True,
+        ).ask()
     elif provider == "litellm":
         _typer.echo(f"See supported LiteLLM embedding models: {_LITELLM_MODELS_URL}")
-        model = questionary.text("Model name").ask()
+        default_model = previous.model if previous is not None else ""
+        model = questionary.text("Model name", default=default_model).ask()
     else:
         _typer.echo(f"Error: unknown provider {provider!r}", err=True)
         raise _typer.Exit(code=1)
@@ -392,13 +422,14 @@ def _ok_fail_tag(ok: bool) -> str:
     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.
+def _run_init_model_check() -> bool:
+    """Ask the daemon to test the embedding model; print results. Return True if all pass.
 
     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.
+    synthetic failed DoctorCheckResult — uniform failure-output shape. The
+    caller decides what to show on failure (retry prompt / next-steps block).
     """
     from rich.console import Console as _Console
     from rich.live import Live as _Live
@@ -426,55 +457,101 @@ def _run_init_model_check(settings_path: Path) -> None:
             )
         ]
 
-    failed = False
+    ok = True
     for r in results:
         if r.name == "done":
             continue
-        _print_doctor_result(r)
+        _print_doctor_result(r, verbose=False)
         if not r.ok:
-            failed = True
+            ok = False
+    return ok
 
-    if failed:
-        display_path = format_path_for_display(settings_path)
-        _typer.echo(
-            f"You can edit {display_path} to change the model or add API keys\n"
-            "under `envs:`. Then run `ccc doctor` to verify.",
-            err=True,
-        )
+
+def _print_init_next_steps(settings_path: Path) -> None:
+    """Prominent recovery block shown after a failed init model check."""
+    import click as _click
+
+    display_path = format_path_for_display(settings_path)
+    _typer.echo(err=True)
+    _typer.echo(_click.style("  Next steps", bold=True), err=True)
+    _typer.echo(_click.style(f"  {'─' * 38}", fg="bright_black"), err=True)
+    _typer.echo(
+        f"  1. Edit  {_click.style(display_path, fg='cyan', bold=True)}\n"
+        "     to change the model or add API keys under `envs:`.",
+        err=True,
+    )
+    _typer.echo("  2. Run  `ccc doctor`  to verify.", err=True)
+    _typer.echo()  # trailing blank before whatever init prints next
 
 
 def _setup_user_settings_interactive(litellm_model_flag: str | None) -> None:
-    """Interactive global-settings setup — only runs when settings are missing."""
+    """Interactive global-settings setup — only runs when settings are missing.
+
+    Loops until the configured model passes its check or the user chooses to
+    keep the current settings. On failure we offer a retry, but only when we
+    can actually re-prompt for a different model — i.e. interactive and not
+    pinned by ``--litellm-model``; otherwise we just print the next steps.
+    """
     from .embedder_defaults import lookup_defaults
     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(),
-    )
+    st_installed = is_sentence_transformers_installed()
+    interactive = sys.stdin.isatty()
+    previous: EmbeddingSettings | None = None
 
-    # Apply curated defaults if the model is in our table.
-    indexing_defaults, query_defaults = lookup_defaults(embedding.provider, embedding.model)
-    defaults_applied = indexing_defaults is not None or query_defaults is not None
-    if defaults_applied:
-        embedding.indexing_params = indexing_defaults or {}
-        embedding.query_params = query_defaults or {}
+    while True:
+        embedding = _resolve_embedding_choice(
+            litellm_model_flag=litellm_model_flag,
+            st_installed=st_installed,
+            tty=interactive,
+            previous=previous,
+        )
+        previous = embedding  # remembered as the defaults for a potential retry
 
-    path = save_initial_user_settings(embedding, defaults_applied=defaults_applied)
-    _typer.echo()
-    _typer.echo(f"Created user settings: {format_path_for_display(path)}")
+        # Apply curated defaults if the model is in our table.
+        indexing_defaults, query_defaults = lookup_defaults(embedding.provider, embedding.model)
+        defaults_applied = indexing_defaults is not None or query_defaults is not None
+        if defaults_applied:
+            embedding.indexing_params = indexing_defaults or {}
+            embedding.query_params = query_defaults or {}
 
-    if defaults_applied:
+        path = save_initial_user_settings(embedding, defaults_applied=defaults_applied)
         _typer.echo()
-        _typer.echo(f"Applied recommended defaults for {embedding.model}:")
-        _typer.echo(f"  indexing_params: {embedding.indexing_params}")
-        _typer.echo(f"  query_params:    {embedding.query_params}")
+        _typer.echo(f"Created user settings: {format_path_for_display(path)}")
 
-    _typer.echo()
-    _typer.echo(f"Testing embedding model: {embedding.provider} / {embedding.model}")
-    _run_init_model_check(path)
-    _typer.echo()
+        if defaults_applied:
+            _typer.echo()
+            _typer.echo(f"Applied recommended defaults for {embedding.model}:")
+            _typer.echo(f"  indexing_params: {embedding.indexing_params}")
+            _typer.echo(f"  query_params:    {embedding.query_params}")
+
+        _typer.echo()
+        _typer.echo(f"Testing embedding model: {embedding.provider} / {embedding.model}")
+        if _run_init_model_check():
+            _typer.echo()
+            return
+
+        # Model check failed. Retry only makes sense if we can re-prompt.
+        if interactive and litellm_model_flag is None:
+            import questionary
+
+            _typer.echo()  # separate the failure output from the prompt below
+            choice = questionary.select(
+                "The embedding model couldn't be loaded. What would you like to do?",
+                choices=[
+                    questionary.Choice(title="Try a different provider/model", value="retry"),
+                    questionary.Choice(
+                        title="Keep these settings and finish — I'll edit the file myself",
+                        value="keep",
+                    ),
+                ],
+            ).ask()
+            if choice == "retry":
+                continue
+            # "keep" or None (cancelled) falls through to the next-steps block.
+
+        _print_init_next_steps(path)
+        return
 
 
 @app.command()
@@ -692,7 +769,7 @@ def _print_error(msg: str) -> None:
     _typer.echo(_click.style(f"  ERROR: {msg}", fg="red"), err=True)
 
 
-def _print_doctor_result(result: DoctorCheckResult) -> None:
+def _print_doctor_result(result: DoctorCheckResult, *, verbose: bool = False) -> None:
     import click as _click
 
     if result.name == "done":
@@ -703,11 +780,27 @@ def _print_doctor_result(result: DoctorCheckResult) -> None:
         _typer.echo(f"    {line}")
     for err in result.errors:
         _typer.echo(_click.style(f"    ERROR: {err}", fg="red"), err=True)
+    if result.traceback:
+        if verbose:
+            for line in result.traceback.splitlines():
+                _typer.echo(_click.style(f"    {line}", fg="bright_black"), err=True)
+        else:
+            _typer.echo(
+                _click.style("    Run `ccc doctor -v` for the full traceback.", fg="bright_black"),
+                err=True,
+            )
 
 
 @app.command()
 @_catch_daemon_start_error
-def doctor() -> None:
+def doctor(
+    verbose: bool = _typer.Option(
+        False,
+        "-v",
+        "--verbose",
+        help="Show full exception tracebacks for failed checks.",
+    ),
+) -> None:
     """Check system health and report issues."""
     from . import client as _client
     from .settings import (
@@ -717,6 +810,9 @@ def doctor() -> None:
         load_user_settings as _load_user_settings,
     )
 
+    def _on_result(result: DoctorCheckResult) -> None:
+        _print_doctor_result(result, verbose=verbose)
+
     # --- 1. Global settings (local, no daemon needed) ---
     _print_section("Global Settings")
     settings_path = user_settings_path()
@@ -770,7 +866,7 @@ def doctor() -> None:
         try:
             _client.doctor(
                 project_root=None,
-                on_result=_print_doctor_result,
+                on_result=_on_result,
             )
         except Exception as e:
             _print_error(f"Model check failed: {e}")
@@ -801,7 +897,7 @@ def doctor() -> None:
         try:
             _client.doctor(
                 project_root=str(project_root),
-                on_result=_print_doctor_result,
+                on_result=_on_result,
             )
         except Exception as e:
             _print_error(f"Project checks failed: {e}")

{cocoindex_code-0.2.33 → cocoindex_code-0.2.35}/src/cocoindex_code/client.py

@@ -111,25 +111,33 @@ def _connect_and_handshake() -> Connection:
 
     Returns the open connection for the caller to send exactly one request.
 
-    On the first call, automatically starts or
-    restarts the daemon if needed.  Subsequent calls fail fast with
-    ``DaemonVersionError`` on mismatch (indicating the daemon was replaced
-    mid-session, e.g. after a tool upgrade).
+    Automatically starts or restarts the daemon when it is absent or running
+    with stale global settings (e.g. a ``ccc init`` retry rewrote
+    ``global_settings.yml`` after the daemon loaded it). A genuine *version*
+    mismatch after we have already reached a matching daemon means the binary
+    was replaced under us mid-session — that fails fast instead of looping on
+    restarts.
     """
     global _daemon_ensured  # noqa: PLW0603
 
-    if _daemon_ensured:
-        return _raw_connect_and_handshake()
-
-    # First connection — auto-start/restart as needed.
     try:
         conn = _raw_connect_and_handshake()
         _daemon_ensured = True
         return conn
-    except DaemonVersionError:
+    except DaemonVersionError as e:
+        # `resp.ok` is False only for a real version mismatch. Once we have
+        # ensured a matching daemon, a fresh version mismatch means the binary
+        # was swapped under us — fail fast. A settings-only restart request
+        # (resp.ok True, but the loaded settings mtime moved) is expected;
+        # restart the daemon below so it reloads them.
+        if _daemon_ensured and not e.resp.ok:
+            raise
         stop_daemon()
     except (ConnectionRefusedError, OSError):
-        pass
+        # No daemon answered. Normal on the first call (start one below); if we
+        # had already ensured one it vanished mid-session — surface that.
+        if _daemon_ensured:
+            raise
 
     if _is_daemon_supervised():
         # Supervisor is responsible for (re)starting the daemon — just wait
@@ -192,10 +200,16 @@ class DaemonVersionError(RuntimeError):
 
     def __init__(self, resp: HandshakeResponse) -> None:
         self.resp = resp
-        super().__init__(
-            f"Daemon version mismatch (daemon={resp.daemon_version}, "
-            f"client={__version__}). Please retry — the daemon may need a restart."
-        )
+        if not resp.ok:
+            message = (
+                f"Daemon version mismatch (daemon={resp.daemon_version}, "
+                f"client={__version__}). Please retry — the daemon may need a restart."
+            )
+        else:
+            message = (
+                "Daemon is running with stale global settings and needs a restart. Please retry."
+            )
+        super().__init__(message)
 
 
 class DaemonStartError(RuntimeError):
@@ -363,7 +377,10 @@ def doctor(
                 raise RuntimeError("Connection to daemon lost during doctor checks")
             resp = decode_response(data)
             if isinstance(resp, ErrorResponse):
-                raise RuntimeError(f"Daemon error: {resp.message}")
+                detail = f"Daemon error: {resp.message}"
+                if resp.traceback:
+                    detail += f"\n{resp.traceback}"
+                raise RuntimeError(detail)
             if isinstance(resp, DoctorResponse):
                 results.append(resp.result)
                 if on_result is not None:

{cocoindex_code-0.2.33 → cocoindex_code-0.2.35}/src/cocoindex_code/daemon.py

@@ -10,6 +10,7 @@ import signal
 import sys
 import threading
 import time
+import traceback
 from collections.abc import AsyncIterator, Callable
 from multiprocessing.connection import Connection, Listener
 from pathlib import Path
@@ -250,7 +251,11 @@ async def handle_connection(
                     conn.send_bytes(encode_response(resp))
             except Exception as exc:
                 logger.exception("Error during streaming response")
-                conn.send_bytes(encode_response(ErrorResponse(message=str(exc))))
+                conn.send_bytes(
+                    encode_response(
+                        ErrorResponse(message=str(exc), traceback=traceback.format_exc())
+                    )
+                )
         else:
             conn.send_bytes(encode_response(result))
     except (EOFError, OSError, asyncio.CancelledError):
@@ -359,6 +364,7 @@ async def _check_model(
         ok=False,
         details=[params_detail],
         errors=[result.error],
+        traceback=result.traceback,
     )
 
 

{cocoindex_code-0.2.33 → cocoindex_code-0.2.35}/src/cocoindex_code/protocol.py

@@ -154,6 +154,9 @@ class DoctorCheckResult(_msgspec.Struct):
     ok: bool
     details: list[str]
     errors: list[str]
+    # Full formatted traceback for a failed check, shown by `ccc doctor` to aid
+    # debugging of daemon-side exceptions (e.g. a failing model check).
+    traceback: str | None = None
 
 
 class DoctorResponse(_msgspec.Struct, tag="doctor"):
@@ -175,6 +178,9 @@ class DaemonEnvResponse(_msgspec.Struct, tag="daemon_env"):
 
 class ErrorResponse(_msgspec.Struct, tag="error"):
     message: str
+    # Full formatted traceback from the daemon, when the error originates from an
+    # unhandled exception. Surfaced by the CLI so daemon-side failures are debuggable.
+    traceback: str | None = None
 
 
 Response = (

{cocoindex_code-0.2.33 → cocoindex_code-0.2.35}/src/cocoindex_code/shared.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import importlib.util
 import logging
 import pathlib
+import traceback as _tb
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Annotated, Any, NamedTuple, Union
 
@@ -47,11 +48,14 @@ def is_sentence_transformers_installed() -> bool:
 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.
+    On success ``error is None`` and ``dim`` holds the embedding dimension. On
+    failure ``error`` holds a one-line summary and ``traceback`` the full
+    formatted traceback (for surfacing daemon-side stack traces in `ccc doctor`).
     """
 
     dim: int | None
     error: str | None
+    traceback: str | None = None
 
 
 async def check_embedding(
@@ -73,7 +77,7 @@ async def check_embedding(
         msg = " ".join(f"{type(e).__name__}: {e}".splitlines())
         if len(msg) > 500:
             msg = msg[:500] + "…"
-        return EmbeddingCheckResult(dim=None, error=msg)
+        return EmbeddingCheckResult(dim=None, error=msg, traceback=_tb.format_exc())
 
 
 def create_embedder(