fix(init): clarify providers, add interactive recovery, fix retry crash (#181) (#184)

Addresses the `ccc init` issues reported in #181:

- Relabel embedding providers so local Ollama is clearly under `litellm`
  ("litellm (100+ providers — cloud APIs & local Ollama)") and
  sentence-transformers is marked as built-in HuggingFace models.
- Reject `ollama/` models inline at the sentence-transformers prompt, before
  anything is written or tested, instead of crashing later.
- On a failed init model check, loop with an interactive "try a different
  model / keep & finish" choice, pre-filling the previous provider and model
  on retry, and print a prominent "Next steps" recovery block.
- Add `ccc doctor -v` to show full tracebacks; by default show the one-line
  error plus a hint to rerun with `-v`.
- Fix the retry crash where a rewritten global_settings.yml made the already
  -ensured daemon report a bogus "version mismatch": restart the daemon on a
  stale-settings handshake even after it was ensured, while still failing fast
  on a genuine mid-session version mismatch. Make DaemonVersionError's message
  reflect the actual cause.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: georgeh0

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":
@@ -704,13 +781,26 @@ def _print_doctor_result(result: DoctorCheckResult) -> None:
     for err in result.errors:
         _typer.echo(_click.style(f"    ERROR: {err}", fg="red"), err=True)
     if result.traceback:
-        for line in result.traceback.splitlines():
-            _typer.echo(_click.style(f"    {line}", fg="bright_black"), err=True)
+        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 (
@@ -720,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()
@@ -773,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}")
@@ -804,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}")

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):