[jkbdco]

Summary

Adds a third embedder path beside sentence-transformers and litellm: provider: custom with embedding.embedder: "module.path:callable". cocoindex-code imports the factory and calls it once at daemon start as factory(settings, indexing_params); the result must expose an async embed() and cocoindex's __coco_vector_schema__() (checked at load against a small runtime protocol, CustomEmbedder). The form mirrors the module.path:callable strings the chunker registry already accepts.

Why

The cloud path routes every embedding through litellm. That is the right default for a tool that wants to support a hundred providers out of the box, but it is also a large dependency tree (aiohttp, boto3, openai, tiktoken, tokenizers and about forty more), and litellm has had two PyPI supply-chain compromises this year (1.82.7/1.82.8 in March, 1.107.0 on October 21). A user who talks to one provider can now install a small adapter of their own next to the tool (uv tool install cocoindex-code --with my-embedders, with a uv override to leave litellm out) and keep the rest of cocoindex-code unchanged. We run the index this way against Voyage AI; the adapter is a single-file httpx client.

Changes

• settings.py: EmbeddingSettings.embedder, validated in __post_init__ (required with custom, rejected with any other provider), round-tripped by the YAML (de)serialisers; a comment template for the custom provider in generated settings.
• embedder_params.py: validate_params passes a custom embedder's kwargs through; the embedder owns them.
• shared.py: CustomEmbedder protocol, load_custom_embedder_factory() with errors that name the spec (malformed value, import failure, missing attribute, non-callable), and the custom branch in create_embedder() that checks the returned object against the protocol.
• tests/test_custom_embedder.py: settings validation and round trip, params pass-through, loading a factory from a temporary module, contract rejection, every loader error, and an embed + schema call through the loaded object.
• EMBEDDINGS.md: a "Custom Embedder" section with the YAML shape and the contract; CLAUDE.md: one line in the embedding-flow notes.

ccc init is unchanged and does not offer the provider; it is a settings-file feature.

Testing

• tests/test_custom_embedder.py, tests/test_settings.py, tests/test_embedder_params.py: 100 passed.
• Full suite in a venv without sentence-transformers: 30 failures, identical to main run the same way in the same environment (all need sentence_transformers/torch or a running ccc); no new failures on this branch.
• ruff check and ruff format --check clean on the touched files; mypy --strict clean on them apart from the pre-existing yaml stubs note.
• Used in anger: our index daemons run with this hook and a small httpx Voyage adapter, litellm absent from the environment.

🤖 Generated with Claude Code