Metadata-Version: 2.4
Name: llm4free
Version: 2026.7.17
Summary: Search for anything using Google, DuckDuckGo, phind.com, Contains AI models, can transcribe yt videos, temporary email and phone number generation, has TTS support, webai (terminal gpt and open interpreter) and offline LLMs and more
Author-email: OEvortex <koulabhay26@gmail.com>
License: Apache-2.0
Project-URL: Source, https://github.com/OEvortex/LLM4Free
Project-URL: Tracker, https://github.com/OEvortex/LLM4Free/issues
Project-URL: YouTube, https://youtube.com/@OEvortex
Keywords: search,ai,chatbot,llm,language-model,gpt,openai,gemini,claude,llama,search-engine,text-to-speech,tts,text-to-image,tti,weather,youtube,toolkit,utilities,web-search,duckduckgo,google,yep
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Communications
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE.md
Requires-Dist: typing_extensions>=4.0.0
Requires-Dist: curl_cffi
Requires-Dist: httpx
Requires-Dist: tqdm
Requires-Dist: packaging
Requires-Dist: nest-asyncio
Requires-Dist: colorama
Requires-Dist: rich
Requires-Dist: PyYAML
Requires-Dist: html5lib
Requires-Dist: psutil
Requires-Dist: aiohttp
Requires-Dist: litprinter
Requires-Dist: lxml>=5.2.2
Requires-Dist: pydantic
Requires-Dist: fastapi>=0.128.0
Requires-Dist: uvicorn>=0.40.0
Requires-Dist: starlette>=0.50.0
Requires-Dist: openai>=2.43.0
Requires-Dist: pytest>=9.0.2
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: tokenizers>=0.23.1
Requires-Dist: safetensors>=0.8.0
Requires-Dist: huggingface-hub>=1.20.1
Requires-Dist: requests>=2.32.5
Requires-Dist: mkdocs>=1.6.1
Requires-Dist: mkdocstrings>=1.0.4
Requires-Dist: mkdocstrings-python>=2.0.5
Requires-Dist: mkdocs-material>=9.7.6
Provides-Extra: dev
Requires-Dist: ruff>=0.1.6; extra == "dev"
Requires-Dist: pytest>=7.4.2; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Provides-Extra: api
Requires-Dist: fastapi; extra == "api"
Requires-Dist: uvicorn[standard]; extra == "api"
Requires-Dist: pydantic; extra == "api"
Requires-Dist: python-multipart; extra == "api"
Requires-Dist: tiktoken; extra == "api"
Requires-Dist: jinja2; extra == "api"
Requires-Dist: websockets>=11.0; extra == "api"
Requires-Dist: starlette; extra == "api"
Requires-Dist: regex; extra == "api"
Provides-Extra: parser
Requires-Dist: lxml>=5.2.2; extra == "parser"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6.1; extra == "docs"
Requires-Dist: mkdocs-material>=9.7.6; extra == "docs"
Requires-Dist: mkdocstrings>=1.0.4; extra == "docs"
Requires-Dist: mkdocstrings-python>=2.0.5; extra == "docs"
Dynamic: license-file

<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" width="320">
  </picture>
</a>

<h1>LLM4Free</h1>

<p><strong>One Python toolkit for 40+ free &amp; paid AI models, web search, image &amp; voice generation, and a drop-in OpenAI-compatible server — all behind a single, consistent interface.</strong></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="https://github.com/OEvortex/llm4free/stargazers"><img src="https://img.shields.io/github/stars/OEvortex/llm4free?style=flat-square" alt="GitHub Stars"></a>
  <a href="https://github.com/OEvortex/llm4free/network/members"><img src="https://img.shields.io/github/forks/OEvortex/llm4free?style=flat-square" alt="GitHub Forks"></a>
  <a href="#"><img src="https://img.shields.io/pypi/pyversions/llm4free?style=flat-square&logo=python" alt="Python Version"></a>
  <a href="https://github.com/OEvortex/llm4free/blob/main/LICENSE.md"><img src="https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square" alt="License"></a>
  <a href="https://deepwiki.com/OEvortex/llm4free"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
</p>

<p>
  <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>
</p>

</div>

<hr/>

## ✨ Why LLM4Free?

Most AI libraries lock you into **one provider** and **one way of doing things**. LLM4Free gives you *everything* behind the interface you already know — the OpenAI SDK:

- 🔌 **One interface, 40+ providers.** Every chat provider implements `client.chat.completions.create(...)` — identical to the OpenAI Python SDK. Switch providers by changing one line.
- 💸 **Free tier built in.** Use HeckAI, Pollinations, and more with **zero API key** — then graduate to Groq, DeepInfra, or your own key when you need scale.
- 🔄 **Auto-failover client.** The unified `Client` retries across providers and resolves models for you. No more 3am outages from a dead endpoint.
- 🔍 **Multi-engine search.** DuckDuckGo, Bing, Brave, Yahoo, Mojeek, Wikipedia — one API.
- 🖼️🗣️ **Images & voice.** Text-to-image (Pollinations, Together, Stable Horde…) and text-to-speech (ElevenLabs, OpenAI FM, Qwen, Murf…) out of the box.
- 🚀 **OpenAI-compatible server.** Serve any provider through standard `/v1` endpoints — point the official OpenAI SDK at your laptop.
- 🧰 **Developer toolbox.** Web crawler (Scout), GitHub data toolkit, temp-mail, GGUF conversion, user-agent rotation, ASCII art, and more.
- 📚 **Fully typed & documented.** 100% type-annotated public API with auto-generated MkDocs reference.

> [!NOTE]
> LLM4Free is **Apache-2.0 licensed** — free for personal and commercial use.

<hr/>

## 📦 Installation

```bash
# pip
pip install -U llm4free

# With the OpenAI-compatible API server
pip install -U "llm4free[api]"

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

```bash
# uv (recommended)
uv add llm4free

# Run without installing
uv run llm4free --help

# Install as a global CLI tool
uv tool install llm4free
```

```bash
# Docker
docker pull OEvortex/llm4free:latest
docker run -it OEvortex/llm4free:latest
```

See [docs/DOCKER.md](docs/DOCKER.md) for full Docker deployment options including compose profiles.

<hr/>

## 🚀 Quick Start

### Unified Client — one client for everything

The fastest way to use LLM4Free is the unified `Client`. It behaves just like the OpenAI SDK you already know, but it picks a working provider for you and auto-fails over when one is down. Use `model="auto"` to let it choose, or `model="Provider/Model"` to force a specific one.

```python
from llm4free.client import Client

# Let the client pick any working provider/model
client = Client(print_provider_info=True)
response = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Explain quantum computing in simple terms"}],
)
print(response.choices[0].message.content)

# Or force a specific provider/model explicitly
client.chat.completions.create(
    model="HeckAI/google/gemini-2.5-flash-preview",
    messages=[{"role": "user", "content": "Hello!"}],
)
```

> [!TIP]
> `model="auto"` resolves a working provider and model for you — no need to memorize provider names. Use `model="Provider/Model"` (for example `"HeckAI/google/gemini-2.5-flash-preview"`) to force a specific backend. `client.chat.completions.last_provider` tells you which provider was used, and `print_provider_info=True` prints it live. This gives you auto-failover and model resolution for free.

### AI Chat — no API key required (raw provider)

Prefer to use a provider directly? Every provider implements the OpenAI-compatible interface. The `Client` above is the recommended path because it adds auto-failover and model resolution automatically.

```python
from llm4free.llm.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

The same unified `Client` does images OpenAI-style — `client.images.generate(...)` (alias `client.images.create(...)`). Use `model="auto"` for automatic provider selection and failover, or pin a backend with `model="Provider/Model"`.

```python
from llm4free.client import Client

client = Client(print_provider_info=True)

# Auto-select a working image provider
image = client.images.generate(
    prompt="A serene mountain landscape at sunset",
    model="auto",
    size="1024x1024",
)
print(image.data[0].url)

# Or force a specific backend
image = client.images.generate(
    prompt="A cyberpunk city at night",
    model="PollinationsAI/flux",
)
print(image.data[0].url)
```

Prefer a provider directly? Every TTI provider implements the OpenAI-style `images.create(...)` method too:

```python
from llm4free.Provider.TTI import PollinationsAI

gen = PollinationsAI()
image = gen.images.create(prompt="A serene mountain landscape at sunset", response_format="url")
print(image.data[0].url)
```

### Unified Client — recall the hero example

The unified `Client` shown at the top of [Quick Start](#unified-client--one-client-for-everything) is the recommended way to use LLM4Free: `model="auto"` picks a working provider, `model="Provider/Model"` forces a specific one, and it auto-fails over between providers.

```python
from llm4free.client import Client

client = Client(print_provider_info=True)
resp = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Summarize LLM4Free."}],
)
print(resp.choices[0].message.content)
```

See [docs/getting-started.md](docs/getting-started.md) for the full quick-start guide.

<hr/>

## 💻 Command Line Interface

A rich CLI powered by [Rich](https://github.com/Textualize/rich) — search, chat, and generate straight from your terminal.

```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](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.llm.heckai import HeckAI
from llm4free.llm.artingai import ArtingAI
from llm4free.llm.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.llm.Auth.groq import Groq
from llm4free.llm.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.llm.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/](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](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](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](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 official 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](docs/openai-api-server.md) | Docker: [docs/DOCKER.md](docs/DOCKER.md)

<hr/>

## 🧩 Tool Calling

Built-in function calling that works with any provider.

```python
from llm4free.llm.heckai import HeckAI
from llm4free.AIbase 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](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](docs/models.md)

<hr/>

## 🛠️ Developer Tools

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

<hr/>

## 📚 Documentation

| Resource | Description |
|----------|-------------|
| [Getting Started](docs/getting-started.md) | Installation, first chat, web search, image generation |
| [Architecture](docs/architecture.md) | System design, layers, and data flows |
| [CLI Reference](docs/cli.md) | All CLI commands and options |
| [Python Client](docs/client.md) | Unified client with auto-failover |
| [API Server](docs/openai-api-server.md) | OpenAI-compatible FastAPI server |
| [Model Registry](docs/models.md) | Enumerate LLM, TTS, TTI models |
| [Tool Calling](docs/tool-calling.md) | Function calling with any provider |
| [Search Docs](docs/search.md) | Multi-engine search API |
| [Scout](docs/scout.md) | HTML parser and crawler |
| [Provider Development](docs/provider-development.md) | Create custom providers |
| [Deployment](docs/deployment.md) | Production deployment guide |
| [Docker](docs/DOCKER.md) | Docker setup and compose profiles |
| [Inferno](docs/inferno.md) | Local LLM server |
| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
| [Contributing](docs/contributing.md) | How to contribute |
| [Provider Modules](llm4free/llm/) | All provider implementations |
| [Docs Hub](docs/README.md) | Full documentation index |

<hr/>

## 🤝 Contributing

We welcome contributions — new providers, search engines, bug fixes, and docs. With 40+ providers and counting, there's always room to help.

1. Fork the repository
2. Create a feature branch
3. Make changes with descriptive commits
4. Submit a pull request

See [docs/contributing.md](docs/contributing.md) for full guidelines, and [docs/provider-development.md](docs/provider-development.md) to add a provider.

<hr/>

## 📄 License

Released under **Apache-2.0**. See [LICENSE.md](LICENSE.md). Free for personal and commercial use.

<hr/>

<div align="center">
  <p>Made with ❤️ by the LLM4Free team · <a href="https://github.com/OEvortex/llm4free">GitHub</a> · <a href="https://pypi.org/project/llm4free">PyPI</a> · <a href="https://t.me/OEvortexAI">Telegram</a></p>
</div>
