OEvortex/llm4free — Gitpedia

<div align="center"> <a href="https://github.com/OEvortex/llm4free"> <picture>  <source media="(prefers-color-scheme: dark)" srcset="https://github.com/OEvortex/llm4free/blob/main/logo.svg" style="background-color: #f8f9fa; padding: 12px; border-radius: 6px; display: inline-block;">  <img src="https://github.com/OEvortex/llm4free/blob/main/logo.svg" alt="LLM4Free Logo"> </picture> </a> <a href="https://github.com/OEvortex/llm4free"> <img src="https://img.shields.io/badge/LLM4Free-All--in--One%20Toolkit-blue?style=for-the-badge&logo=python&logoColor=white" alt="LLM4Free Logo"> </a> <h1>LLM4Free</h1> <p><strong>Formerly WebScout — Your All-in-One Python Toolkit for Web Search, AI Interaction, Digital Utilities, and More</strong></p> <p> Access diverse search engines, cutting-edge AI models, temporary communication tools, media utilities, developer helpers, and powerful CLI interfaces -- all through one unified library. </p>  <p> <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> </p> </div> <hr/>

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

<hr/>

[!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.

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)

<hr/>

Installation

pip (Standard)

bash
pip install -U llm4free

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

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

uv (Recommended)

bash
uv add llm4free

# Run without installing
uv run llm4free --help

# Install as global tool
uv tool install llm4free

Docker

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

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

<hr/>

Quick Start

AI Chat (No API Key)

python
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

python
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

python
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.

<hr/>

Command Line Interface

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

bash
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

Category	Engines
`text`	`ddg`, `bing`, `brave`, `yahoo`, `mojeek`, `wikipedia`
`images`	`ddg`, `bing`, `brave`, `yahoo`
`videos`	`ddg`, `brave`, `yahoo`
`news`	`ddg`, `bing`, `brave`, `yahoo`
`suggestions`	`ddg`, `bing`, `brave`, `yahoo`
`weather`	`ddg`, `yahoo`
`answers`	`ddg`
`translate`	`ddg`
`maps`	`ddg`

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

Full CLI reference: docs/cli.md

<hr/>

AI Chat Providers

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

Free Providers (No Auth Required)

python
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

python
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

python
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.

<hr/>

Search Engines

python
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

<hr/>

Text-to-Image

python
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

<hr/>

Text-to-Speech

python
from llm4free.Provider.TTS import ElevenlabsTTS, ParlerTTS

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

TTS model registry: docs/models.md

<hr/>

OpenAI-Compatible API Server

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

bash
# Start the server
llm4free-server

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

Use with the OpenAI Python Client

python
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

bash
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

<hr/>

Python Client

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

python
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

<hr/>

Tool Calling

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

python
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

<hr/>

Model Registry

Enumerate available models across all providers.

python
from llm4free import model

# All LLM models
all_models = model.llm.list()
print(f"Total: {len(all_models)}")

# Models by provider
summary = model.llm.summary()
for provider, count in summary.items():
    print(f"  {provider}: {count}")

# TTS voices
voices = model.tts.list()
print(f"Total voices: {len(voices)}")

Model registry docs: docs/models.md

<hr/>

Developer Tools

Tool	Description	Docs
SwiftCLI	CLI framework with decorators	docs/swiftcli.md
Scout	HTML parser & web crawler	docs/scout.md
LitPrinter	Styled debug printing	docs/litprinter.md
LitAgent	User-agent rotation	docs/litagent.md
GitAPI	GitHub data extraction	docs/gitapi.md
GGUF	Model conversion & quantization	docs/gguf.md
ZeroArt	ASCII art generator	docs/zeroart.md
Weather	Weather toolkit	docs/weather.md
Decorators	`@timeIt` and `@retry`	docs/decorators.md
Sanitize	Stream sanitization	docs/sanitize.md
Prompts	System prompt manager	docs/awesome-prompts.md

<hr/>

Documentation

Resource	Description
Getting Started	Installation, first chat, web search, image generation
Architecture	System design, layers, and data flows
CLI Reference	All CLI commands and options
Python Client	Unified client with auto-failover
API Server	OpenAI-compatible FastAPI server
Model Registry	Enumerate LLM, TTS, TTI models
Tool Calling	Function calling with any provider
Search Docs	Multi-engine search API
Scout	HTML parser and crawler
Provider Development	Create custom providers
Deployment	Production deployment guide
Docker	Docker setup and compose profiles
Inferno	Local LLM server
Troubleshooting	Common issues and solutions
Contributing	How to contribute
Provider Modules	All provider implementations
Docs Hub	Full documentation index