cocoindex-code 0.2.28__tar.gz → 0.2.29__tar.gz

{cocoindex_code-0.2.28 → cocoindex_code-0.2.29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cocoindex-code
-Version: 0.2.28
+Version: 0.2.29
 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
@@ -96,7 +96,7 @@ pipx upgrade cocoindex-code                  # upgrade
 
 Using [uv](https://docs.astral.sh/uv/getting-started/installation/):
 ```bash
-uv tool install --upgrade 'cocoindex-code[full]' --prerelease explicit --with "cocoindex>=1.0.0a24"
+uv tool install --upgrade 'cocoindex-code[full]'
 ```
 
 Two install styles — they mirror the Docker image variants of the same names:
@@ -437,6 +437,14 @@ embedding:
   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
 
+  # Optional extra kwargs passed to the embedder, separately for indexing vs query.
+  # `ccc init` auto-populates these for known models (e.g. Cohere, Voyage, Nvidia NIM,
+  # nomic-ai code-retrieval models, Snowflake arctic-embed).
+  # indexing_params:
+  #   input_type: search_document        # litellm: input_type, dimensions
+  # query_params:
+  #   input_type: search_query           # sentence-transformers: prompt_name
+
 envs:                                                # extra environment variables for the daemon
   OPENAI_API_KEY: your-key                           # only needed if not already in your shell environment
 ```
@@ -445,6 +453,30 @@ envs:                                                # extra environment variabl
 
 > **Custom location:** set `COCOINDEX_CODE_DIR` to place `global_settings.yml` somewhere other than `~/.cocoindex_code/` — useful if you want the file to live alongside your projects (e.g. on a synced folder).
 
+#### `indexing_params` / `query_params`
+
+Some embedding models expose different modes for documents vs queries (asymmetric retrieval). For example, Cohere's v3 models want `input_type: search_document` when embedding corpus content and `input_type: search_query` when embedding a user query; several SentenceTransformers models use `prompt_name: passage` / `prompt_name: query` for the same purpose. These knobs live under `indexing_params` and `query_params`:
+
+```yaml
+embedding:
+  provider: litellm
+  model: cohere/embed-english-v3.0
+  indexing_params:
+    input_type: search_document
+  query_params:
+    input_type: search_query
+```
+
+`ccc init` populates these automatically for models it recognizes — including all Cohere v3, Voyage, Nvidia NIM, Gemini embedding (`gemini/gemini-embedding-*`, `gemini/text-embedding-*`, `gemini/embedding-*` — LiteLLM auto-maps `input_type` to Gemini's `task_type`), `nomic-ai/CodeRankEmbed`, `nomic-ai/nomic-embed-code`, `nomic-ai/nomic-embed-text-v1`/`v1.5`, `mixedbread-ai/mxbai-embed-large-v1`, and the `Snowflake/snowflake-arctic-embed-*` family — and prints the chosen defaults. For other models, it leaves a commented-out template under `embedding:` so you can fill it in by hand.
+
+OpenAI embeddings (`text-embedding-3-*`, `text-embedding-ada-002`) are intentionally not in the list: they're symmetric and have no equivalent knob.
+
+**Accepted keys:** `prompt_name` (sentence-transformers), `input_type` and `dimensions` (litellm). Other keys are rejected at daemon startup with a clear error.
+
+**Doctor checks both sides.** `ccc doctor` exercises the model once with `indexing_params` and once with `query_params`, reporting each as a separate `Model Check (indexing)` / `Model Check (query)` entry — so a misconfiguration on one side is diagnosable without hiding behind the other.
+
+**Legacy-bridge warning:** if you're upgrading from an earlier version and your `global_settings.yml` uses `nomic-ai/CodeRankEmbed` or `nomic-ai/nomic-embed-code` without `indexing_params` / `query_params`, the daemon continues to apply the previous behavior (`prompt_name: query` at query time) and prints a one-time warning asking you to make the setting explicit. You can silence the warning by adding an empty block such as `query_params: {}`.
+
 ### Project Settings (`<project>/.cocoindex_code/settings.yml`)
 
 Per-project. Controls which files to index.
@@ -727,7 +759,7 @@ pipx upgrade cocoindex-code       # upgrade
 
 Using uv (install or upgrade):
 ```bash
-uv tool install --upgrade cocoindex-code --prerelease explicit --with "cocoindex>=1.0.0a24"
+uv tool install --upgrade cocoindex-code
 ```
 
 ## Legacy: Environment Variables

{cocoindex_code-0.2.28 → cocoindex_code-0.2.29}/README.md

@@ -52,7 +52,7 @@ pipx upgrade cocoindex-code                  # upgrade
 
 Using [uv](https://docs.astral.sh/uv/getting-started/installation/):
 ```bash
-uv tool install --upgrade 'cocoindex-code[full]' --prerelease explicit --with "cocoindex>=1.0.0a24"
+uv tool install --upgrade 'cocoindex-code[full]'
 ```
 
 Two install styles — they mirror the Docker image variants of the same names:
@@ -393,6 +393,14 @@ embedding:
   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
 
+  # Optional extra kwargs passed to the embedder, separately for indexing vs query.
+  # `ccc init` auto-populates these for known models (e.g. Cohere, Voyage, Nvidia NIM,
+  # nomic-ai code-retrieval models, Snowflake arctic-embed).
+  # indexing_params:
+  #   input_type: search_document        # litellm: input_type, dimensions
+  # query_params:
+  #   input_type: search_query           # sentence-transformers: prompt_name
+
 envs:                                                # extra environment variables for the daemon
   OPENAI_API_KEY: your-key                           # only needed if not already in your shell environment
 ```
@@ -401,6 +409,30 @@ envs:                                                # extra environment variabl
 
 > **Custom location:** set `COCOINDEX_CODE_DIR` to place `global_settings.yml` somewhere other than `~/.cocoindex_code/` — useful if you want the file to live alongside your projects (e.g. on a synced folder).
 
+#### `indexing_params` / `query_params`
+
+Some embedding models expose different modes for documents vs queries (asymmetric retrieval). For example, Cohere's v3 models want `input_type: search_document` when embedding corpus content and `input_type: search_query` when embedding a user query; several SentenceTransformers models use `prompt_name: passage` / `prompt_name: query` for the same purpose. These knobs live under `indexing_params` and `query_params`:
+
+```yaml
+embedding:
+  provider: litellm
+  model: cohere/embed-english-v3.0
+  indexing_params:
+    input_type: search_document
+  query_params:
+    input_type: search_query
+```
+
+`ccc init` populates these automatically for models it recognizes — including all Cohere v3, Voyage, Nvidia NIM, Gemini embedding (`gemini/gemini-embedding-*`, `gemini/text-embedding-*`, `gemini/embedding-*` — LiteLLM auto-maps `input_type` to Gemini's `task_type`), `nomic-ai/CodeRankEmbed`, `nomic-ai/nomic-embed-code`, `nomic-ai/nomic-embed-text-v1`/`v1.5`, `mixedbread-ai/mxbai-embed-large-v1`, and the `Snowflake/snowflake-arctic-embed-*` family — and prints the chosen defaults. For other models, it leaves a commented-out template under `embedding:` so you can fill it in by hand.
+
+OpenAI embeddings (`text-embedding-3-*`, `text-embedding-ada-002`) are intentionally not in the list: they're symmetric and have no equivalent knob.
+
+**Accepted keys:** `prompt_name` (sentence-transformers), `input_type` and `dimensions` (litellm). Other keys are rejected at daemon startup with a clear error.
+
+**Doctor checks both sides.** `ccc doctor` exercises the model once with `indexing_params` and once with `query_params`, reporting each as a separate `Model Check (indexing)` / `Model Check (query)` entry — so a misconfiguration on one side is diagnosable without hiding behind the other.
+
+**Legacy-bridge warning:** if you're upgrading from an earlier version and your `global_settings.yml` uses `nomic-ai/CodeRankEmbed` or `nomic-ai/nomic-embed-code` without `indexing_params` / `query_params`, the daemon continues to apply the previous behavior (`prompt_name: query` at query time) and prints a one-time warning asking you to make the setting explicit. You can silence the warning by adding an empty block such as `query_params: {}`.
+
 ### Project Settings (`<project>/.cocoindex_code/settings.yml`)
 
 Per-project. Controls which files to index.
@@ -683,7 +715,7 @@ pipx upgrade cocoindex-code       # upgrade
 
 Using uv (install or upgrade):
 ```bash
-uv tool install --upgrade cocoindex-code --prerelease explicit --with "cocoindex>=1.0.0a24"
+uv tool install --upgrade cocoindex-code
 ```
 
 ## Legacy: Environment Variables

{cocoindex_code-0.2.28 → cocoindex_code-0.2.29}/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.28'
-__version_tuple__ = version_tuple = (0, 2, 28)
+__version__ = version = '0.2.29'
+__version_tuple__ = version_tuple = (0, 2, 29)
 
 __commit_id__ = commit_id = None

{cocoindex_code-0.2.28 → cocoindex_code-0.2.29}/src/cocoindex_code/cli.py

@@ -436,6 +436,7 @@ def _run_init_model_check(settings_path: Path) -> None:
 
 def _setup_user_settings_interactive(litellm_model_flag: str | None) -> None:
     """Interactive global-settings setup — only runs when settings are missing."""
+    from .embedder_defaults import lookup_defaults
     from .shared import is_sentence_transformers_installed
 
     embedding = _resolve_embedding_choice(
@@ -444,10 +445,23 @@ def _setup_user_settings_interactive(litellm_model_flag: str | None) -> None:
         tty=sys.stdin.isatty(),
     )
 
-    path = save_initial_user_settings(embedding)
+    # 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 {}
+
+    path = save_initial_user_settings(embedding, defaults_applied=defaults_applied)
     _typer.echo()
     _typer.echo(f"Created user settings: {format_path_for_display(path)}")
 
+    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}")
     _run_init_model_check(path)

{cocoindex_code-0.2.28 → cocoindex_code-0.2.29}/src/cocoindex_code/client.py

@@ -65,6 +65,38 @@ logger = logging.getLogger(__name__)
 
 _daemon_ensured = False
 
+# Tracks which daemon-side handshake warnings have already been surfaced to
+# the user in this process. We print each distinct warning at most once per
+# `ccc` invocation — see `_print_handshake_warnings`.
+_surfaced_warnings: set[str] = set()
+
+
+def print_warning(message: str) -> None:
+    """Render a user-facing warning to stderr with a uniform style.
+
+    Prefixes with ``Warning:`` and renders in yellow when stderr is a TTY;
+    falls through as plain text for pipes / files / CI logs.  Intended as
+    the single entry point for warnings the user should notice — reuse it
+    for any new warning rather than inventing a local style.
+    """
+    import click
+
+    click.secho(f"Warning: {message}", fg="yellow", err=True)
+
+
+def _print_handshake_warnings(resp: HandshakeResponse) -> None:
+    """Print any new daemon-side warnings to stderr (once per process).
+
+    The daemon populates ``HandshakeResponse.warnings`` on every handshake;
+    the dedup set here ensures a warning is printed at most once within a
+    single CLI invocation even though several connections are opened.
+    """
+    for w in resp.warnings:
+        if w in _surfaced_warnings:
+            continue
+        _surfaced_warnings.add(w)
+        print_warning(w)
+
 
 def _is_daemon_supervised() -> bool:
     """True when an external supervisor (Docker entrypoint loop, systemd, …) owns
@@ -146,6 +178,7 @@ def _raw_connect_and_handshake() -> Connection:
     if not resp.ok or _needs_restart(resp):
         conn.close()
         raise DaemonVersionError(resp)
+    _print_handshake_warnings(resp)
     return conn
 
 
@@ -452,6 +485,7 @@ def stop_daemon() -> None:
     """
     global _daemon_ensured  # noqa: PLW0603
     _daemon_ensured = False
+    _surfaced_warnings.clear()
     pid_path = daemon_pid_path()
 
     pid: int | None = None

{cocoindex_code-0.2.28 → cocoindex_code-0.2.29}/src/cocoindex_code/daemon.py

@@ -24,6 +24,7 @@ from ._daemon_paths import (
 )
 from ._version import __version__
 from .chunking import ChunkerFn as _ChunkerFn
+from .embedder_params import resolve_embedder_params
 from .project import Project
 from .protocol import (
     DaemonEnvRequest,
@@ -56,6 +57,7 @@ from .protocol import (
 )
 from .settings import (
     ChunkerMapping,
+    UserSettings,
     format_path_for_display,
     get_host_path_mappings,
     global_settings_mtime_us,
@@ -69,6 +71,27 @@ from .shared import Embedder, check_embedding, create_embedder
 logger = logging.getLogger(__name__)
 
 
+def _build_backward_compat_warning(
+    user_settings: UserSettings,
+    settings_path: Path,
+) -> str:
+    """Compose the one-time handshake warning for legacy-bridge models.
+
+    Fired when a user's settings omit ``indexing_params`` / ``query_params`` for
+    a model that was previously hardcoded to use ``prompt_name="query"`` for
+    queries.  See embedder_defaults.LEGACY_QUERY_PROMPT_MODELS.
+    """
+    return (
+        f"Your embedding model ({user_settings.embedding.model}) was previously "
+        f'hardcoded to use prompt_name="query" for queries. Add the following to '
+        f"{settings_path} to keep this behavior and silence this warning:\n"
+        f"\n"
+        f"  embedding:\n"
+        f"    query_params:\n"
+        f"      prompt_name: query\n"
+    )
+
+
 def _resolve_chunker_registry(mappings: list[ChunkerMapping]) -> dict[str, _ChunkerFn]:
     """Resolve ``ChunkerMapping`` settings entries to a ``{suffix: fn}`` dict.
 
@@ -105,10 +128,19 @@ class ProjectRegistry:
 
     _projects: dict[str, Project]
     _embedder: Embedder | None
-
-    def __init__(self, embedder: Embedder | None) -> None:
+    indexing_params: dict[str, Any]
+    query_params: dict[str, Any]
+
+    def __init__(
+        self,
+        embedder: Embedder | None,
+        indexing_params: dict[str, Any] | None = None,
+        query_params: dict[str, Any] | None = None,
+    ) -> None:
         self._projects = {}
         self._embedder = embedder
+        self.indexing_params = dict(indexing_params) if indexing_params else {}
+        self.query_params = dict(query_params) if query_params else {}
 
     async def get_project(self, project_root: str) -> Project:
         """Get or create a Project for the given root. Lazy initialization."""
@@ -120,7 +152,13 @@ class ProjectRegistry:
             root = Path(project_root)
             project_settings = load_project_settings(root)
             chunker_registry = _resolve_chunker_registry(project_settings.chunkers)
-            project = await Project.create(root, self._embedder, chunker_registry=chunker_registry)
+            project = await Project.create(
+                root,
+                self._embedder,
+                indexing_params=self.indexing_params,
+                query_params=self.query_params,
+                chunker_registry=chunker_registry,
+            )
             self._projects[project_root] = project
         return self._projects[project_root]
 
@@ -168,6 +206,7 @@ async def handle_connection(
     on_shutdown: Callable[[], None],
     settings_mtime_us: int | None,
     settings_env_names: list[str],
+    handshake_warnings: list[str],
 ) -> None:
     """Handle a single client connection (per-request model).
 
@@ -193,6 +232,7 @@ async def handle_connection(
                     ok=ok,
                     daemon_version=__version__,
                     global_settings_mtime_us=settings_mtime_us,
+                    warnings=list(handshake_warnings),
                 )
             )
         )
@@ -260,8 +300,19 @@ async def _handle_doctor(
     appear before project settings in the output.
     """
     if req.project_root is None:
-        # Global-scope checks
-        yield DoctorResponse(result=await _check_model(registry._embedder))
+        # Global-scope checks — two separate embed calls because indexing and
+        # query may pass different kwargs (asymmetric embedding models), and
+        # either side can fail independently (e.g. a malformed input_type).
+        yield DoctorResponse(
+            result=await _check_model(
+                registry._embedder, label="indexing", params=registry.indexing_params
+            )
+        )
+        yield DoctorResponse(
+            result=await _check_model(
+                registry._embedder, label="query", params=registry.query_params
+            )
+        )
     else:
         # Project-scope checks
         yield DoctorResponse(result=await _check_file_walk(req.project_root))
@@ -274,31 +325,39 @@ async def _handle_doctor(
     )
 
 
-async def _check_model(embedder: Embedder | None) -> DoctorCheckResult:
-    """Test the embedding model by embedding a short string.
+async def _check_model(
+    embedder: Embedder | None,
+    label: str,
+    params: dict[str, Any],
+) -> DoctorCheckResult:
+    """Test the embedding model by embedding a short string using *params*.
 
-    Returns a failed result when the embedder is ``None`` (daemon running in
-    no-settings mode).
+    *label* appears in the check's name (e.g. ``"indexing"`` / ``"query"``) so
+    users see which side of the config the result corresponds to.  Returns a
+    failed result when the embedder is ``None`` (daemon running in no-settings
+    mode).
     """
+    name = f"Model Check ({label})"
     if embedder is None:
         return DoctorCheckResult(
-            name="Model Check",
+            name=name,
             ok=False,
             details=[],
             errors=["Daemon has no global settings loaded. Run `ccc init` to set up."],
         )
-    result = await check_embedding(embedder)
+    result = await check_embedding(embedder, params)
+    params_detail = f"params: {params}" if params else "params: {} (no extra kwargs)"
     if result.error is None:
         return DoctorCheckResult(
-            name="Model Check",
+            name=name,
             ok=True,
-            details=[f"Embedding dimension: {result.dim}"],
+            details=[params_detail, f"Embedding dimension: {result.dim}"],
             errors=[],
         )
     return DoctorCheckResult(
-        name="Model Check",
+        name=name,
         ok=False,
-        details=[],
+        details=[params_detail],
         errors=[result.error],
     )
 
@@ -506,11 +565,27 @@ def run_daemon() -> None:
     # provider/model picker in `ccc init`.
     settings_mtime_us = global_settings_mtime_us()  # None when file is missing
     embedder: Embedder | None
+    indexing_params: dict[str, Any] = {}
+    query_params: dict[str, Any] = {}
+    handshake_warnings: list[str] = []
     if user_settings_path().is_file():
         user_settings = load_user_settings()
         settings_env_keys = list(user_settings.envs.keys())
         for key, value in user_settings.envs.items():
             os.environ[key] = value
+        # Resolve params BEFORE constructing the embedder so invalid configs
+        # fail fast without paying the model-load cost.
+        try:
+            embedder_params = resolve_embedder_params(user_settings.embedding)
+        except ValueError:
+            logger.exception("Invalid embedder params in global_settings.yml")
+            sys.exit(1)
+        indexing_params = embedder_params.indexing
+        query_params = embedder_params.query
+        if embedder_params.used_backward_compat:
+            handshake_warnings.append(
+                _build_backward_compat_warning(user_settings, user_settings_path())
+            )
         embedder = create_embedder(user_settings.embedding)
     else:
         settings_env_keys = []
@@ -532,7 +607,11 @@ def run_daemon() -> None:
     logger.info("Daemon starting (PID %d, version %s)", os.getpid(), __version__)
 
     start_time = time.monotonic()
-    registry = ProjectRegistry(embedder)
+    registry = ProjectRegistry(
+        embedder,
+        indexing_params=indexing_params,
+        query_params=query_params,
+    )
 
     sock_path = daemon_socket_path()
     if sys.platform != "win32":
@@ -560,6 +639,7 @@ def run_daemon() -> None:
                 _request_shutdown,
                 settings_mtime_us,
                 settings_env_keys,
+                handshake_warnings,
             )
         )
         tasks.add(task)

cocoindex_code-0.2.29/src/cocoindex_code/embedder_defaults.py

@@ -0,0 +1,152 @@
+"""Curated default embedder params for known models.
+
+Consulted only by ``ccc init`` — the table is NOT read at daemon runtime.
+The runtime path reads the user's YAML verbatim; the legacy-bridge in
+``embedder_params.resolve_embedder_params`` is the only runtime-level fallback
+and is scoped to :data:`LEGACY_QUERY_PROMPT_MODELS`.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, NamedTuple
+
+__all__ = [
+    "DefaultParamsEntry",
+    "LEGACY_QUERY_PROMPT_MODELS",
+    "lookup_defaults",
+]
+
+
+class DefaultParamsEntry(NamedTuple):
+    provider: str  # "sentence-transformers" | "litellm"
+    model: str | re.Pattern[str]  # str = exact match; Pattern = regex match
+    indexing_params: dict[str, Any]  # may be empty
+    query_params: dict[str, Any]  # may be empty
+
+
+# Models previously hardcoded in shared.py:_QUERY_PROMPT_MODELS.  Retained as
+# a frozenset so the legacy-bridge in ``embedder_params`` can recognize
+# pre-existing configs that predate this feature.
+LEGACY_QUERY_PROMPT_MODELS: frozenset[str] = frozenset(
+    {"nomic-ai/nomic-embed-code", "nomic-ai/CodeRankEmbed"}
+)
+
+
+_DEFAULT_PARAMS: list[DefaultParamsEntry] = [
+    # --- sentence-transformers ---
+    DefaultParamsEntry(
+        "sentence-transformers",
+        "nomic-ai/CodeRankEmbed",
+        {},
+        {"prompt_name": "query"},
+    ),
+    DefaultParamsEntry(
+        "sentence-transformers",
+        "nomic-ai/nomic-embed-code",
+        {},
+        {"prompt_name": "query"},
+    ),
+    DefaultParamsEntry(
+        "sentence-transformers",
+        "nomic-ai/nomic-embed-text-v1",
+        {"prompt_name": "passage"},
+        {"prompt_name": "query"},
+    ),
+    DefaultParamsEntry(
+        "sentence-transformers",
+        "nomic-ai/nomic-embed-text-v1.5",
+        {"prompt_name": "passage"},
+        {"prompt_name": "query"},
+    ),
+    DefaultParamsEntry(
+        "sentence-transformers",
+        "mixedbread-ai/mxbai-embed-large-v1",
+        {},
+        {"prompt_name": "query"},
+    ),
+    DefaultParamsEntry(
+        "sentence-transformers",
+        re.compile(r"Snowflake/snowflake-arctic-embed-.+"),
+        {},
+        {"prompt_name": "query"},
+    ),
+    # --- litellm ---
+    DefaultParamsEntry(
+        "litellm",
+        re.compile(r"cohere/embed-(english|multilingual)(-light)?-v3\.0"),
+        {"input_type": "search_document"},
+        {"input_type": "search_query"},
+    ),
+    DefaultParamsEntry(
+        "litellm",
+        re.compile(r"voyage/.+"),
+        {"input_type": "document"},
+        {"input_type": "query"},
+    ),
+    DefaultParamsEntry(
+        "litellm",
+        re.compile(r"nvidia_nim/nvidia/.+"),
+        {"input_type": "passage"},
+        {"input_type": "query"},
+    ),
+    # Gemini embedding models: LiteLLM's Gemini transformation auto-maps
+    # `input_type` → `task_type` (RETRIEVAL_DOCUMENT / RETRIEVAL_QUERY work
+    # across all Gemini embedding generations).
+    DefaultParamsEntry(
+        "litellm",
+        re.compile(r"gemini/(gemini-embedding|text-embedding|embedding)[-\w.]*"),
+        {"input_type": "RETRIEVAL_DOCUMENT"},
+        {"input_type": "RETRIEVAL_QUERY"},
+    ),
+]
+
+
+def lookup_defaults(
+    provider: str, model: str
+) -> tuple[dict[str, Any] | None, dict[str, Any] | None]:
+    """Look up recommended (indexing_params, query_params) for *model*.
+
+    Walks :data:`_DEFAULT_PARAMS` in order; an exact-name entry matches iff
+    ``entry.model == model``; a compiled-regex entry matches via
+    ``entry.model.fullmatch(model)``.  First match wins.  Returns the pair of
+    dicts (each possibly empty) or ``(None, None)`` when no entry matches.
+    """
+    for entry in _DEFAULT_PARAMS:
+        if entry.provider != provider:
+            continue
+        if isinstance(entry.model, str):
+            matched = entry.model == model
+        else:
+            matched = entry.model.fullmatch(model) is not None
+        if matched:
+            return dict(entry.indexing_params), dict(entry.query_params)
+    return None, None
+
+
+def _assert_legacy_bridge_invariant() -> None:
+    """Each legacy model must have an exact sentence-transformers entry with
+    ``query_params == {"prompt_name": "query"}``.  Guarantees users who run
+    ``ccc init`` against a legacy model get the same effective behavior the
+    runtime legacy-bridge produces.
+    """
+    for legacy in LEGACY_QUERY_PROMPT_MODELS:
+        found = False
+        for entry in _DEFAULT_PARAMS:
+            if (
+                entry.provider == "sentence-transformers"
+                and isinstance(entry.model, str)
+                and entry.model == legacy
+                and entry.query_params == {"prompt_name": "query"}
+            ):
+                found = True
+                break
+        if not found:
+            raise AssertionError(
+                f"Legacy model {legacy!r} has no matching sentence-transformers "
+                f"exact-name entry in _DEFAULT_PARAMS with "
+                f"query_params={{'prompt_name': 'query'}}"
+            )
+
+
+_assert_legacy_bridge_invariant()

cocoindex_code-0.2.29/src/cocoindex_code/embedder_params.py

@@ -0,0 +1,95 @@
+"""Validation and resolution of embedder ``indexing_params`` / ``query_params``.
+
+Runtime entry point is :func:`resolve_embedder_params`.  The curated defaults
+table lives in :mod:`embedder_defaults` and is used only by ``ccc init`` —
+this module does not consult it.
+"""
+
+from __future__ import annotations
+
+from typing import Any, NamedTuple
+
+from .embedder_defaults import LEGACY_QUERY_PROMPT_MODELS
+from .settings import EmbeddingSettings
+
+__all__ = [
+    "EmbedderParams",
+    "accepted_kwargs_for",
+    "resolve_embedder_params",
+    "validate_params",
+]
+
+
+# Accepted kwargs per provider.  Intentionally minimal — we only expose knobs
+# that users have reason to tune.  ``normalize_embeddings`` (sentence-
+# transformers) and ``encoding_format`` (litellm) are deliberately excluded
+# because other code assumes unit vectors (query._l2_to_score) and float
+# payloads (litellm_embedder hardcodes encoding_format="float").
+_ACCEPTED_KWARGS: dict[str, frozenset[str]] = {
+    "sentence-transformers": frozenset({"prompt_name"}),
+    "litellm": frozenset({"input_type", "dimensions"}),
+}
+
+
+def accepted_kwargs_for(provider: str) -> frozenset[str]:
+    """Return the set of accepted kwarg names for *provider*.
+
+    Raises ``ValueError`` on unknown providers.
+    """
+    try:
+        return _ACCEPTED_KWARGS[provider]
+    except KeyError as e:
+        raise ValueError(f"Unknown provider: {provider!r}") from e
+
+
+def validate_params(
+    provider: str,
+    indexing_params: dict[str, Any] | None,
+    query_params: dict[str, Any] | None,
+) -> None:
+    """Raise ``ValueError`` if either dict contains keys not accepted by *provider*."""
+    accepted = accepted_kwargs_for(provider)
+    for side, params in (("indexing_params", indexing_params), ("query_params", query_params)):
+        if not params:
+            continue
+        unknown = sorted(set(params) - accepted)
+        if unknown:
+            raise ValueError(
+                f"{side}: unknown key(s) {unknown!r} for provider {provider!r}. "
+                f"Accepted keys: {sorted(accepted)!r}."
+            )
+
+
+class EmbedderParams(NamedTuple):
+    """Params that will be spread into ``embedder.embed()`` calls at runtime."""
+
+    indexing: dict[str, Any]  # never None; possibly empty
+    query: dict[str, Any]  # never None; possibly empty
+    used_backward_compat: bool  # True iff the legacy bridge fired
+
+
+def resolve_embedder_params(settings: EmbeddingSettings) -> EmbedderParams:
+    """Resolve the effective embedder params from user settings.
+
+    Whatever the user put in the file, verbatim, with one exception for
+    backward compatibility: if neither ``indexing_params`` nor ``query_params``
+    is set and the model was previously handled by the hardcoded
+    ``_QUERY_PROMPT_MODELS`` path, fill in ``query = {'prompt_name': 'query'}``
+    and raise the ``used_backward_compat`` flag so the daemon emits a
+    handshake warning.
+    """
+    indexing: dict[str, Any] = dict(settings.indexing_params) if settings.indexing_params else {}
+    query: dict[str, Any] = dict(settings.query_params) if settings.query_params else {}
+    used_backward_compat = False
+
+    if (
+        settings.indexing_params is None
+        and settings.query_params is None
+        and settings.provider == "sentence-transformers"
+        and settings.model in LEGACY_QUERY_PROMPT_MODELS
+    ):
+        query = {"prompt_name": "query"}
+        used_backward_compat = True
+
+    validate_params(settings.provider, indexing, query)
+    return EmbedderParams(indexing=indexing, query=query, used_backward_compat=used_backward_compat)

{cocoindex_code-0.2.28 → cocoindex_code-0.2.29}/src/cocoindex_code/indexer.py

@@ -19,6 +19,7 @@ from .settings import load_gitignore_spec, load_project_settings
 from .shared import (
     CODEBASE_DIR,
     EMBEDDER,
+    INDEXING_EMBED_PARAMS,
     SQLITE_DB,
     CodeChunk,
 )
@@ -140,6 +141,7 @@ async def process_file(
 ) -> None:
     """Process a single file: chunk, embed, and store."""
     embedder = coco.use_context(EMBEDDER)
+    indexing_params = coco.use_context(INDEXING_EMBED_PARAMS)
 
     try:
         content = await file.read_text()
@@ -185,7 +187,7 @@ async def process_file(
                 content=chunk.text,
                 start_line=chunk.start.line,
                 end_line=chunk.end.line,
-                embedding=await embedder.embed(chunk.text),
+                embedding=await embedder.embed(chunk.text, **indexing_params),
             )
         )
 

{cocoindex_code-0.2.28 → cocoindex_code-0.2.29}/src/cocoindex_code/litellm_embedder.py

@@ -13,6 +13,8 @@ import numpy as np
 from cocoindex.ops.litellm import LiteLLMEmbedder, litellm
 from numpy.typing import NDArray
 
+litellm.drop_params = True
+
 logger = logging.getLogger(__name__)
 
 _RATE_LIMIT_DELAY_RE = re.compile(r"Please try again in ([0-9.]+)(ms|s)", re.IGNORECASE)

{cocoindex_code-0.2.28 → cocoindex_code-0.2.29}/src/cocoindex_code/project.py

@@ -6,6 +6,7 @@ import asyncio
 import sqlite3
 from collections.abc import AsyncIterator, Callable
 from pathlib import Path
+from typing import Any
 
 import cocoindex as coco
 from cocoindex.connectors import sqlite as coco_sqlite
@@ -34,6 +35,8 @@ from .settings import (
 from .shared import (
     CODEBASE_DIR,
     EMBEDDER,
+    INDEXING_EMBED_PARAMS,
+    QUERY_EMBED_PARAMS,
     SQLITE_DB,
     Embedder,
 )
@@ -257,9 +260,11 @@ class Project:
     async def create(
         project_root: Path,
         embedder: Embedder,
+        indexing_params: dict[str, Any],
+        query_params: dict[str, Any],
         chunker_registry: dict[str, ChunkerFn] | None = None,
     ) -> Project:
-        """Create a project with explicit embedder.
+        """Create a project with explicit embedder and per-call params.
 
         Project-level settings and .gitignore are NOT cached here — the
         indexer loads them fresh from disk on every run so that user edits
@@ -268,6 +273,11 @@ class Project:
         Args:
             project_root: Root directory of the codebase to index.
             embedder: Embedding model instance.
+            indexing_params: Extra kwargs spread into ``embedder.embed()`` during
+                indexing (e.g. ``{"prompt_name": "passage"}``).  Pass ``{}`` for
+                no extras.
+            query_params: Extra kwargs spread into ``embedder.embed()`` for the
+                query side.
             chunker_registry: Optional mapping of file suffix (e.g. ``".toml"``)
                 to a ``ChunkerFn``. When a suffix matches, the registered
                 chunker is called instead of the built-in splitter.
@@ -287,6 +297,8 @@ class Project:
         context.provide(CODEBASE_DIR, project_root)
         context.provide(SQLITE_DB, coco_sqlite.connect(str(target_sqlite_db), load_vec=True))
         context.provide(EMBEDDER, embedder)
+        context.provide(INDEXING_EMBED_PARAMS, dict(indexing_params))
+        context.provide(QUERY_EMBED_PARAMS, dict(query_params))
         context.provide(CHUNKER_REGISTRY, dict(chunker_registry) if chunker_registry else {})
 
         env = coco.Environment(settings, context_provider=context)

{cocoindex_code-0.2.28 → cocoindex_code-0.2.29}/src/cocoindex_code/protocol.py

@@ -71,6 +71,9 @@ class HandshakeResponse(_msgspec.Struct, tag="handshake"):
     ok: bool
     daemon_version: str
     global_settings_mtime_us: int | None = None
+    # Non-fatal daemon-side warnings surfaced to the client on every handshake.
+    # The client dedupes and prints them to stderr (see client._print_handshake_warnings).
+    warnings: list[str] = []
 
 
 class IndexResponse(_msgspec.Struct, tag="index"):

{cocoindex_code-0.2.28 → cocoindex_code-0.2.29}/src/cocoindex_code/query.py

@@ -8,7 +8,7 @@ from pathlib import Path
 from typing import Any
 
 from .schema import QueryResult
-from .shared import EMBEDDER, SQLITE_DB, query_prompt_name
+from .shared import EMBEDDER, QUERY_EMBED_PARAMS, SQLITE_DB
 
 
 def _l2_to_score(distance: float) -> float:
@@ -106,9 +106,10 @@ async def query_codebase(
 
     db = env.get_context(SQLITE_DB)
     embedder = env.get_context(EMBEDDER)
+    query_params = env.get_context(QUERY_EMBED_PARAMS)
 
     # Generate query embedding.
-    query_embedding = await embedder.embed(query, query_prompt_name)
+    query_embedding = await embedder.embed(query, **query_params)
 
     embedding_bytes = query_embedding.astype("float32").tobytes()
 

{cocoindex_code-0.2.28 → cocoindex_code-0.2.29}/src/cocoindex_code/settings.py

@@ -93,6 +93,11 @@ class EmbeddingSettings:
     provider: str = "litellm"
     device: str | None = None
     min_interval_ms: int | None = None
+    # Extra kwargs spread into ``embedder.embed()`` during indexing/query.
+    # ``None`` means the user did not set the key; ``{}`` is an explicit empty
+    # dict (used to opt out of the legacy-bridge warning).
+    indexing_params: dict[str, Any] | None = None
+    query_params: dict[str, Any] | None = None
 
 
 @dataclass
@@ -410,6 +415,10 @@ def _embedding_settings_to_dict(embedding: EmbeddingSettings) -> dict[str, Any]:
         d["device"] = embedding.device
     if embedding.min_interval_ms is not None:
         d["min_interval_ms"] = embedding.min_interval_ms
+    if embedding.indexing_params is not None:
+        d["indexing_params"] = dict(embedding.indexing_params)
+    if embedding.query_params is not None:
+        d["query_params"] = dict(embedding.query_params)
     return d
 
 
@@ -432,6 +441,13 @@ def _user_settings_from_dict(d: dict[str, Any]) -> UserSettings:
         emb_kwargs["device"] = emb_dict["device"]
     if "min_interval_ms" in emb_dict:
         emb_kwargs["min_interval_ms"] = emb_dict["min_interval_ms"]
+    # indexing_params / query_params: missing → None (dataclass default);
+    # present-but-null → {} (treat the same as an empty dict, since both mean
+    # "user acknowledged the key and wants no extra kwargs").
+    if "indexing_params" in emb_dict:
+        emb_kwargs["indexing_params"] = dict(emb_dict["indexing_params"] or {})
+    if "query_params" in emb_dict:
+        emb_kwargs["query_params"] = dict(emb_dict["query_params"] or {})
     embedding = EmbeddingSettings(**emb_kwargs)
     envs = d.get("envs", {})
     return UserSettings(embedding=embedding, envs=envs)
@@ -514,21 +530,53 @@ _INITIAL_ENVS_COMMENT = (
     "#   VOYAGE_API_KEY: ...\n"
 )
 
-
-def save_initial_user_settings(embedding: EmbeddingSettings) -> Path:
+# Comment-template blocks inserted after `embedding:` when we don't have
+# curated defaults for the chosen model, so users know the fields exist.
+# Keyed by provider name.
+_PARAMS_COMMENT_BY_PROVIDER: dict[str, str] = {
+    "sentence-transformers": (
+        "  #\n"
+        "  # Extra kwargs passed to the embedder. Supported keys:\n"
+        "  #   prompt_name\n"
+        "  # indexing_params: {}\n"
+        "  # query_params: {}\n"
+    ),
+    "litellm": (
+        "  #\n"
+        "  # Extra kwargs passed to the embedder. Supported keys:\n"
+        "  #   input_type, dimensions\n"
+        "  # indexing_params: {}\n"
+        "  # query_params: {}\n"
+    ),
+}
+
+
+def save_initial_user_settings(
+    embedding: EmbeddingSettings,
+    defaults_applied: bool,
+) -> 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.
+
+    When ``defaults_applied`` is False, a provider-specific commented-out
+    template for ``indexing_params`` / ``query_params`` is inserted under the
+    ``embedding:`` block so the user sees the fields exist.
     """
     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
+    content = _INITIAL_HEADER + emb_block
+    if not defaults_applied:
+        hint = _PARAMS_COMMENT_BY_PROVIDER.get(embedding.provider)
+        if hint is not None:
+            content += hint
+    content += _INITIAL_ENVS_COMMENT
 
     path = user_settings_path()
     path.parent.mkdir(parents=True, exist_ok=True)

{cocoindex_code-0.2.28 → cocoindex_code-0.2.29}/src/cocoindex_code/shared.py

@@ -6,7 +6,7 @@ import importlib.util
 import logging
 import pathlib
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Annotated, NamedTuple, Union
+from typing import TYPE_CHECKING, Annotated, Any, NamedTuple, Union
 
 import cocoindex as coco
 import numpy as np
@@ -24,9 +24,6 @@ logger = logging.getLogger(__name__)
 SBERT_PREFIX = "sbert/"
 DEFAULT_LITELLM_MIN_INTERVAL_MS = 5
 
-# Models that define a "query" prompt for asymmetric retrieval.
-_QUERY_PROMPT_MODELS = {"nomic-ai/nomic-embed-code", "nomic-ai/CodeRankEmbed"}
-
 # Type alias
 Embedder = Union["SentenceTransformerEmbedder", "LiteLLMEmbedder"]
 
@@ -34,12 +31,8 @@ Embedder = Union["SentenceTransformerEmbedder", "LiteLLMEmbedder"]
 EMBEDDER = coco.ContextKey[Embedder]("embedder", detect_change=True)
 SQLITE_DB = coco.ContextKey[sqlite.ManagedConnection]("index_db")
 CODEBASE_DIR = coco.ContextKey[pathlib.Path]("codebase")
-
-# Module-level variable — set by daemon at startup (needed for CodeChunk annotation).
-embedder: Embedder | None = None
-
-# Query prompt name — set alongside embedder by create_embedder().
-query_prompt_name: str | None = None
+INDEXING_EMBED_PARAMS = coco.ContextKey[dict[str, Any]]("indexing_embed_params")
+QUERY_EMBED_PARAMS = coco.ContextKey[dict[str, Any]]("query_embed_params")
 
 
 def is_sentence_transformers_installed() -> bool:
@@ -61,29 +54,30 @@ class EmbeddingCheckResult(NamedTuple):
     error: str | None
 
 
-async def check_embedding(embedder: Embedder) -> EmbeddingCheckResult:
+async def check_embedding(
+    embedder: Embedder,
+    params: dict[str, Any] | None = None,
+) -> 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`).
+    *params* are spread into ``embed()`` so callers can verify indexing vs
+    query params separately (they may use different keys at runtime).
+
+    Never raises. Used by the daemon's doctor path (`daemon._check_model`).
     """
+    kwargs = dict(params) if params else {}
     try:
-        vec = await embedder.embed("hello world")
+        vec = await embedder.embed("hello world", **kwargs)
         return EmbeddingCheckResult(dim=len(vec), error=None)
     except Exception as e:
-        msg = f"{type(e).__name__}: {e}".splitlines()[0]
+        msg = " ".join(f"{type(e).__name__}: {e}".splitlines())
         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.
-
-    Also sets the module-level ``embedder`` and ``query_prompt_name`` variables.
-    """
-    global embedder, query_prompt_name
-
+    """Create and return an embedder instance based on settings."""
     if settings.provider == "sentence-transformers":
         from cocoindex.ops.sentence_transformers import SentenceTransformerEmbedder
 
@@ -92,7 +86,6 @@ def create_embedder(settings: EmbeddingSettings) -> Embedder:
         if model_name.startswith(SBERT_PREFIX):
             model_name = model_name[len(SBERT_PREFIX) :]
 
-        query_prompt_name = "query" if model_name in _QUERY_PROMPT_MODELS else None
         instance: Embedder = SentenceTransformerEmbedder(
             model_name,
             device=settings.device,
@@ -111,14 +104,12 @@ def create_embedder(settings: EmbeddingSettings) -> Embedder:
             settings.model,
             min_interval_ms=min_interval_ms,
         )
-        query_prompt_name = None
         logger.info(
             "Embedding model (LiteLLM): %s | min_interval_ms: %s",
             settings.model,
             min_interval_ms,
         )
 
-    embedder = instance
     return instance