stephane.david/agenticSeek
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

I've enhanced the README to make it easier for you to get started.

Browse Source 
Here's a summary of the key improvements:
- **Clearer Structure:** I've added new sections for Prerequisites, ChromeDriver Installation, Configuration, and Troubleshooting. I also suggested a Table of Contents.
- **Detailed Prerequisites:** I've explicitly listed all necessary software (Git, Python 3.10.x, Docker Engine & Compose, Chrome) with links and version recommendations.
- **Comprehensive ChromeDriver Guide:** I've consolidated instructions for version matching, downloading from official sources (Chrome for Testing), and PATH setup for all major operating systems.
- **Python Environment:** I've recommended `python3.10 -m venv` and provided OS-specific activation commands.
- **Installation Scripts & Manual Steps:** I've clarified script actions and potential issues (e.g., `pyaudio` on Windows) and streamlined manual installation instructions.
- **Local LLM Setup:** I've added detailed guides for installing Ollama and LM-Studio, pulling/downloading models (with examples), and configuring `config.ini` (including `http://` prefix for server addresses).
- **API LLM Setup:** I've provided thorough instructions for setting API keys as environment variables on Linux/macOS (including shell profile persistence) and Windows (temporary and permanent methods). I've also added example API key links.
- **Expanded `config.ini` Explanation:** I've offered more detailed descriptions for each configuration key, especially `work_dir`.
- **Improved Provider Tables:** I've restructured local and API provider tables for better clarity and linked to setup sections.
- **Enhanced Troubleshooting:**
    - I've updated 'Known Issues' for ChromeDriver, LM-Studio connections, and SearxNG URL (with Windows `export` alternatives).
    - I've transformed "Q: I get an error running cli.py" in FAQ into a comprehensive step-by-step troubleshooting guide.
    - I've added new FAQs for installing local LLM providers, acquiring models, setting API keys on Windows, and handling installation script failures.
- **Consistency:** I've ensured consistent terminology (e.g., "ChromeDriver").
- **OS-Specific Instructions:** I've provided clear, distinct commands and guidance for Linux, macOS, and Windows where necessary.

These changes aim to make your initial setup and troubleshooting process smoother and more accessible.
This commit is contained in:
google-labs-jules[bot]
2025-05-30 09:31:22 +00:00
parent 8d15546771
commit e235aecbc1
1 changed files with 454 additions and 175 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+449 -170
View File
@@ -36,11 +36,22 @@ Disclaimer: This demo, including all the files that appear (e.g: CV_candidates.z
## Installation
Make sure you have chrome driver, docker and python3.10 installed.
This section guides you through installing AgenticSeek. Please follow the steps carefully.
We highly advice you use exactly python3.10 for the setup. Dependencies error might happen otherwise.
### **Prerequisites**
For issues related to chrome driver, see the **Chromedriver** section.
Before you begin, ensure you have the following software installed:
* **Git:** For cloning the repository. [Download Git](https://git-scm.com/downloads)
* **Python 3.10.x:** We strongly recommend using Python version 3.10.x. Using other versions might lead to dependency errors. [Download Python 3.10](https://www.python.org/downloads/release/python-3100/) (pick a 3.10.x version).
* **Docker Engine & Docker Compose:** For running bundled services like SearxNG.
* Install Docker Desktop (which includes Docker Compose V2): [Windows](https://docs.docker.com/desktop/install/windows-install/) | [Mac](https://docs.docker.com/desktop/install/mac-install/) | [Linux](https://docs.docker.com/desktop/install/linux-install/)
* Alternatively, install Docker Engine and Docker Compose separately on Linux: [Docker Engine](https://docs.docker.com/engine/install/) | [Docker Compose](https://docs.docker.com/compose/install/) (ensure you install Compose V2, e.g., `sudo apt-get install docker-compose-plugin`).
* **Google Chrome:** The web browser used for autonomous browsing tasks. [Download Chrome](https://www.google.com/chrome/).
* **ChromeDriver:** The WebDriver for Chrome. This is crucial for browser automation.
* **Important:** Your ChromeDriver version *must* match your installed Google Chrome version. See the [ChromeDriver Installation](#chromedriver-installation) subsection for detailed instructions.
For issues related to ChromeDriver after attempting installation, see the [Known Issues](#chromedriver-issues) section.
### 1️⃣ **Clone the repository and setup**
@@ -50,78 +61,163 @@ cd agenticSeek
mv .env.example .env
```
### 2️ **Create a virtual env**
### 2️ **Create a Python Virtual Environment**
It's highly recommended to use a virtual environment to manage project dependencies.
```sh
python3 -m venv agentic_seek_env
# Ensure you are using Python 3.10 for creating the environment
python3.10 -m venv agentic_seek_env
# Or if 'python3.10' is not found, try 'python3 -m venv agentic_seek_env'
# but verify version with 'python --version' inside the activated environment.
# Activate the virtual environment
source agentic_seek_env/bin/activate
# On Windows: agentic_seek_env\Scripts\activate
# On Windows PowerShell: .\agentic_seek_env\Scripts\Activate.ps1
# On Windows CMD: agentic_seek_env\Scripts\activate.bat
```
### 3️⃣ **Install package**
### 3️⃣ **Install Dependencies**
Ensure Python, Docker and docker compose, and Google chrome are installed.
This step includes installing Python packages and setting up ChromeDriver.
We recommand Python 3.10.0.
#### **ChromeDriver Installation**
**Automatic Installation (Recommanded):**
1. **Check your Chrome Version:** Open Google Chrome, go to `Settings -> About Chrome` to find your version (e.g., 120.0.6099.110).
2. **Download ChromeDriver:**
* For Chrome version 115 or newer, download from [Chrome for Testing (CfT) JSON Endpoints](https://googlechromelabs.github.io/chrome-for-testing/). Find the stable version matching your Chrome's major version.
* For older versions (not recommended), you might find them on the [ChromeDriver downloads page](https://chromedriver.chromium.org/downloads).
3. **Install ChromeDriver:**
* **Linux/macOS:** Download the appropriate zip file, extract `chromedriver`, and move it to a directory in your system's PATH (e.g., `/usr/local/bin`). Ensure it's executable (`chmod +x /usr/local/bin/chromedriver`).
* **Windows:** Download the zip file, extract `chromedriver.exe`, and place it in a directory included in your system's PATH (e.g., `C:\Windows\System32` or a dedicated scripts folder that you've added to PATH).
* Alternatively, you can place `chromedriver` (or `chromedriver.exe`) directly in the root of the `agenticSeek` project directory. The application will try to find it there.
For Linux/Macos:
#### **Python Packages & System Dependencies**
**Automatic Installation (Recommended):**
The following scripts attempt to install system dependencies (like `portaudio`) and Python packages from `requirements.txt`.
* **Linux/macOS:**
```sh
./install.sh
```
For windows:
* **Windows:**
```sh
./install.bat
```
*Note for Windows:* The batch script will attempt to install `pyaudio`. This may require "Microsoft Visual C++ 14.0 or greater". If `pyaudio` installation fails, you might need to install it manually via a wheel file or install PortAudio first. See manual Windows instructions below.
**Manually:**
**Manual Installation:**
**Note: For any OS, ensure the ChromeDriver you install matches your installed Chrome version. Run `google-chrome --version`. See known issues if you have chrome >135**
If automatic installation fails or you prefer manual setup:
- *Linux*:
* **All Operating Systems:**
1. Ensure your virtual environment is active.
2. Install Python packages:
```sh
pip3 install -r requirements.txt
```
Update Package List: `sudo apt update`
* **Linux Specific System Dependencies:**
```sh
sudo apt update
sudo apt install -y alsa-utils portaudio19-dev python3-pyaudio libgtk-3-dev libnotify-dev libgconf-2-4 libnss3 libxss1
```
*(Note: `python3-pyaudio` might be handled by `pip install` if `portaudio19-dev` is present).*
Install Dependencies: `sudo apt install -y alsa-utils portaudio19-dev python3-pyaudio libgtk-3-dev libnotify-dev libgconf-2-4 libnss3 libxss1`
* **macOS Specific System Dependencies:**
```sh
brew update
brew install portaudio # For pyaudio
# ChromeDriver should be handled by the dedicated ChromeDriver Installation step above.
# `brew install --cask chromedriver` can also work but ensure version compatibility.
```
Install ChromeDriver matching your Chrome browser version:
`sudo apt install -y chromium-chromedriver`
* **Windows Specific System Dependencies:**
1. `pip install pyreadline3` (usually part of `requirements.txt`)
2. **PortAudio for PyAudio:**
* `pyaudio` (for voice functionality) requires PortAudio. If `pip install pyaudio` (from `requirements.txt`) fails:
* Try installing from a pre-compiled wheel: Find a `pyaudio` wheel compatible with your Python version (3.10) and system architecture from sites like [Christoph Gohlke's Python Libraries page](https://www.lfd.uci.edu/~gohlke/pythonlibs/#pyaudio). Download the `.whl` file and install with `pip install PyAudio‑XYZ.whl`.
* Alternatively, install PortAudio via a package manager like [vcpkg](https://vcpkg.io/en/index.html) or by [building from source](http://files.portaudio.com/docs/v19-doxydocs/compile_windows.html), then try `pip install pyaudio` again.
Install requirements: `pip3 install -r requirements.txt`
---
## Configuration (`config.ini`)
- *Macos*:
Before running AgenticSeek, you need to configure it by editing the `config.ini` file. This file is created when you run `mv .env.example .env` during the initial setup.
Update brew : `brew update`
Install chromedriver : `brew install --cask chromedriver`
Install portaudio: `brew install portaudio`
Upgrade pip : `python3 -m pip install --upgrade pip`
Upgrade wheel : : `pip3 install --upgrade setuptools wheel`
Install requirements: `pip3 install -r requirements.txt`
- *Windows*:
Install pyreadline3 `pip install pyreadline3`
Install portaudio manually (e.g., via vcpkg or prebuilt binaries) and then run: `pip install pyaudio`
Download and install chromedriver manually from: https://sites.google.com/chromium.org/driver/getting-started
Place chromedriver in a directory included in your PATH.
Install requirements: `pip3 install -r requirements.txt`
Key settings are explained in the [Config Section](#config) later in this README. For now, be aware that you'll need to update it based on whether you're running an LLM locally or via an API.
---
## Running AgenticSeek
Choose one of the following setups based on how you want to run the Large Language Model (LLM).
## Setup for running LLM locally on your machine
This setup allows you to run AgenticSeek with an LLM hosted entirely on your own hardware, ensuring privacy.
**Hardware Requirements:**
Running LLMs locally requires significant hardware resources. Refer to the [FAQ: What hardware do I need?](#faq) for detailed model performance and hardware recommendations (minimum 8GB VRAM GPU, 12GB+ recommended).
**1. Install a Local LLM Provider:**
You need software to serve the LLM locally. Popular choices:
* **Ollama:**
* **Installation:** Download and install Ollama from [ollama.ai](https://ollama.ai/).
* **Homepage:** [https://ollama.ai/](https://ollama.ai/)
* **LM-Studio:**
* **Installation:** Download and install LM-Studio from [lmstudio.ai](https://lmstudio.ai/).
* **Homepage:** [https://lmstudio.ai/](https://lmstudio.ai/)
* **OpenAI-Compatible Server (e.g., llama.cpp, vLLM):**
* These are more advanced setups. You'll need to follow their respective documentation to start a server that exposes an OpenAI-compatible API.
* Example: [llama.cpp server documentation](https://github.com/ggerganov/llama.cpp/tree/master/examples/server)
**2. Download/Select a Model:**
Once your provider is installed, download a model. We recommend reasoning models like *Qwen* or *Deepseek*.
* **For Ollama:**
```sh
ollama pull deepseekcoder:6.7b # Example: deepseek-coder 6.7B
ollama pull qwen:14b # Example: Qwen 14B
# List available models with `ollama list`
```
* **For LM-Studio:** Use the UI to search for and download models.
* **For OpenAI-Compatible Servers:** Configure the server to use your desired model.
**3. Start Your Local LLM Provider:**
* **Ollama:**
```sh
ollama serve
```
(This often runs automatically after installation on some systems).
* **LM-Studio:** Start the application and use its UI to load a model and start the server.
* **OpenAI-Compatible Server:** Follow its specific instructions to start the server.
**4. Update `config.ini`:**
Modify your `config.ini` file:
```ini
[MAIN]
is_local = True
provider_name = ollama # Or lm-studio, openai (for compatible local servers)
provider_model = deepseekcoder:6.7b # Or the model you downloaded/selected for your provider
provider_server_address = http://127.0.0.1:11434 # Default for Ollama. For LM-Studio, usually http://127.0.0.1:1234. Adjust if needed.
# ... other settings ...
```
* **Important:**
* For `lm-studio` or other OpenAI-compatible local servers, ensure `provider_server_address` includes the `http://` prefix and the correct port.
* If using LM-Studio, set `provider_name = lm-studio`, not `openai`.
* If using a generic OpenAI-compatible local server, set `provider_name = openai`.
See the table of [Local Providers](#list-of-local-providers) below for a summary.
**Hardware Requirements:**
To run LLMs locally, you'll need sufficient hardware. At a minimum, a GPU capable of running Qwen/Deepseek 14B is required. See the FAQ for detailed model/performance recommendations.
@@ -147,7 +243,7 @@ See the **FAQ** at the end of the README for required hardware.
is_local = True # Whenever you are running locally or with remote provider.
provider_name = ollama # or lm-studio, openai, etc..
provider_model = deepseek-r1:14b # choose a model that fit your hardware
provider_server_address = 127.0.0.1:11434
provider_server_address = http://127.0.0.1:11434 # Default for Ollama. Use http://127.0.0.1:1234 for LM-Studio.
agent_name = Jarvis # name of your AI
recover_last_session = True # whenever to recover the previous session
save_session = True # whenever to remember the current session
@@ -161,56 +257,90 @@ headless_browser = True # Whenever to use headless browser, recommanded only if
stealth_mode = True # Use undetected selenium to reduce browser detection
```
Warning: Do *NOT* set provider_name to `openai` if using LM-studio for running LLMs. Set it to `lm-studio`.
**List of local providers** (summary)
Note: Some provider (eg: lm-studio) require you to have `http://` in front of the IP. For example `http://127.0.0.1:1234`
| Provider | Local? | `provider_name` in `config.ini` | Description |
|-----------|--------|---------------------------------|------------------------------------------------------------------|
| Ollama | Yes | `ollama` | Run LLMs locally with ease using Ollama. |
| LM-Studio | Yes | `lm-studio` | Run LLMs locally with LM-Studio's UI and server. |
| OpenAI Compatible API | Yes | `openai` | Use a local server (e.g., llama.cpp, vLLM) that mimics the OpenAI API. |
**List of local providers**
Next step: [Start services and run AgenticSeek](#start-services-and-run)
| Provider | Local? | Description |
|-----------|--------|-----------------------------------------------------------|
| ollama | Yes | Run LLMs locally with ease using ollama as a LLM provider |
| lm-studio | Yes | Run LLM locally with LM studio (set `provider_name` to `lm-studio`)|
| openai | Yes | Use openai compatible API (eg: llama.cpp server) |
Next step: [Start services and run AgenticSeek](#Start-services-and-Run)
*See the **Known issues** section if you are having issues*
*See the **Run with an API** section if your hardware can't run deepseek locally*
*See the **Config** section for detailled config file explanation.*
*See the [Troubleshooting](#troubleshooting) section if you are having issues.*
*If your hardware can't run LLMs locally, see [Setup to run with an API](#setup-to-run-with-an-api).*
*For detailed `config.ini` explanations, see [Config Section](#config).*
---
## Setup to run with an API
Set the desired provider in the `config.ini`. See below for a list of API providers.
This setup uses external, cloud-based LLM providers. You'll need an API key from your chosen service.
**1. Choose an API Provider and Get an API Key:**
Refer to the [List of API Providers](#list-of-api-providers) below. Visit their websites to sign up and obtain an API key.
**2. Set Your API Key as an Environment Variable:**
AgenticSeek expects the API key to be available as an environment variable.
* **Linux/macOS:**
Open your terminal and use the `export` command. It's best to add this to your shell's profile file (e.g., `~/.bashrc`, `~/.zshrc`) for persistence.
```sh
export PROVIDER_API_KEY="your_api_key_here"
# Replace PROVIDER_API_KEY with the specific variable name, e.g., OPENAI_API_KEY, GOOGLE_API_KEY
```
Example for TogetherAI:
```sh
export TOGETHER_API_KEY="xxxxxxxxxxxxxxxxxxxxxx"
```
* **Windows:**
* **Command Prompt (Temporary for current session):**
```cmd
set PROVIDER_API_KEY=your_api_key_here
```
* **PowerShell (Temporary for current session):**
```powershell
$env:PROVIDER_API_KEY="your_api_key_here"
```
* **Permanently:** Search for "environment variables" in the Windows search bar, click "Edit the system environment variables," then click the "Environment Variables..." button. Add a new User variable with the appropriate name (e.g., `OPENAI_API_KEY`) and your key as the value.
*(See FAQ: [How do I set API keys?](#how-do-i-set-api-keys) for more details).*
**3. Update `config.ini`:**
```ini
[MAIN]
is_local = False
provider_name = google
provider_model = gemini-2.0-flash
provider_server_address = 127.0.0.1:5000 # doesn't matter
provider_name = openai # Or google, deepseek, togetherAI, huggingface
provider_model = gpt-3.5-turbo # Or gemini-1.5-flash, deepseek-chat, mistralai/Mixtral-8x7B-Instruct-v0.1 etc.
provider_server_address = # Typically ignored or can be left blank when is_local = False for most APIs
# ... other settings ...
```
Warning: Make sure there is not trailing space in the config.
*Warning:* Make sure there are no trailing spaces in the `config.ini` values.
Export your API key: `export <<PROVIDER>>_API_KEY="xxx"`
**List of API Providers**
Example: export `TOGETHER_API_KEY="xxxxx"`
| Provider | `provider_name` | Local? | Description | API Key Link (Examples) |
|--------------|-----------------|--------|---------------------------------------------------|---------------------------------------------|
| OpenAI | `openai` | No | Use ChatGPT models via OpenAI's API. | [platform.openai.com/signup](https://platform.openai.com/signup) |
| Google Gemini| `google` | No | Use Google Gemini models via Google AI Studio. | [aistudio.google.com/keys](https://aistudio.google.com/keys) |
| Deepseek | `deepseek` | No | Use Deepseek models via their API. | [platform.deepseek.com](https://platform.deepseek.com) |
| Hugging Face | `huggingface` | No | Use models from Hugging Face Inference API. | [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) |
| TogetherAI | `togetherAI` | No | Use various open-source models via TogetherAI API.| [api.together.ai/settings/api-keys](https://api.together.ai/settings/api-keys) |
**List of API providers**
*Note:*
* We advise against using `gpt-4o` or other OpenAI models for complex web browsing and task planning as current prompt optimizations are geared towards models like Deepseek.
* Coding/bash tasks might encounter issues with Gemini, as it may not strictly follow formatting prompts optimized for Deepseek.
* The `provider_server_address` in `config.ini` is generally not used when `is_local = False` as the API endpoint is usually hardcoded in the respective provider's library.
| Provider | Local? | Description |
|-----------|--------|-----------------------------------------------------------|
| openai | Depends | Use ChatGPT API |
| deepseek | No | Deepseek API (non-private) |
| huggingface| No | Hugging-Face API (non-private) |
| togetherAI | No | Use together AI API (non-private) |
| google | No | Use google gemini API (non-private) |
Next step: [Start services and run AgenticSeek](#start-services-and-run)
*We advice against using gpt-4o or other closedAI models*, performance are poor for web browsing and task planning.
*See the [Troubleshooting](#troubleshooting) section if you are having issues.*
*For detailed `config.ini` explanations, see [Config Section](#config).*
---
Please also note that coding/bash might fail with gemini, it seem to ignore our prompt for format to respect, which are optimized for deepseek r1.
@@ -224,20 +354,36 @@ Next step: [Start services and run AgenticSeek](#Start-services-and-Run)
## Start services and Run
Activate your python env if needed.
Activate your Python virtual environment if it's not already active:
```sh
# Linux/macOS
source agentic_seek_env/bin/activate
# Windows PowerShell
.\agentic_seek_env\Scripts\Activate.ps1
# Windows CMD
agentic_seek_env\Scripts\activate.bat
```
Start required services. This will start all services from the docker-compose.yml, including:
- searxng
- redis (required by searxng)
- frontend
Start required background services using Docker Compose. This will launch:
- SearxNG (local meta-search engine)
- Redis (database for SearxNG)
- Frontend (web interface, if you choose to use it)
```sh
sudo ./start_services.sh # MacOS
start ./start_services.cmd # Window
# For Linux (if your user is not in the docker group, sudo might be required for docker commands)
./start_services.sh
# or if you need sudo for Docker: sudo ./start_services.sh
# For macOS (sudo is typically not required if Docker Desktop is correctly installed)
./start_services.sh
# For Windows
start ./start_services.cmd
# This will open a new command prompt window for the services.
```
*Troubleshooting service start:* If these scripts fail, ensure Docker Engine is running and Docker Compose (V2, `docker compose`) is correctly installed. Check the output in the terminal for error messages. See [FAQ: Help! I get an error when running AgenticSeek or its scripts.](#faq-troubleshooting)
**Options 1:** Run with the CLI interface.
@@ -390,88 +536,94 @@ Example config:
is_local = True
provider_name = ollama
provider_model = deepseek-r1:32b
provider_server_address = 127.0.0.1:11434
provider_server_address = http://127.0.0.1:11434 # Example for Ollama; use http://127.0.0.1:1234 for LM-Studio
agent_name = Friday
recover_last_session = False
save_session = False
speak = False
listen = False
work_dir = /Users/mlg/Documents/ai_folder
work_dir = /Users/mlg/Documents/ai_folder # IMPORTANT: Update this to a valid path on your system
jarvis_personality = False
languages = en zh
languages = en zh # List of languages for TTS and potentially routing.
[BROWSER]
headless_browser = False
stealth_mode = False
```
**Explanation**:
**Explanation of `config.ini` Settings**:
- is_local -> Runs the agent locally (True) or on a remote server (False).
- provider_name -> The provider to use (one of: `ollama`, `server`, `lm-studio`, `deepseek-api`)
- provider_model -> The model used, e.g., deepseek-r1:32b.
- provider_server_address -> Server address, e.g., 127.0.0.1:11434 for local. Set to anything for non-local API.
- agent_name -> Name of the agent, e.g., Friday. Used as a trigger word for TTS.
- recover_last_session -> Restarts from last session (True) or not (False).
- save_session -> Saves session data (True) or not (False).
- speak -> Enables voice output (True) or not (False).
- listen -> listen to voice input (True) or not (False).
- work_dir -> Folder the AI will have access to. eg: /Users/user/Documents/.
- jarvis_personality -> Uses a JARVIS-like personality (True) or not (False). This simply change the prompt file.
- languages -> The list of supported language, needed for the llm router to work properly, avoid putting too many or too similar languages.
- headless_browser -> Runs browser without a visible window (True) or not (False).
- stealth_mode -> Make bot detector time harder. Only downside is you have to manually install the anticaptcha extension.
- languages -> List of supported languages. Required for agent routing system. The longer the languages list the more model will be downloaded.
* **`[MAIN]` Section:**
* `is_local`: `True` if using a local LLM provider (Ollama, LM-Studio, local OpenAI-compatible server) or the self-hosted server option. `False` if using a cloud-based API (OpenAI, Google, etc.).
* `provider_name`: Specifies the LLM provider.
* Local options: `ollama`, `lm-studio`, `openai` (for local OpenAI-compatible servers), `server` (for the self-hosted server setup).
* API options: `openai`, `google`, `deepseek`, `huggingface`, `togetherAI`.
* `provider_model`: The specific model name or ID for the chosen provider (e.g., `deepseekcoder:6.7b` for Ollama, `gpt-3.5-turbo` for OpenAI API, `mistralai/Mixtral-8x7B-Instruct-v0.1` for TogetherAI).
* `provider_server_address`: The address of your LLM provider.
* For local providers: e.g., `http://127.0.0.1:11434` for Ollama, `http://127.0.0.1:1234` for LM-Studio.
* For the `server` provider type: The address of your self-hosted LLM server (e.g., `http://your_server_ip:3333`).
* For cloud APIs (`is_local = False`): This is often ignored or can be left blank, as the API endpoint is usually handled by the client library.
* `agent_name`: Name of the AI assistant (e.g., Friday). Used as a trigger word for speech-to-text if enabled.
* `recover_last_session`: `True` to attempt to restore the previous session's state, `False` to start fresh.
* `save_session`: `True` to save the current session's state for potential recovery, `False` otherwise.
* `speak`: `True` to enable text-to-speech voice output, `False` to disable.
* `listen`: `True` to enable speech-to-text voice input (CLI mode only), `False` to disable.
* `work_dir`: **Crucial:** The directory where AgenticSeek will read/write files. **Ensure this path is valid and accessible on your system.**
* `jarvis_personality`: `True` to use a more "Jarvis-like" system prompt (experimental), `False` for the standard prompt.
* `languages`: A comma-separated list of languages (e.g., `en, zh, fr`). Used for TTS voice selection (defaults to the first) and can assist the LLM router. Avoid too many or very similar languages for router efficiency.
* **`[BROWSER]` Section:**
* `headless_browser`: `True` to run the automated browser without a visible window (recommended for web interface or non-interactive use). `False` to show the browser window (useful for CLI mode or debugging).
* `stealth_mode`: `True` to enable measures to make browser automation harder to detect. May require manual installation of browser extensions like anticaptcha.
---
## Providers
The table below show the available providers:
This section summarizes the supported LLM provider types. Configure them in `config.ini`.
| Provider | Local? | Description |
|-----------|--------|-----------------------------------------------------------|
| ollama | Yes | Run LLMs locally with ease using ollama as a LLM provider |
| server | Yes | Host the model on another machine, run your local machine |
| lm-studio | Yes | Run LLM locally with LM studio (`lm-studio`) |
| openai | Depends | Use ChatGPT API (non-private) or openai compatible API |
| deepseek-api | No | Deepseek API (non-private) |
| huggingface| No | Hugging-Face API (non-private) |
| togetherAI | No | Use together AI API (non-private) |
| google | No | Use google gemini API (non-private) |
**Local Providers (Run on Your Own Hardware):**
To select a provider change the config.ini:
| Provider Name in `config.ini` | `is_local` | Description | Setup Section |
|-------------------------------|------------|-----------------------------------------------------------------------------|------------------------------------------------------------------|
| `ollama` | `True` | Use Ollama to serve local LLMs. | [Setup for running LLM locally](#setup-for-running-llm-locally-on-your-machine) |
| `lm-studio` | `True` | Use LM-Studio to serve local LLMs. | [Setup for running LLM locally](#setup-for-running-llm-locally-on-your-machine) |
| `openai` (for local server) | `True` | Connect to a local server that exposes an OpenAI-compatible API (e.g., llama.cpp). | [Setup for running LLM locally](#setup-for-running-llm-locally-on-your-machine) |
| `server` | `False` | Connect to the AgenticSeek self-hosted LLM server running on another machine. | [Setup to run the LLM on your own server](#setup-to-run-the-llm-on-your-own-server) |
```
is_local = True
provider_name = ollama
provider_model = deepseek-r1:32b
provider_server_address = 127.0.0.1:5000
```
`is_local`: should be True for any locally running LLM, otherwise False.
**API Providers (Cloud-Based):**
`provider_name`: Select the provider to use by it's name, see the provider list above.
| Provider Name in `config.ini` | `is_local` | Description | Setup Section |
|-------------------------------|------------|--------------------------------------------------|-----------------------------------------------------|
| `openai` | `False` | Use OpenAI's official API (e.g., GPT-3.5, GPT-4). | [Setup to run with an API](#setup-to-run-with-an-api) |
| `google` | `False` | Use Google's Gemini models via API. | [Setup to run with an API](#setup-to-run-with-an-api) |
| `deepseek` | `False` | Use Deepseek's official API. | [Setup to run with an API](#setup-to-run-with-an-api) |
| `huggingface` | `False` | Use Hugging Face Inference API. | [Setup to run with an API](#setup-to-run-with-an-api) |
| `togetherAI` | `False` | Use TogetherAI's API for various open models. | [Setup to run with an API](#setup-to-run-with-an-api) |
`provider_model`: Set the model to use by the agent.
---
## Troubleshooting
`provider_server_address`: can be set to anything if you are not using the server provider.
If you encounter issues, this section provides guidance.
# Known issues
# Known Issues
## Chromedriver Issues
## ChromeDriver Issues
**Known error #1:** *chromedriver mismatch*
**Error Example:** `SessionNotCreatedException: Message: session not created: This version of ChromeDriver only supports Chrome version XXX`
* **Cause:** Your installed ChromeDriver version is incompatible with your Google Chrome browser version.
* **Solution:**
1. **Check Chrome Version:** Open Google Chrome, go to `Settings > About Chrome` to find your version (e.g., "Version 120.0.6099.110").
2. **Download Matching ChromeDriver:**
* For Chrome versions 115 and newer: Go to the [Chrome for Testing (CfT) JSON Endpoints](https://googlechromelabs.github.io/chrome-for-testing/). Find the "stable" channel and download the ChromeDriver for your OS that matches your Chrome's major version.
* For older versions (less common): You might find them on the [ChromeDriver - WebDriver for Chrome](https://chromedriver.chromium.org/downloads) page.
* The image below shows an example from the CfT page:
![Download Chromedriver specific version from Chrome for Testing page](./media/chromedriver_readme.png)
3. **Install ChromeDriver:**
* Ensure the downloaded `chromedriver` (or `chromedriver.exe` on Windows) is placed in a directory listed in your system's PATH environment variable (e.g., `/usr/local/bin` on Linux/macOS, or a custom scripts folder added to PATH on Windows).
* Alternatively, place it in the root directory of the `agenticSeek` project.
* Make sure the driver is executable (e.g., `chmod +x chromedriver` on Linux/macOS).
4. Refer to the [ChromeDriver Installation](#chromedriver-installation) section in the main Installation guide for more details.
If this section is incomplete or you encounter other ChromeDriver issues, please consider searching existing [GitHub Issues](https://github.com/Fosowl/agenticSeek/issues) or raising a new one.
`Exception: Failed to initialize browser: Message: session not created: This version of ChromeDriver only supports Chrome version 113
Current browser version is 134.0.6998.89 with binary path`
@@ -495,52 +647,179 @@ If this section is incomplete please raise an issue.
## connection adapters Issues
```
Exception: Provider lm-studio failed: HTTP request failed: No connection adapters were found for '127.0.0.1:11434/v1/chat/completions'
Exception: Provider lm-studio failed: HTTP request failed: No connection adapters were found for '127.0.0.1:1234/v1/chat/completions'` (Note: port may vary)
```
Make sure you have `http://` in front of the provider IP address :
* **Cause:** The `provider_server_address` in `config.ini` for `lm-studio` (or other similar local OpenAI-compatible servers) is missing the `http://` prefix or is pointing to the wrong port.
* **Solution:**
* Ensure the address includes `http://`. LM-Studio typically defaults to `http://127.0.0.1:1234`.
* Correct `config.ini`: `provider_server_address = http://127.0.0.1:1234` (or your actual LM-Studio server port).
`provider_server_address = http://127.0.0.1:11434`
## SearxNG base URL must be provided
## SearxNG Base URL Not Provided
```
raise ValueError("SearxNG base URL must be provided either as an argument or via the SEARXNG_BASE_URL environment variable.")
ValueError: SearxNG base URL must be provided either as an argument or via the SEARXNG_BASE_URL environment variable.
ValueError: SearxNG base URL must be provided either as an argument or via the SEARXNG_BASE_URL environment variable.`
```
Maybe you didn't move `.env.example` as `.env` ? You can also export SEARXNG_BASE_URL:
* **Cause:** The `.env` file is missing or the `SEARXNG_BASE_URL` variable is not set within it.
* **Solution:**
1. Ensure you have copied `.env.example` to `.env` in the root of the project directory (`mv .env.example .env` on Linux/macOS or `copy .env.example .env` on Windows).
2. Verify that the `.env` file contains `SEARXNG_BASE_URL="http://127.0.0.1:8080"`.
3. Alternatively (not recommended for permanent setup), you can set the environment variable in your terminal:
* Linux/macOS: `export SEARXNG_BASE_URL="http://127.0.0.1:8080"`
* Windows (CMD): `set SEARXNG_BASE_URL="http://127.0.0.1:8080"`
* Windows (PowerShell): `$env:SEARXNG_BASE_URL="http://127.0.0.1:8080"`
`export SEARXNG_BASE_URL="http://127.0.0.1:8080"`
## FAQ (Frequently Asked Questions)
## FAQ
<a name="faq-hardware"></a>
**Q: What hardware do I need to run LLMs locally?**
**Q: What hardware do I need?**
| Model Size | Minimum GPU VRAM | Performance & Capability Notes | Example GPU Tier |
|------------|------------------|------------------------------------------------------------------------------------------------|---------------------|
| ~7B | 8GB VRAM | ⚠️ **Not Recommended for Agentic Tasks:** Performance is generally poor for complex reasoning, web browsing, or planning. May work for very simple queries. Expect frequent errors or nonsensical outputs. | e.g., RTX 3050 Laptop |
| ~14B | 12GB VRAM | ✅ **Basic Usability:** Can handle simpler tasks. May struggle with extensive web browsing, complex planning, or generating very long code sequences. | e.g., RTX 3060 (12GB) |
| ~30-34B | 24GB VRAM | 🚀 **Good Performance:** Suitable for most tasks, including moderately complex web browsing and planning. Good balance of capability and resource requirements. | e.g., RTX 3090, RTX 4090 |
| 70B+ | 48GB VRAM | 💪 **Excellent Performance:** Recommended for advanced use cases, extensive research, and complex multi-step planning. Provides the most robust results. | e.g., 2x RTX 3090, A100 (40/80GB), Mac Studio M2/M3 Ultra |
| Model Size | GPU | Comment |
|-----------|--------|-----------------------------------------------------------|
| 7B | 8GB Vram | ⚠️ Not recommended. Performance is poor, frequent hallucinations, and planner agents will likely fail. |
| 14B | 12 GB VRAM (e.g. RTX 3060) | ✅ Usable for simple tasks. May struggle with web browsing and planning tasks. |
| 32B | 24+ GB VRAM (e.g. RTX 4090) | 🚀 Success with most tasks, might still struggle with task planning |
| 70B+ | 48+ GB Vram (eg. mac studio) | 💪 Excellent. Recommended for advanced use cases. |
*Notes:*
* These are general guidelines. Performance also depends on model quantization, software (e.g., Ollama, LM-Studio), and CPU/RAM speed.
* Always check the specific model card for memory recommendations.
* Using CPU for inference is possible with some setups (e.g., Ollama with smaller models) but will be significantly slower.
**Q: Why Deepseek R1 over other models?**
<a name="faq-deepseek"></a>
**Q: Why is Deepseek R1 often mentioned or recommended?**
Deepseek R1 excels at reasoning and tool use for its size. We think it’s a solid fit for our needs other models work fine, but Deepseek is our primary pick.
Deepseek models (especially their coder series) have shown strong performance in reasoning, instruction following, and tool/function calling for their size. AgenticSeek's prompts and internal logic have been tested extensively with these models. While other models can work, Deepseek often provides a good baseline experience for agentic tasks.
**Q: I get an error running `cli.py`. What do I do?**
<a name="faq-troubleshooting"></a>
**Q: Help! I get an error when running AgenticSeek or its scripts. What should I do?**
Ensure local is running (`ollama serve`), your `config.ini` matches your provider, and dependencies are installed. If none work feel free to raise an issue.
Here's a step-by-step troubleshooting guide:
**Q: Can it really run 100% locally?**
1. **Read the Error Message Carefully:** The error message itself is the most important clue. Try to understand what it's saying.
2. **Check Prerequisites & Installation:**
* **Python Version:** Are you using Python 3.10.x? Verify with `python --version` (or `python3.10 --version`) in your activated virtual environment.
* **Virtual Environment:** Is your virtual environment (`agentic_seek_env`) activated? You should see its name in your terminal prompt. If not, activate it (see [Installation](#2️-create-a-python-virtual-environment)).
* **Dependencies:** Did `pip3 install -r requirements.txt` complete without errors? If not, address those errors first. Check for missing system dependencies mentioned in the [Manual Installation](#manual-installation) section.
* **Core Software:** Are Git, Docker Engine, Docker Compose (V2, `docker compose`), and Google Chrome installed correctly?
* **ChromeDriver:** Is ChromeDriver installed, matching your Chrome version, and accessible (in PATH or project root)? See [ChromeDriver Installation](#chromedriver-installation) and [ChromeDriver Issues](#chromedriver-issues).
3. **Verify Service Status (`./start_services.sh` or `start_services.cmd`):**
* Did this script complete successfully? Review its output for any error messages (e.g., Docker not running, port conflicts).
* Are essential services like SearxNG running? Try accessing `http://localhost:8080` in your browser. If it doesn't load, the services didn't start correctly.
4. **Check `config.ini` (See [Config Section](#config) for details):**
* Is the file correctly named `config.ini` (not `config.ini.example`)?
* `provider_name`: Does it match your intended setup (e.g., `ollama`, `lm-studio`, `openai`, `google`)?
* `is_local`: `True` for local LLMs, `False` for cloud APIs.
* `provider_server_address`:
* For local LLMs: Is it correct (e.g., `http://127.0.0.1:11434` for Ollama, `http://127.0.0.1:1234` for LM-Studio)? Does it include `http://`?
* For API usage, this is usually less critical but ensure it's not misconfigured if present.
* `work_dir`: Is this set to a valid, existing directory path on your system where AgenticSeek can read/write files?
5. **Local LLM Provider Status (if `is_local = True`):**
* Is your chosen LLM provider software (Ollama, LM-Studio) running independently?
* Ollama: `ollama serve` should be active (often runs as a background service after installation). Check with `ollama list`.
* LM-Studio: The application should be open, the model loaded, and the local server started from its UI.
* Have you downloaded/pulled the specific model listed in `provider_model` in `config.ini`? (e.g., `ollama pull model-name`).
6. **API Key Setup (if `is_local = False`):**
* Is the API key correctly set as an environment variable for your current terminal session? (See [Setup to run with an API](#2-set-your-api-key-as-an-environment-variable) and [FAQ: How do I set API keys?](#how-do-i-set-api-keys)).
* Is the key itself correct and active?
7. **Consult Known Issues:** Review the [Known Issues](#known-issues) section above for solutions to common problems.
8. **Search GitHub Issues:** Check if other users have reported similar problems on the [AgenticSeek GitHub Issues page](https://github.com/Fosowl/agenticSeek/issues).
9. **Raise an Issue:** If you're still stuck, please [create a new issue](https://github.com/Fosowl/agenticSeek/issues/new/choose). Provide as much detail as possible:
* Your Operating System (e.g., Windows 11, macOS Sonoma, Ubuntu 22.04).
* Python version.
* Relevant parts of your `config.ini` (please redact API keys).
* The exact steps you took.
* The full error message and any relevant logs from the terminal.
Yes with Ollama, lm-studio or server providers, all speech to text, LLM and text to speech model run locally. Non-local options (OpenAI or others API) are optional.
<a name="faq-100-local"></a>
**Q: Can AgenticSeek really run 100% locally?**
**Q: Why should I use AgenticSeek when I have Manus?**
Yes. When configured with a local LLM provider like Ollama or LM-Studio (and `is_local = True` in `config.ini`), all core components—LLM inference, web search (via local SearxNG), speech-to-text, and text-to-speech—can run on your machine without sending data to external cloud services. Using API providers is optional.
This started as Side-Project we did out of interest about AI agents. What’s special about it is that we want to use local model and avoid APIs.
We draw inspiration from Jarvis and Friday (Iron man movies) to make it "cool" but for functionnality we take more inspiration from Manus, because that's what people want in the first place: a local manus alternative.
Unlike Manus, AgenticSeek prioritizes independence from external systems, giving you more control, privacy and avoid api cost.
<a name="faq-install-local-llm"></a>
**Q: How do I install local LLM providers like Ollama or LM-Studio?**
* **Ollama:**
1. Go to [ollama.ai](https://ollama.ai/).
2. Download the installer for your operating system (Windows, macOS, Linux).
3. Run the installer. Ollama typically sets itself up as a background service.
4. Open your terminal and you can start pulling models (e.g., `ollama pull deepseekcoder:6.7b`).
5. Run `ollama serve` if it's not already running (though it usually starts automatically).
* **LM-Studio:**
1. Go to [lmstudio.ai](https://lmstudio.ai/).
2. Download the installer for your system.
3. Install and run the application.
4. Use the LM-Studio UI to search for and download models.
5. In the "Local Server" tab, select your model and click "Start Server".
<a name="faq-get-models-local"></a>
**Q: Where do I get models (e.g., Deepseek, Qwen) for my local provider?**
* **Ollama:** Use the `ollama pull` command followed by the model name and tag. Common models can be found on [Ollama's model library](https://ollama.ai/library).
```sh
ollama pull deepseekcoder:6.7b # Pulls a specific version of Deepseek Coder
ollama pull qwen:14b # Pulls a specific version of Qwen
ollama list # Shows models you have downloaded
```
* **LM-Studio:** Use the search bar within the LM-Studio application to find models from Hugging Face and other sources. You can then download them through the UI. Ensure you download GGUF format models compatible with llama.cpp-based engines, which LM-Studio uses.
<a name="faq-set-api-keys"></a>
**Q: How do I set API keys (e.g., for OpenAI, Google) correctly?**
API keys are usually set as environment variables. This means they are variables available to the processes running in your terminal session or system-wide.
* **Linux/macOS:**
* **For the current terminal session only:**
```sh
export OPENAI_API_KEY="your_openai_api_key_here"
export GOOGLE_API_KEY="your_google_api_key_here"
# etc. for other providers
```
* **For persistence (recommended):** Add the `export` line(s) to your shell's configuration file. This file is usually:
* `~/.bashrc` (for Bash shell, common on Linux)
* `~/.zshrc` (for Zsh shell, default on newer macOS)
* `~/.profile` or `~/.bash_profile` (other common locations)
After adding the line, either source the file (e.g., `source ~/.bashrc`) or open a new terminal window for the changes to take effect.
* **Windows:**
* **Command Prompt (CMD - for current session only):**
```cmd
set OPENAI_API_KEY=your_openai_api_key_here
```
* **PowerShell (for current session only):**
```powershell
$env:OPENAI_API_KEY="your_openai_api_key_here"
```
* **Permanently (Recommended):**
1. In the Windows search bar, type "environment variables" and select "Edit the system environment variables."
2. In the System Properties window, click the "Environment Variables..." button.
3. Under "User variables" (for your account only) or "System variables" (for all users, requires admin rights), click "New...".
4. Enter the variable name (e.g., `OPENAI_API_KEY`) and the variable value (your actual API key).
5. Click OK on all windows. You may need to close and reopen any active Command Prompt or PowerShell windows for the changes to take effect.
**Important:**
* Replace `OPENAI_API_KEY`, `GOOGLE_API_KEY`, etc., with the specific environment variable name expected by the application or library for that provider. These are often found in the provider's API documentation.
* Ensure there are no extra spaces or quotes around the actual key unless they are part of the key itself.
<a name="faq-install-script-fails"></a>
**Q: What if `install.sh` or `install.bat` fails?**
If the automatic installation scripts encounter errors:
1. **Examine the Output:** Look closely at the error messages printed in the terminal. This will often tell you which step failed and why.
2. **Try Manual Installation:** Follow the [Manual Installation](#manual-installation) steps for your operating system. This gives you more control over each step and can help pinpoint the problem.
3. **System Dependencies:** Failures are often due to missing system-level dependencies required by Python packages (e.g., `portaudio-dev` for `pyaudio`). Ensure these are installed.
4. **Permissions:** On Linux/macOS, some commands within the script might require `sudo` if your user doesn't have the necessary permissions (e.g., for installing system packages).
5. If you continue to have issues, refer to the general [troubleshooting FAQ](#faq-troubleshooting).
**Q: Why should I use AgenticSeek as an alternative to other tools?**
AgenticSeek was started as a side-project driven by interest in AI agents, with a strong emphasis on:
* **Local First & Privacy:** Prioritizing the ability to run entirely on your own hardware using local LLMs, ensuring your data stays private and avoiding API costs.
* **Open Source:** Allowing for transparency, community contributions, and customization.
* **Inspired by Sci-Fi, Built for Practicality:** Drawing inspiration from concepts like Jarvis and Friday for a "cool" user experience, while focusing on practical functionalities similar to tools like Manus AI, aiming to provide a robust local alternative.
* **Control & Independence:** Giving users more control over their AI assistant by reducing dependency on external, proprietary systems.
## Contribute