<img src="https://github.com/OEvortex/llm4free/blob/main/logo.svg" alt="LLM4Free Logo">

LLM4Free

Formerly WebScout — Your All-in-One Python Toolkit for Web Search, AI Interaction, Digital Utilities, and More

Access diverse search engines, cutting-edge AI models, temporary communication tools, media utilities, developer helpers, and powerful CLI interfaces -- all through one unified library.








<a href="https://pypi.org/project/llm4free/"><img src="https://img.shields.io/pypi/v/llm4free.svg?style=flat-square&logo=pypi&label=PyPI" alt="PyPI Version"></a>
<a href="https://pepy.tech/project/llm4free"><img src="https://static.pepy.tech/badge/llm4free/month?style=flat-square" alt="Monthly Downloads"></a>
<a href="https://pepy.tech/project/llm4free"><img src="https://static.pepy.tech/badge/llm4free?style=flat-square" alt="Total Downloads"></a>
<a href="#"><img src="https://img.shields.io/pypi/pyversions/llm4free?style=flat-square&logo=python" alt="Python Version"></a>
<a href="https://deepwiki.com/OEvortex/LLM4Free"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>

Table of Contents

• Features
• Installation
• Quick Start
• CLI
• AI Chat Providers
• Search Engines
• Text-to-Image
• Text-to-Speech
• OpenAI-Compatible API Server
• Python Client
• Tool Calling
• Model Registry
• Developer Tools
• Documentation
• Contributing
• License

[!IMPORTANT] LLM4Free uses a single unified OpenAI-compatible interface for all providers. Every provider implements client.chat.completions.create(...) — identical to the OpenAI Python SDK.

[!NOTE] LLM4Free supports 40+ AI providers including: HeckAI, ChatGPT, Groq, DeepInfra, Nvidia, Sambanova, OpenRouter, HuggingFace, OllamaSwarm, and many more.

<a href="https://t.me/OEvortexAI"><img alt="Telegram Group" src="https://img.shields.io/badge/Telegram%20Group-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white"></a>
<a href="https://youtube.com/@OEvortex"><img alt="YouTube" src="https://img.shields.io/badge/YouTube-FF0000?style=for-the-badge&logo=youtube&logoColor=white"></a>
<a href="https://buymeacoffee.com/oevortex"><img alt="Buy Me A Coffee" src="https://img.shields.io/badge/Buy%20Me%20A%20Coffee-FFDD00?style=for-the-badge&logo=buymeacoffee&logoColor=black"></a>

Features

Search & AI

• Multi-Engine Search -- DuckDuckGo, Bing, Brave, Yahoo, Mojeek, Wikipedia. (Search Docs)
• 40+ AI Providers -- All OpenAI-compatible for easy switching. (Architecture)
• AI-Powered Search -- Perplexity, IAsk, Monica, AyeSoul, WebPilotAI.
• OpenAI-Compatible API Server -- Serve any LLM4Free provider via OpenAI endpoints. (Server Docs)
• Unified Python Client -- Auto-failover chat and image generation. (Client Docs)

Media & Content

• Text-to-Image -- PollinationsAI, Together, Miragic, MagicStudio. (TTI Docs)
• Text-to-Speech -- ElevenLabs, Deepgram, OpenAI FM, Parler, Qwen, MurfAI, and more. (Model Registry)
• Speech-to-Text -- ElevenLabs STT.
• YouTube Toolkit -- Video downloads, transcription, API access. (Docs)
• Weather Tools -- Detailed weather info with ASCII display. (Weather Docs)

Developer Tools

• SwiftCLI -- Elegant CLI framework. (SwiftCLI Docs)
• Scout -- HTML parser and web crawler. (Scout Docs)
• LitPrinter -- Styled console output. (LitPrinter Docs)
• LitAgent -- User-agent rotation and IP toolkit. (LitAgent Docs)
• GitAPI -- GitHub data extraction without auth. (GitAPI Docs)
• GGUF Conversion -- Quantize HuggingFace models to GGUF. (GGUF Docs)
• ZeroArt -- Zero-dependency ASCII art generator. (ZeroArt Docs)
• Utility Decorators -- @timeIt and @retry helpers. (Decorator Docs)
• Stream Sanitization -- SSE/HTTP stream processing. (Sanitize Docs)

Privacy & Utilities

• Temp Mail -- Disposable email via Emailnator, MailTM, TempMailIO.
• Proxy Manager -- Automatic proxy rotation. (Architecture)
• Awesome Prompts -- Curated system prompts for AI personas. (Prompts Docs)

Installation

pip (Standard)

pip install -U llm4free

# With API server support
pip install -U "llm4free[api]"

# With development tools
pip install -U "llm4free[dev]"

uv (Recommended)

uv add llm4free

# Run without installing
uv run llm4free --help

# Install as global tool
uv tool install llm4free

Docker

docker pull OEvortex/llm4free:latest
docker run -it OEvortex/llm4free:latest

See docs/DOCKER.md for full Docker deployment options including compose profiles.

Quick Start

AI Chat (No API Key)

from llm4free.Provider.Openai_comp.heckai import HeckAI

client = HeckAI()
response = client.chat.completions.create(
    model="google/gemini-2.5-flash-preview",
    messages=[{"role": "user", "content": "Explain quantum computing in simple terms"}],
)
print(response.choices[0].message.content)

Web Search

from llm4free import DuckDuckGoSearch

search = DuckDuckGoSearch()
results = search.text("best practices for API design", max_results=5)
for result in results:
    print(f"{result['title']}: {result['href']}")

Image Generation

from llm4free.Provider.TTI import PollinationsAI

gen = PollinationsAI()
path = gen.generate_image(prompt="A serene mountain landscape at sunset")
print(f"Saved to: {path}")

See docs/getting-started.md for the full quick-start guide.

Command Line Interface

LLM4Free provides a rich CLI powered by Rich with multi-engine support.

llm4free --help                       # List all commands
llm4free version                      # Show version
llm4free text -k "python programming" # DuckDuckGo search (default)
llm4free images -k "mountains"        # Image search
llm4free news -k "AI breakthrough" -t w  # News from last week
llm4free weather -l "New York"        # Weather info
llm4free translate -k "Hola" --to en  # Translation

Supported Engines

# Use a specific engine
llm4free text -k "climate change" -e bing
llm4free text -k "quantum physics" -e wikipedia

Full CLI reference: docs/cli.md

AI Chat Providers

All providers use the OpenAI-compatible interface (client.chat.completions.create(...)).

Free Providers (No Auth Required)

from llm4free.Provider.Openai_comp.heckai import HeckAI
from llm4free.Provider.Openai_comp.artingai import ArtingAI
from llm4free.Provider.Openai_comp.freeai import FreeAI

# HeckAI - multiple models
client = HeckAI()
response = client.chat.completions.create(
    model="google/gemini-2.5-flash-preview",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

# ArtingAI
client = ArtingAI()
response = client.chat.completions.create(
    model="gpt-5",
    messages=[{"role": "user", "content": "Hello!"}],
)

Authenticated Providers

from llm4free.Provider.Openai_comp.Auth.groq import Groq
from llm4free.Provider.Openai_comp.Auth.deepinfra import DeepInfra

groq = Groq(api_key="your-key")
response = groq.chat.completions.create(
    model="llama-3.3-70b-versatile",
    messages=[{"role": "user", "content": "Write a Python function to sort a list"}],
)
print(response.choices[0].message.content)

Streaming

from llm4free.Provider.Openai_comp.heckai import HeckAI

client = HeckAI()
stream = client.chat.completions.create(
    model="google/gemini-2.5-flash-preview",
    messages=[{"role": "user", "content": "Tell me a joke"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

See llm4free/llm/ for all available provider implementations.

Search Engines

from llm4free import DuckDuckGoSearch, BingSearch, YahooSearch, BraveSearch

# DuckDuckGo
ddg = DuckDuckGoSearch()
results = ddg.text("python frameworks", max_results=5)

# Bing
bing = BingSearch()
results = bing.text("climate change solutions")

# Brave
brave = BraveSearch()
results = brave.text("machine learning tutorials")

Search docs: docs/search.md

Text-to-Image

from llm4free.Provider.TTI import PollinationsAI, TogetherImage

# PollinationsAI
poll = PollinationsAI()
poll.generate_image(prompt="A cyberpunk city at night")

# Together AI
together = TogetherImage()
together.generate_image(prompt="A robot playing chess")

TTI docs: docs/getting-started.md#image-generation

Text-to-Speech

from llm4free.Provider.TTS import ElevenlabsTTS, ParlerTTS

tts = ElevenlabsTTS()
tts.text_to_speech("Hello, world!", voice="alloy")

TTS model registry: docs/models.md

OpenAI-Compatible API Server

Run a local FastAPI server that serves any LLM4Free provider through standard OpenAI endpoints.

# Start the server
llm4free-server

# Custom config
llm4free-server --port 8080 --host 0.0.0.0 --debug

Use with the OpenAI Python Client

from openai import OpenAI

client = OpenAI(api_key="dummy", base_url="http://localhost:8000/v1")

response = client.chat.completions.create(
    model="ChatGPT/gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

Docker Deployment

docker-compose up llm4free-api
docker-compose -f docker-compose.yml -f docker-compose.no-auth.yml up llm4free-api

Full server docs: docs/openai-api-server.md | Docker: docs/DOCKER.md

Python Client

The unified Client class provides auto-failover across providers with smart model resolution.

from llm4free.client import Client

client = Client(print_provider_info=True)

# Auto provider + model selection
resp = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Summarize LLM4Free."}]
)
print(resp.choices[0].message.content)

# Streaming
stream = client.chat.completions.create(
    model="ChatGPT/gpt-4o-mini",
    messages=[{"role": "user", "content": "Write a limerick about Python."}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

# Image generation
img = client.images.generate(prompt="A neon owl", model="auto", size="1024x1024")
print(img.data[0].url)

Client docs: docs/client.md

Tool Calling

LLM4Free has a built-in tool calling system that works with any provider.

from llm4free.Provider.Openai_comp.heckai import HeckAI
from llm4free.Provider.Openai_comp.base import Tool

def get_weather(city: str) -> str:
    return f"Weather in {city}: Sunny, 25C"

weather_tool = Tool(
    name="get_weather",
    description="Get current weather for a city.",
    parameters={"city": {"type": "string", "description": "City name."}},
    implementation=get_weather,
)

client = HeckAI(tools=[weather_tool])
response = client.chat.completions.create(
    model="google/gemini-2.5-flash-preview",
    messages=[{"role": "user", "content": "What is the weather in London?"}],
)
print(response.choices[0].message.content)

Tool calling docs: docs/tool-calling.md

Model Registry

Enumerate available models across all providers.

```python from llm4