`ccc init` wizard misleads users into selecting `sentence-transformers` for local Ollama setups, causing crashes

[jimmckeeth]

The interactive setup prompt for ccc init incorrectly labels providers, which misleads users trying to configure a local Ollama model. The CLI implies sentence-transformers is the choice for local models, while labeling litellm as a cloud option.

Steps to Reproduce:

1. Run ccc init.
2. Observe the prompt:

? Embedding provider (Use arrow keys)
 » sentence-transformers (local, free)
   litellm (cloud, 100+ providers)

3. Select sentence-transformers (because I want "local/free" and I don't have an API key).
4. Enter ollama/nomic-embed-text as the model.
5. The application crashes because sentence-transformers attempts to process a LiteLLM/Ollama prefix as a HuggingFace identifier.

And to top it off the documentation is useless. ollama/snowflake-arctic-embed is mentioned under LineLLM but not under sentence-transformers, but the default of Snowflake/snowflake-arctic-embed-xs isn't mentioned anyplace in the docs. Even the README here says "LiteLLM-only; requires a cloud embedding provider and API key."

And to top it all off, if I run ccc init again ccc reset --all it doesn't help. I have to either delete .cocoindex_code/global_settings.yml or edit it manually. Thankfully ccc doctor includes a mention of that settings file after scrolling a couple of pages of crash messages.

---

Expected Behavior:

• The init walk through should clarify that litellm is required for local Ollama proxying.
• 'Init' should test the configuration before writing it to a hidden config file that just crashes.
• An option for ccc reset --global or ccc init --global to repeat the global init again.
• ccc doctor should trap the crash and provide suggested troubleshooting steps (like running ccc init --global again.)

Suggested Fixes:

• Change the litellm label to something like litellm (cloud APIs & local Ollama).
• Add input validation that throws a clear warning or error immediately during the prompt if a user selects sentence-transformers but enters a model starting with ollama/.
  • Better yet, have a list of options the user can scroll through, with a free form "other".
  • Then test the selection to make sure it is valid.
• Documentation that explains this at least a little.
  • Is Snowflake/snowflake-arctic-embed-xs the only sentence-transformers option?
  • CocoIndex-Code doesn't have any documentation (that I could fine) beyond the README and the landing page. So users end up reading the CocoIndex documentation and then have to figure out what CocoIndex-Code does from the source code.

I understand the CCC is made with the full CocoIndex, and if I look at the full CCC source code and then read the CocoIndex docs I can figure it out, but when I have an install guide and guided init, I expect it to work.

Don't get me wrong, I'm a big fan of CCC. I did a lunch and learn presentation on it at work, and am planning another presentation on it in a couple of weeks for a different group. But all three times I've installed it now it crashed out and I had to edit the global_settings.yml settings file manually. I ended up creating an installation guide for coworkers because a number of them had trouble installing it too (partially due to annoying corporate networking configuration, but also because of the reasons described above.)

[badmonster0]

Thank you so much @jimmckeeth Really appreciate you sharing the project and leave such detailed steps and suggestions on the fix, we will take a look as soon as we can!

[georgeh0]

Hi @jimmckeeth ,

Thanks for the detailed report and suggestion. Really sorry for all the confusions and thanks for your patience.

• We'll definitely update labels for the providers.

• Regarding the error resulted from ccc init, the current consideration is: the wizard aim at covering simple cases and doesn't cover everything (yet), e.g. sometimes more env variables need to be configured and the wizard isn't comprehensive enough to support all, so currently it works in the way like: if there's any error there, we show the error and ask users to edit the global setting file and run ccc doctor to verify. We already show this today after showing the error messages in running the model:

  You can edit /Users/hjz/.cocoindex_code/global_settings.yml to change the model or add API keys under `envs:`. Then run `ccc doctor` to verify.                                                                                                                                          
  

  But seems this message is not noticed? We can improve by:

  • Make this message more apparent
  • Once there's any error, ask users to choose between: update settings by the wizard or try again, or exit and update global_settings.yml manually. Only exit the wizard if they explicitly choose so.
  • Make the wizard more comprehensive and cover all needs, so that we never write the global setting file until the configured model works.

  Let us know which makes more sense from your perspective.

• We'll also consider a feature of invoking the wizard to edit the global settings afterwards. (there can be risk, e.g. today the settings files are considered owned by users once generated by the wizard, so users may organize in their own way, e.g. when they switch model they may comment out the previous model and API key so they can switch back easily, regenerating the setting file will potentially clear these comments, but I guess as long as we make this side effect clear, it'll be fine)

[jimmckeeth]

I did see the message, but it wasn't immediately obvious to me.

BTW, I really like the improvements you recently added. This made the usage much clearer, and the test loop is a nice touch.

I would still suggest the line

See supported LiteLLM embedding models: https://docs.litellm.ai/docs/embedding/supported_embedding

is not ideal.

I made PR#188 with EMBEDDINGS.md as a guide.