The Problem

Enterprises that need a self‑hosted AI assistant face two friction points: (1) most “local” projects still require cloud APIs or paid inference services, and (2) wiring a browser‑automation layer, code execution sandbox, and voice I/O together is non‑trivial. The result is a DIY stack that is brittle, insecure, and hard to maintain.

What This Does

agenticSeek delivers a single‑repo, Docker‑driven stack that runs entirely on‑premises. The Python core in sources/ defines a hierarchy of agents (sources/agents/*_agent.py) that select the appropriate tool (browser, code executor, planner, etc.) and invoke a local LLM via sources/llm_provider.py. The web UI lives in frontend/agentic-seek-front/ (React) and talks to the Flask API in llm_server/app.py. All prompts are version‑controlled under prompts/.

Key files:

  • cli.py – CLI entry point that bootstraps the agent system.
  • llm_server/app.py – Flask server exposing /process endpoints used by the UI.
  • sources/browser.py – Chrome driver setup, random user‑agent generation, and SSL bypass logic.
  • sources/tools/tools.py – Central configuration helper (high import count).

How It Is Wired

Execution typically starts at cli.py → main() (line 20). main orchestrates a session, persisting state via save_session → save_memory (filesystem writes). Core processing routes through sources/agents/agent.py (28 functions, 7 callers) which delegates to the appropriate subclass (browser_agent, code_agent, etc.).

From agent.py the flow hits:

  1. load_prompt and get_model_name in llm_provider.py (model selection).
  2. process → llm_request (calls the LLM inference function; 10+ calls).
  3. UI feedback functions pretty_print (called 35 times) and animate_thinking (11 times) in utility.py – the two highest‑blast‑radius modules (18 and 10 dependents respectively).

Network I/O occurs in:

  • sources/tools/BashInterpreter.py → link_valid (uses requests.get).
  • sources/browser.py → Chrome driver interactions (outbound HTTP).

File I/O occurs in:

  • sources/memory.py (loads/saves conversation context).
  • sources/speech_to_text.py (open without context manager – a leak risk).

The Docker composition (docker-compose.yml) builds three images: backend (Dockerfile.backend), frontend (frontend/Dockerfile.frontend), and the LLM router (llm_router/). The Flask app runs with debug=True (exposes full traceback).

No circular imports were detected; the import graph contains 58 modules and 118 edges, with sources/utility.py and sources/tools/tools.py acting as hubs. Changing either module has the widest impact (18 and 12 dependent modules).

How To Use It

# 1. Clone the exact repo
git clone https://github.com/moses-y/agenticSeek
cd agenticSeek

# 2. Install Python deps (if running without Docker)
pip install -r requirements.txt   # uses pip, Python 3.10 recommended
#   or, for the backend container
docker compose build backend

# 3. Prepare environment
cp .env.example .env               # edit as needed (e.g., model path, ports)

# 4. Start all services
docker compose up --build          # brings up backend, frontend, and searxng

# 5. Run the CLI (optional, bypasses UI)
python cli.py

The UI is served at http://localhost:3000 (React) and talks to the Flask API at http://localhost:5000. The CLI uses the same backend endpoints internally.

Real‑World Use

A product team can embed agenticSeek in an internal knowledge‑base portal. When a user asks “Generate a release‑notes summary for version 2.3”, the CLI (or UI) invokes the planner agent, which calls the code agent to run a diff script, then the browser agent to fetch the latest changelog page, and finally returns a spoken summary via text_to_speech.py. All data stays on the corporate network, eliminating external data leakage.

Code Health & Issues

  • High – No CI – 58 source files, no workflow (.github/ empty). Add a GitHub Actions pipeline that runs docker compose build and the Python test suite on each push.
  • High – No build gate – docker-compose.yml ships deployable images without validation. Add a workflow that builds each Dockerfile and runs a sanity check (e.g., docker run --rm <image> --help).
  • High – Debug mode enabled – llm_server/app.py runs app.run(debug=True). Switch to an env‑driven flag (DEBUG=os.getenv("DEBUG")=="1").
  • Medium – Dependabot missing – Four manifest files (requirements.txt, package.json, pyproject.toml, Dockerfiles) lack automated version updates. Add .github/dependabot.yml.
  • Medium – Base image not pinned – Dockerfile.backend uses python:3.11-slim. Pin to a digest to guarantee reproducible builds.
  • Medium – Runs as root – No USER directive in Dockerfile.backend. Create a non‑root user and set appropriate file ownership.

Additional static findings (not duplicated): deep nesting (max depth 6 in several agent files), duplicated 6‑line blocks across scripts, oversized sources/browser.py (688 lines), and broad exception handling in planner_agent.py and api.py.

The Bottom Line

agenticSeek provides a functional, fully‑local AI assistant with a ready‑made Docker stack, making it attractive for privacy‑sensitive environments. However, the codebase lacks basic production safeguards (CI, hardened containers, debug lockdown) and contains several maintainability hotspots. It is suitable for teams comfortable with tightening the DevOps pipeline and refactoring the high‑impact utility modules.