# xtekky/gpt4free architecture

> Architecture diagram of the GitHub repository xtekky/gpt4free, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xtekky/gpt4free
- Repository: https://github.com/xtekky/gpt4free

## Overview

GPT4Free is a multi-provider LLM and media access product, exposed through a Python client, OpenAI-compatible API, optional GUI, and MCP server. A typical client request selects a model/provider, runs through provider execution and retry/response handling, and returns generated content; provider adapters connect to external services. The README also identifies local inference, media generation, and browsing/tool capabilities. Several implementation links are supported by the SOURCE INDEX or excerpts; links for unsampled subsystems are omitted rather than inferred.

Main entry points: [`g4f/client/__init__.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/client/__init__.py) (Python Client), [`g4f/client/service.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/client/service.py) (Client Service), [`g4f/Provider/template/OpenaiTemplate.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/Provider/template/OpenaiTemplate.py) (Provider Adapters), [`g4f/providers/retry_provider.py`](https://github.com/xtekky/gpt4free/blob/main/g4f/providers/retry_provider.py) (Retry Providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_python_client["Python Client<br/>[__init__.py]"]
  node_api["OpenAI API<br/>[run.py]"]
  node_gui["Web GUI<br/>[app.py]"]
  node_mcp["MCP Server<br/>[server.py]"]
end

subgraph group_routing["Request Routing"]
  node_client_service["Client Service<br/>[service.py]"]
  node_provider_catalog["Provider Catalog<br/>[__init__.py]"]
  node_provider_router["Provider Router<br/>[provider_router.py]"]
  node_any_provider["Any Provider<br/>[any_provider.py]"]
  node_retry["Retry Providers<br/>[retry_provider.py]"]
  node_config_provider["Config Routes<br/>[config_provider.py]"]
  node_models["Model Catalog<br/>[models.py]"]
  node_response["Response Handling<br/>[response.py]"]
  node_configuration["Configuration<br/>[config.py]"]
  node_typing["Shared Types<br/>[typing.py]"]
  node_debug["Diagnostics<br/>[debug.py]"]
end

subgraph group_providers["Provider Integrations"]
  node_base_provider["Provider Runtime<br/>[base_provider.py]"]
  node_provider_adapters["Provider Adapters<br/>[OpenaiTemplate.py]"]
  node_http["Async HTTP<br/>[aiohttp.py]"]
  node_local_inference["Local Inference"]
  node_cookies["Credentials and Cookies<br/>[cookies.py]"]
end

subgraph group_capabilities["Media and Tools"]
  node_agent_tools["Agent Tools<br/>[AgentTools.py]"]
  node_media["Media Generation<br/>[__init__.py]"]
  node_media_persistence["Media Persistence<br/>[copy_images.py]"]
  node_browsing["Web Browsing<br/>[browse.py]"]
end

node_user(("Application User"))
node_external_providers{{"External Model Services"}}

node_user -->|"requests"| node_python_client
node_user -->|"calls"| node_api
node_user -->|"uses"| node_gui
node_python_client -->|"resolves via"| node_client_service
node_client_service -->|"resolves provider"| node_provider_catalog
node_client_service -->|"checks routes"| node_config_provider
node_client_service -->|"logs selection"| node_debug
node_client_service -->|"resolves model"| node_models
node_python_client -->|"dispatches through"| node_any_provider
node_python_client -->|"uses"| node_retry
node_python_client -->|"returns"| node_response
node_provider_catalog -->|"loads"| node_provider_adapters
node_provider_router -->|"resolves providers"| node_provider_catalog
node_provider_router -->|"uses"| node_retry
node_retry -->|"invokes"| node_base_provider
node_provider_adapters -->|"implements"| node_base_provider
node_provider_adapters -.->|"requests models"| node_external_providers
node_local_inference -.->|"implements"| node_base_provider
node_python_client -->|"creates media"| node_media
node_media -->|"persists media"| node_media_persistence
node_mcp -->|"uses"| node_media
node_mcp -->|"copies media"| node_media_persistence
node_mcp -->|"uses"| node_cookies
node_python_client -->|"runs tools"| node_agent_tools
node_provider_adapters -.->|"sends requests"| node_http
node_provider_adapters -.->|"uses credentials"| node_cookies
node_browsing -.->|"searches web"| node_external_providers
node_python_client -->|"uses schemas"| node_typing
node_retry -->|"reads settings"| node_configuration

click node_python_client "https://github.com/xtekky/gpt4free/blob/main/g4f/client/__init__.py"
click node_client_service "https://github.com/xtekky/gpt4free/blob/main/g4f/client/service.py"
click node_api "https://github.com/xtekky/gpt4free/blob/main/g4f/api/run.py"
click node_gui "https://github.com/xtekky/gpt4free/blob/main/g4f/gui/server/app.py"
click node_mcp "https://github.com/xtekky/gpt4free/blob/main/g4f/mcp/server.py"
click node_provider_catalog "https://github.com/xtekky/gpt4free/blob/main/g4f/Provider/__init__.py"
click node_provider_router "https://github.com/xtekky/gpt4free/blob/main/g4f/providers/provider_router.py"
click node_any_provider "https://github.com/xtekky/gpt4free/blob/main/g4f/providers/any_provider.py"
click node_retry "https://github.com/xtekky/gpt4free/blob/main/g4f/providers/retry_provider.py"
click node_config_provider "https://github.com/xtekky/gpt4free/blob/main/g4f/providers/config_provider.py"
click node_base_provider "https://github.com/xtekky/gpt4free/blob/main/g4f/providers/base_provider.py"
click node_provider_adapters "https://github.com/xtekky/gpt4free/blob/main/g4f/Provider/template/OpenaiTemplate.py"
click node_agent_tools "https://github.com/xtekky/gpt4free/blob/main/g4f/Provider/AgentTools.py"
click node_models "https://github.com/xtekky/gpt4free/blob/main/g4f/models.py"
click node_response "https://github.com/xtekky/gpt4free/blob/main/g4f/providers/response.py"
click node_http "https://github.com/xtekky/gpt4free/blob/main/g4f/requests/aiohttp.py"
click node_media "https://github.com/xtekky/gpt4free/blob/main/g4f/image/__init__.py"
click node_media_persistence "https://github.com/xtekky/gpt4free/blob/main/g4f/image/copy_images.py"
click node_browsing "https://github.com/xtekky/gpt4free/blob/main/g4f/browsing/browse.py"
click node_local_inference "https://github.com/xtekky/gpt4free/tree/main/g4f/Provider/local"
click node_cookies "https://github.com/xtekky/gpt4free/blob/main/g4f/cookies.py"
click node_configuration "https://github.com/xtekky/gpt4free/blob/main/g4f/config.py"
click node_typing "https://github.com/xtekky/gpt4free/blob/main/g4f/typing.py"
click node_debug "https://github.com/xtekky/gpt4free/blob/main/g4f/debug.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_python_client,node_api,node_gui,node_mcp,node_user toneBlue
class node_client_service,node_provider_catalog,node_provider_router,node_any_provider,node_retry,node_config_provider,node_models,node_response,node_configuration,node_typing,node_debug toneAmber
class node_base_provider,node_provider_adapters,node_http,node_local_inference,node_cookies toneMint
class node_agent_tools,node_media,node_media_persistence,node_browsing toneRose
class node_external_providers toneIndigo
```

## Components

### User Interfaces

- [Python Client](https://github.com/xtekky/gpt4free/blob/main/g4f/client/__init__.py): `g4f/client/__init__.py`
- [OpenAI API](https://github.com/xtekky/gpt4free/blob/main/g4f/api/run.py): `g4f/api/run.py`
- [Web GUI](https://github.com/xtekky/gpt4free/blob/main/g4f/gui/server/app.py): `g4f/gui/server/app.py`
- [MCP Server](https://github.com/xtekky/gpt4free/blob/main/g4f/mcp/server.py): `g4f/mcp/server.py`

### Request Routing

- [Client Service](https://github.com/xtekky/gpt4free/blob/main/g4f/client/service.py): `g4f/client/service.py`
- [Provider Catalog](https://github.com/xtekky/gpt4free/blob/main/g4f/Provider/__init__.py): `g4f/Provider/__init__.py`
- [Provider Router](https://github.com/xtekky/gpt4free/blob/main/g4f/providers/provider_router.py): `g4f/providers/provider_router.py`
- [Any Provider](https://github.com/xtekky/gpt4free/blob/main/g4f/providers/any_provider.py): `g4f/providers/any_provider.py`
- [Retry Providers](https://github.com/xtekky/gpt4free/blob/main/g4f/providers/retry_provider.py): `g4f/providers/retry_provider.py`
- [Config Routes](https://github.com/xtekky/gpt4free/blob/main/g4f/providers/config_provider.py): `g4f/providers/config_provider.py`
- [Model Catalog](https://github.com/xtekky/gpt4free/blob/main/g4f/models.py): `g4f/models.py`
- [Response Handling](https://github.com/xtekky/gpt4free/blob/main/g4f/providers/response.py): `g4f/providers/response.py`
- [Configuration](https://github.com/xtekky/gpt4free/blob/main/g4f/config.py): `g4f/config.py`
- [Shared Types](https://github.com/xtekky/gpt4free/blob/main/g4f/typing.py): `g4f/typing.py`
- [Diagnostics](https://github.com/xtekky/gpt4free/blob/main/g4f/debug.py): `g4f/debug.py`

### Provider Integrations

- [Provider Runtime](https://github.com/xtekky/gpt4free/blob/main/g4f/providers/base_provider.py): `g4f/providers/base_provider.py`
- [Provider Adapters](https://github.com/xtekky/gpt4free/blob/main/g4f/Provider/template/OpenaiTemplate.py): `g4f/Provider/template/OpenaiTemplate.py`
- [Async HTTP](https://github.com/xtekky/gpt4free/blob/main/g4f/requests/aiohttp.py): `g4f/requests/aiohttp.py`
- [Local Inference](https://github.com/xtekky/gpt4free/tree/main/g4f/Provider/local): `g4f/Provider/local`
- [Credentials and Cookies](https://github.com/xtekky/gpt4free/blob/main/g4f/cookies.py): `g4f/cookies.py`

### Media and Tools

- [Agent Tools](https://github.com/xtekky/gpt4free/blob/main/g4f/Provider/AgentTools.py): `g4f/Provider/AgentTools.py`
- [Media Generation](https://github.com/xtekky/gpt4free/blob/main/g4f/image/__init__.py): `g4f/image/__init__.py`
- [Media Persistence](https://github.com/xtekky/gpt4free/blob/main/g4f/image/copy_images.py): `g4f/image/copy_images.py`
- [Web Browsing](https://github.com/xtekky/gpt4free/blob/main/g4f/browsing/browse.py): `g4f/browsing/browse.py`

### Other components

- **Application User**
- **External Model Services**

## Connections

- Application User → Python Client: requests (evidence: `README.md`)
- Application User → OpenAI API: calls (evidence: `README.md`)
- Application User → Web GUI: uses (evidence: `README.md`)
- Python Client → Client Service: resolves via (evidence: `g4f/client/__init__.py`)
- Client Service → Provider Catalog: resolves provider (evidence: `g4f/client/service.py`)
- Client Service → Config Routes: checks routes (evidence: `g4f/client/service.py`)
- Client Service → Diagnostics: logs selection (evidence: `g4f/client/service.py`)
- Client Service → Model Catalog: resolves model (evidence: `g4f/client/service.py`)
- Python Client → Any Provider: dispatches through (evidence: `g4f/client/__init__.py`)
- Python Client → Retry Providers: uses (evidence: `g4f/client/__init__.py`)
- Python Client → Response Handling: returns (evidence: `g4f/client/__init__.py`)
- Provider Catalog → Provider Adapters: loads (evidence: `g4f/Provider/__init__.py`)
- Provider Router → Provider Catalog: resolves providers (evidence: `g4f/providers/provider_router.py`)
- Provider Router → Retry Providers: uses (evidence: `g4f/providers/provider_router.py`)
- Retry Providers → Provider Runtime: invokes (evidence: `g4f/providers/retry_provider.py`)
- Provider Adapters → Provider Runtime: implements
- Provider Adapters → External Model Services: requests models
- Local Inference → Provider Runtime: implements
- Python Client → Media Generation: creates media (evidence: `g4f/client/__init__.py`)
- Media Generation → Media Persistence: persists media (evidence: `g4f/image/copy_images.py`)
- MCP Server → Media Generation: uses (evidence: `g4f/mcp/server.py`)
- MCP Server → Media Persistence: copies media (evidence: `g4f/mcp/server.py`)
- MCP Server → Credentials and Cookies: uses (evidence: `g4f/mcp/server.py`)
- Python Client → Agent Tools: runs tools (evidence: `g4f/client/__init__.py`)
- Provider Adapters → Async HTTP: sends requests
- Provider Adapters → Credentials and Cookies: uses credentials
- Web Browsing → External Model Services: searches web
- Python Client → Shared Types: uses schemas (evidence: `g4f/client/__init__.py`)
- Retry Providers → Configuration: reads settings (evidence: `g4f/providers/retry_provider.py`)
