FAQ & Troubleshooting

What are the main differences between the primary reasoning model, the next step model, and the summarizer model?

The primary reasoning model (selected during setup, e.g., Claude Sonnet, Gemini Pro, Llama 3) is responsible for high-level planning, deciding which tools to use, understanding context, and writing the final report. The next step model (typically Gemini 2.5 Flash) analyzes the research progress and decides on the next action to take. The summarizer model (e.g., Gemini Flash, DeepSeek 8B) is used for processing large amounts of text from web pages or documents, condensing it into smaller summaries that the primary model can work with efficiently, especially when using local models with smaller context windows.

How does token tracking and cost estimation work?

If TRACK_TOKEN_USAGE is enabled in config.yaml, CleverBee uses LangChain callbacks to count the input and output tokens for each LLM API call. It then multiplies these counts by the pricing defined in config.yaml (e.g., GEMINI_COST_PER_1K_INPUT_TOKENS) to provide an estimated cost. Note that this is an estimate and actual billing from the provider might differ slightly.

Can I use CleverBee completely offline?

Yes, if you select local models for both the primary reasoning and summarization tasks during setup (e.g., using Llama 3 and DeepSeek 8B). However, core functionality like web browsing (web_browser tool) and using MCP tools that require internet access (like YouTube transcripts) will not work offline.

How can I clear the LLM cache?

Run the application with the --no-cache flag: ./run.sh --no-cache. This will delete the .langchain.db file before starting, forcing the LLM to generate fresh responses.

Where are downloaded models stored?

By default, local GGUF models selected during setup are downloaded to the models/ directory within the project folder. This location is defined by LOCAL_MODELS_DIR in config.yaml.

Issue: Installation fails during llama-cpp-python build.

Solution:

• Ensure you have CMake installed (brew install cmake or sudo apt install cmake).
• Check the terminal output for specific compilation errors. Missing C++ compiler or development libraries might be the cause.
• On macOS, ensure Xcode Command Line Tools are installed: xcode-select --install.
• Try cleaning the build cache and reinstalling: pip cache purge then re-run setup.sh or manually run the llama-cpp-python install command from the setup script.

Issue: Model download fails with authentication errors.

Solution:

• Make sure you are logged into Hugging Face CLI: huggingface-cli login.
• Visit the model's page on Hugging Face (URLs are provided during setup) and accept any terms or request access if required.
• Re-run setup.sh to attempt the download again.

Issue: Slow performance with local models, especially on Mac.

Solution:

• This is expected, particularly on Apple Silicon due to memory bandwidth limitations compared to high-end NVIDIA GPUs.
• Ensure N_GPU_LAYERS in config.yaml is set to an optimized value (setup script provides recommendations). More layers offloaded generally means better performance, up to the limit of your VRAM/Unified Memory.
• Consider using a smaller local model (e.g., Mistral 7B) or switching to a cloud model (Gemini/Claude) via config.yaml for better speed.

Issue: Application crashes or throws errors related to API keys.

Solution:

• Double-check that your API keys in the .env file are correct and have the necessary permissions/billing enabled on the provider's platform (Anthropic/Google AI Studio).
• Ensure the keys are correctly formatted in the .env file (e.g., GEMINI_API_KEY="your_key_here").

Issue: Web browsing fails or gets stuck (timeouts, CAPTCHAs).

Solution:

• Increase BROWSER_NAVIGATION_TIMEOUT in config.yaml if pages load slowly.
• Ensure USE_CAPTCHA_SOLVER is enabled if you frequently encounter CAPTCHAs (requires additional setup for the solver service).
• Some websites employ sophisticated anti-bot measures that Playwright (even with patches) may not bypass. The agent might need to rely on other tools or search results in such cases.

Issue: Errors related to MCP tools.

Solution:

• Check the terminal logs for errors originating from the specific MCP server process.
• Ensure the command defined in mcp.json for that server is correct and the necessary dependencies are installed.
• Verify the tool is enabled in config.yaml under the tools: section.