Metadata-Version: 2.5
Name: freetheai
Version: 0.1.0
Summary: Official Python SDK for FreeTheAI: a free OpenAI-compatible AI API with chat, streaming, web search, and image and video tasks.
Project-URL: Homepage, https://freetheai.org
Project-URL: Documentation, https://freetheai.org/docs
Project-URL: Repository, https://github.com/Free-The-Ai/freetheai-python
Project-URL: Issues, https://github.com/Free-The-Ai/freetheai-python/issues
Project-URL: Changelog, https://github.com/Free-The-Ai/freetheai-python/releases
Project-URL: Discord, https://discord.gg/secrets
Author-email: FreeTheAI <vibheksoni@engineer.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai sdk,chat completions,free ai api,free llm api,freetheai,llm,openai compatible,streaming,tool calls,web search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx<1,>=0.25
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://free-the-ai.github.io/freetheai-python/"><img src="https://raw.githubusercontent.com/Free-The-Ai/freetheai-python/main/.github/banner.jpg" alt="FreeTheAI Python SDK" width="100%"></a>
</p>

<p align="center">
  <a href="https://pypi.org/project/freetheai/"><img src="https://img.shields.io/pypi/v/freetheai?color=111111" alt="PyPI"></a>
  <a href="https://pypi.org/project/freetheai/"><img src="https://img.shields.io/pypi/pyversions/freetheai?color=111111" alt="Python versions"></a>
  <a href="https://github.com/Free-The-Ai/freetheai-python/actions/workflows/test.yml"><img src="https://github.com/Free-The-Ai/freetheai-python/actions/workflows/test.yml/badge.svg" alt="Tests"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-111111" alt="MIT license"></a>
  <a href="https://discord.gg/secrets"><img src="https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
</p>

<p align="center">
  <b><a href="https://free-the-ai.github.io/freetheai-python/">Documentation</a></b> ·
  <a href="https://free-the-ai.github.io/freetheai-python/getting-started/">Getting started</a> ·
  <a href="https://freetheai.org/models">Models</a> ·
  <a href="https://freetheai.org">freetheai.org</a>
</p>

# FreeTheAI Python SDK

The official Python client for [FreeTheAI](https://freetheai.org), a free OpenAI-compatible AI API. One key gives you dozens of chat models, streaming, tool calls, web search with sourced answers, and image and video tasks.

```bash
pip install freetheai
```

## Quickstart

Create a key at [freetheai.org](https://freetheai.org/dashboard/api-keys), do the [daily check-in](https://freetheai.org/checkin) for free models, and set `FREETHEAI_API_KEY`.

```python
from freetheai import FreeTheAI

client = FreeTheAI()

reply = client.chat.completions.create(
    model="fta/zai/glm-5.3",
    messages=[{"role": "user", "content": "Write a haiku about open models."}],
)
print(reply["choices"][0]["message"]["content"])
```

Stream it:

```python
for text in client.chat.completions.stream_text(model="fta/kimi/k3", messages=messages):
    print(text, end="", flush=True)
```

Search the web:

```python
answer = client.answer("What changed in Python 3.14?")
print(answer["answer"], answer["sources"])
```

## Built for the FreeTheAI API

Generic OpenAI clients treat every error the same. This one knows how the FreeTheAI API answers:

- **Busy models** wait for the server's `Retry-After`, or move straight to your `fallback_models`.
- **Concurrency limits** are learned on the first refusal; extra calls queue instead of failing.
- **Long replies** are fetched as a stream and assembled, so they don't hit idle timeouts.
- **Cut-off streams** raise `StreamInterruptedError` with the partial text, never a silently short answer.
- **The daily check-in and daily limit** raise `CheckinRequiredError` and `DailyLimitError` at once, with the link or reset time.
- **Mistyped model IDs** come back with suggestions; a missing `fta/` prefix is fixed for you.

```python
client = FreeTheAI(fallback_models=["fta/zai/glm-5.3-flash", "fta/mmx/minimax-m3"])
```

Read [Reliability](https://free-the-ai.github.io/freetheai-python/reliability/) for the full list.

## Documentation

| Guide | |
| --- | --- |
| [Getting started](https://free-the-ai.github.io/freetheai-python/getting-started/) | Key, check-in, first request |
| [Chat and streaming](https://free-the-ai.github.io/freetheai-python/guides/chat/) | Parameters, streaming, reasoning, images |
| [Tool calls](https://free-the-ai.github.io/freetheai-python/guides/tools/) | Function calling step by step |
| [Web search](https://free-the-ai.github.io/freetheai-python/guides/web-search/) | Results and sourced answers |
| [Images and video](https://free-the-ai.github.io/freetheai-python/guides/media/) | Media tasks |
| [Async](https://free-the-ai.github.io/freetheai-python/guides/async/) | `AsyncFreeTheAI` |
| [Errors](https://free-the-ai.github.io/freetheai-python/errors/) | Every error class and what to do |
| [Configuration](https://free-the-ai.github.io/freetheai-python/configuration/) | All client options |

## More from FreeTheAI

- [JavaScript / TypeScript SDK](https://github.com/Free-The-Ai/freetheai-js) and [Go SDK](https://github.com/Free-The-Ai/freetheai-go)
- [Cookbook](https://github.com/Free-The-Ai/freetheai-cookbook): runnable examples
- [Setup guides](https://freetheai.org/setup) for SillyTavern, JanitorAI, Claude Code, Cline, and more
- [API status](https://freetheai.org/status) and [Discord](https://discord.gg/secrets)

## License

MIT
