Utilities & Helpers
Relevant source files
The following files were used as context for generating this wiki page:
The "Utilities & Helpers" module provides essential cross-cutting functionality that powers the browser automation, LLM integration, and deep research capabilities of the project. It serves as the architectural backbone for model instantiation, file management, state tracking, and specialized search workflows. By centralizing these helper functions, the project maintains a clean separation between the user interface and the underlying execution logic.
These utilities handle critical tasks such as managing API keys for diverse LLM providers, capturing browser screenshots for visual analysis, and orchestrating complex iterative search patterns. They ensure that the AI agents have access to the necessary tools to interact with web environments effectively and report findings in a structured manner.
LLM Factory and Provider Management
The project implements a centralized factory pattern for instantiating Large Language Models across multiple providers. This system abstracts provider-specific configuration details and provides a unified interface for the agents.
LLM Instantiation Logic
The get_llm_model function acts as the primary entry point for model creation. it supports a wide array of providers including OpenAI, Anthropic, Google, DeepSeek, and local instances via Ollama. It dynamically handles API key retrieval from environment variables or UI inputs.
Sources: src/utils/utils.py:27-147, src/utils/llm.py:46-118
Supported Providers and Models
The system maintains a registry of predefined models to assist with UI configuration and model selection.
| Provider | Default/Key Models | Environment Variable |
|---|---|---|
| OpenAI | gpt-4o, gpt-4, gpt-3.5-turbo | OPENAI_API_KEY |
| Anthropic | claude-3-5-sonnet, claude-3-opus | ANTHROPIC_API_KEY |
| DeepSeek | deepseek-chat, deepseek-reasoner | DEEPSEEK_API_KEY |
| gemini-2.0-flash, gemini-1.5-pro | GOOGLE_API_KEY | |
| Ollama | qwen2.5, llama2, deepseek-r1 | N/A (Local) |
Sources: src/utils/utils.py:150-161, src/utils/utils.py:29-34
Special Model Handling: DeepSeek-R1
Specialized classes DeepSeekR1ChatOpenAI and DeepSeekR1ChatOllama are implemented to handle the unique output format of "reasoning" models. These helpers extract the reasoning content (thoughts) from the final response content.
The diagram shows how the system bifurcates response processing based on whether the model provides a hidden "thought" chain.
Sources: src/utils/llm.py:48-118
Browser & System Utilities
These utilities facilitate the interaction between the AI agent and the physical browser environment, including visual feedback and artifact management.
Screenshot and Visual Capture
The capture_screenshot utility interacts with the Playwright browser context to generate JPEG representations of the current page. This is used for both the "Live View" in the UI and the vision capabilities of the LLM.
Sources: src/utils/utils.py:202-243
File and Artifact Tracking
The system tracks generated artifacts such as session recordings (.webm) and execution traces (.zip). The get_latest_files helper identifies the most recent completion artifacts to present them to the user.
Sources: src/utils/utils.py:182-201
Deep Research Orchestration
The deep research utility is a high-level helper that orchestrates multiple agent iterations to perform exhaustive web investigations.
Research Workflow
The deep_research function implements a loop that involves planning, multi-query execution, and information recording.
The sequence diagram illustrates the iterative nature of the deep research utility, showing the interaction between the research orchestrator and specialized extraction tools.
Sources: src/utils/deep_research.py:38-164
Reporting and Data Persistence
The generate_final_report utility processes the history_infos collected during research to produce a publication-ready Markdown document. It ensures all sources are cited and formatted correctly.
Sources: src/utils/deep_research.py:176-251
Agent State and Configuration Helpers
The project utilizes state management helpers to allow the UI to communicate with long-running background tasks.
AgentState Management
The AgentState class (referenced in webui.py and src/utils/agent_state.py) provides a thread-safe way to request stops or pauses in agent execution. This is critical for the "Stop" button functionality in the WebUI.
Sources: webui.py:44-93, src/agent/custom_agent.py:284-290
Configuration Persistence
Utilities are provided to save and load UI configurations using .pkl files. This allows users to persist their LLM settings, browser dimensions, and default prompts across sessions.
Sources: webui.py:595-645
Summary
Utilities & Helpers form the foundation of the Web UI repository, providing the necessary abstractions for LLM communication, file handling, and complex research workflows. By centralizing logic in src/utils/utils.py and specialized modules like src/utils/deep_research.py, the system achieves high modularity and support for a wide range of AI models and browser configurations.