Usage Guide

This guide explains how to run the CleverBee application and interact with its Chainlit-based web interface.

Running the Application

Once you have completed the installation and configured your .env file with API keys, you can run CleverBee using the provided script:

./run.sh

This script handles several things automatically:

• Detects and activates the Python virtual environment (venv/ or .venv/).
• Checks if core dependencies (like chainlit) are installed and attempts to install them if missing.
• Launches the Chainlit application.

Command-Line Arguments

You can pass arguments to the run.sh script, which will be forwarded to the underlying chainlit run command.

• No Cache: Use --no-cache to delete the LLM cache file (.langchain.db) before starting. This forces fresh results but increases API usage/cost.

  ./run.sh --no-cache

• Other Chainlit Arguments: Refer to the Chainlit documentation for other available arguments (e.g., changing the port with -p <port>).

Interacting with the Web Interface

After running the script, the Chainlit web interface will typically be available at http://localhost:8000 (check the terminal output for the exact URL).

Starting a Research Task

1. Open the web UI in your browser.
2. You'll see an input field at the bottom of the chat interface.
3. Enter your research topic or question into the input field.
4. Press Enter or click the send button.

Understanding the Interface

• Chat History: The main panel displays the conversation between you and the CleverBee agent.
• Agent Steps: As the agent works, it will output its thoughts, chosen actions (tool usage), observations from tools, and intermediate summaries. These appear as messages in the chat.
• Token Usage / Cost: If enabled in config.yaml, you'll see token counts and estimated costs associated with each LLM call, often displayed alongside agent messages or in a dedicated panel (depending on Chainlit version/layout).
• Final Report: Once the research is complete, the agent will generate and display a final comprehensive report summarizing its findings.

Tips for Effective Queries

• Be Specific: Clear, specific questions yield better results than vague ones.
• Provide Context: If necessary, provide background information or constraints for your research.
• Iterate: If the first result isn't perfect, refine your query and run the research again.

Monitoring and Output

• Terminal Logs: The terminal where you ran ./run.sh will display detailed logs based on the LOG_LEVEL set in config.yaml. This is useful for debugging.
• Log Files: Logs are also output to the .logs directory for later reference.
• Cache File: LLM calls are cached in .langchain.db (SQLite database) by default to save costs and speed up repeated queries.
• Token Tracking: Monitor token usage in the UI or logs to understand resource consumption.