# convergence-ai/proxy-lite architecture

> Architecture diagram of the GitHub repository convergence-ai/proxy-lite, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/convergence-ai/proxy-lite
- Repository: https://github.com/convergence-ai/proxy-lite

## Overview

##### Project Type and Purpose
- Proxy Lite is a mini, lightweight autonomous assistant (a “proxy”) that automates tasks by interacting with web environments. It supports both CLI- and web UI–based usage.
- Its main objective is to process user commands (e.g., “Book a table…”) and autonomously complete tasks (such as web browsing and tool usage) by running a loop between a solver, agent, and environment.
- It uses a modular, pluggable architecture with components for agents, environments, solvers, and tools.

##### Analyzing the File Structure
- The top-level directories and files include configuration files (.gitignore, Makefile, pyproject.toml), assets (images, demo gifs), and the main source code within the “src/proxy_lite” folder.
- Inside “src/proxy_lite” you find subdirectories:
- agents: Contains base agent code with “agent_base.py” and a specific “proxy_lite_agent.py”.
- browser: Manages web interaction (and includes JavaScript files for custom browser interaction and DOM element extraction).
- environments: Provides base classes and a web browser–specific environment (using Playwright, with stealth functionalities).
- solvers: Implements task-solving logic with a “simple_solver” as well as base interfaces.
- tools: Contains definitions for available tools (like BrowserTool and ReturnValueTool).
- Additional modules include configurations, logging, history handling, serialization, and command-line interface (cli.py).
- The project uses a Runner (in “runner.py”) that sets up and continuously cycles through tasks in a manner reminiscent of reinforcement learning (as described in the README).

##### Components and Their Relationships
- CLI and Web UI: The entry points into the system (e.g., “proxy” CLI command, “make app” for the web UI). This is where user tasks are initiated.
- Runner: The central orchestrator that initializes the configuration (using RunnerConfig) and starts a loop that ties together the solver and environment.
- Solver: Implements the decision-making logic. It selects the appropriate agent based on the task and interacts with it.
- Agent: The brain that interprets the task by building up a message history (with roles such as system and user) and then triggers actions (tool calls).
- Environment: For example, the webbrowser environment (which uses Playwright) where real-world actions (like clicking, typing) take place. It provides feedback (observations) back to the agent.
- Tools: Modules such as BrowserTool and ReturnValueTool define the set of actions available. They encapsulate functionality to interact with the external environment.
- Client / API Server Connection: Proxy Lite can be used to interact with a remote model endpoint (via vLLM and HuggingFace spaces). This involves preparing messages and handling model responses.
- Logger, Serializer, Recorder, and other supportive modules: They handle logging, data serialization (ensuring compatibility with OpenAI’s protocol), and recording interactions, thereby providing traceability through the cycle.

##### Architectural Patterns and Technologies
- Modularity: Each functional area (agent, solver, environment, tools) is encapsulated in its own module or package, making the system easily extendable.
- Pluggability: Use of configuration files (like the default.yaml) allows swapping out or configuring components (e.g., using a different environment or model endpoint).
- Reinforcement Learning Style Loop: The Runner sets off a continuous cycle (observe, think, act) similar to RL environments.
- Integration of Web Tools: The browser environment integrates with Playwright and injects custom JavaScript to enhance interaction reliability.
- The system also interfaces directly with external tools and APIs (like the vLLM server and HuggingFace endpoints) while ensuring a clear message format for communication.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface"
        CLI["CLI"] 
    end

    %% Core Processing Layer
    subgraph "Core Processing"
        Runner["Runner"]
        subgraph "Solvers"
            solverBase["Solver Base"]
            simpleSolver["Simple Solver"]
        end
        subgraph "Agents"
            agentBase["Agent Base"]
            proxyAgent["Proxy Lite Agent"]
        end
    end

    %% External Interaction Layer
    subgraph "External Interaction"
        subgraph "Environment & Tools"
            subgraph "Environment"
                envBase["Environment Base"]
                webEnv["Web Browser Environment"]
            end
            subgraph "Tools"
                toolBase["Tool Base"]
                browserTool["Browser Tool"]
                returnTool["Return Value Tool"]
            end
            subgraph "Browser"
                browserJS["Browser Interaction (Browser)"]
                customSelect["Custom Select JS"]
                findPOIs["Find POIs JS"]
                boundingBoxes["Bounding Boxes"]
            end
        end
        client["Client/API Connector"]
    end

    %% Support Modules Layer
    subgraph "Support Modules"
        logger["Logger"]
        serializer["Serializer"]
        recorder["Recorder"]
        config["Configurations"]
    end

    %% Connections
    CLI -->|"sends_command"| Runner

    Runner -->|"calls_solver"| simpleSolver
    simpleSolver -->|"uses_base"| solverBase

    simpleSolver -->|"delegates_to"| proxyAgent
    proxyAgent -->|"relies_on"| agentBase

    proxyAgent -->|"triggers"| browserTool
    proxyAgent -->|"triggers"| returnTool

    browserTool -->|"invokes"| webEnv
    returnTool -->|"invokes"| webEnv

    webEnv -->|"returns_obs"| proxyAgent

    Runner -->|"requests_API"| client

    Runner -->|"logs_to"| logger
    Runner -->|"serializes_with"| serializer
    Runner -->|"records_in"| recorder
    Runner -->|"reads_config"| config

    webEnv -->|"integrates_with"| browserJS
    browserJS -->|"includes"| customSelect
    browserJS -->|"includes"| findPOIs
    browserJS -->|"includes"| boundingBoxes

    %% Styles: Classes and Colors
    classDef ui fill:#f9c,stroke:#333,stroke-width:2px;
    classDef core fill:#ccf,stroke:#333,stroke-width:2px;
    classDef external fill:#cfc,stroke:#333,stroke-width:2px;
    classDef support fill:#ffc,stroke:#333,stroke-width:2px;

    class CLI ui;
    class Runner,solverBase,simpleSolver,agentBase,proxyAgent core;
    class envBase,webEnv,toolBase,browserTool,returnTool,browserJS,customSelect,findPOIs,boundingBoxes,client external;
    class logger,serializer,recorder,config support;

    %% Click Events
    click CLI "https://github.com/convergence-ai/proxy-lite/blob/main/src/proxy_lite/cli.py"
    click Runner "https://github.com/convergence-ai/proxy-lite/blob/main/src/proxy_lite/runner.py"
    click solverBase "https://github.com/convergence-ai/proxy-lite/blob/main/src/proxy_lite/solvers/solver_base.py"
    click simpleSolver "https://github.com/convergence-ai/proxy-lite/blob/main/src/proxy_lite/solvers/simple_solver.py"
    click agentBase "https://github.com/convergence-ai/proxy-lite/blob/main/src/proxy_lite/agents/agent_base.py"
    click proxyAgent "https://github.com/convergence-ai/proxy-lite/blob/main/src/proxy_lite/agents/proxy_lite_agent.py"
    click envBase "https://github.com/convergence-ai/proxy-lite/blob/main/src/proxy_lite/environments/environment_base.py"
    click webEnv "https://github.com/convergence-ai/proxy-lite/blob/main/src/proxy_lite/environments/webbrowser.py"
    click toolBase "https://github.com/convergence-ai/proxy-lite/blob/main/src/proxy_lite/tools/tool_base.py"
    click browserTool "https://github.com/convergence-ai/proxy-lite/blob/main/src/proxy_lite/tools/browser_tool.py"
    click returnTool "https://github.com/convergence-ai/proxy-lite/blob/main/src/proxy_lite/tools/return_tool.py"
    click browserJS "https://github.com/convergence-ai/proxy-lite/blob/main/src/proxy_lite/browser/browser.py"
    click customSelect "https://github.com/convergence-ai/proxy-lite/blob/main/src/proxy_lite/browser/add_custom_select.js"
    click findPOIs "https://github.com/convergence-ai/proxy-lite/blob/main/src/proxy_lite/browser/find_pois.js"
    click boundingBoxes "https://github.com/convergence-ai/proxy-lite/blob/main/src/proxy_lite/browser/bounding_boxes.py"
    click client "https://github.com/convergence-ai/proxy-lite/blob/main/src/proxy_lite/client.py"
    click logger "https://github.com/convergence-ai/proxy-lite/blob/main/src/proxy_lite/logger.py"
    click serializer "https://github.com/convergence-ai/proxy-lite/blob/main/src/proxy_lite/serializer.py"
    click recorder "https://github.com/convergence-ai/proxy-lite/blob/main/src/proxy_lite/recorder.py"
    click config "https://github.com/convergence-ai/proxy-lite/blob/main/src/proxy_lite/configs/default.yaml"
```
