Metadata-Version: 2.4
Name: freellama
Version: 1.0.1
Summary: The simplest way to chat with Llama-3.3-70B for free
Home-page: https://github.com/IMApurbo/freellama
Author: AKM Korishee Apurbo
Author-email: bandinvisible8@gmail.com
License: MIT
Keywords: llm ai chatbot llama free groq
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# FreeLlama

**The simplest Python client for free Llama-3.3-70B access via public proxies**

`freellama` is a lightweight, easy-to-use Python package that gives you instant access to the powerful Llama-3.3-70B-Instruct model — **completely free**, no API key, no registration required.

It works by communicating directly with public LLM web interfaces, delivering high-quality AI responses with minimal setup.

## Features

- **Zero setup** — no accounts, no keys
- Simple `.ask("your message")` interface
- **Quality modes**: `fast` (default, quicker) or `best` (higher quality)
- Optional conversation memory (sends full history when `limit` is enabled)
- Per-conversation message limit with automatic reset
- Streaming support (token-by-token output)
- Clean and intuitive CLI
- Minimal dependencies (only `requests`)

## Installation

```bash
pip install freellama
```

> Requires Python 3.8+

## Quick Start

### Programmatic Use

```python
from freellama import FreeLlama

# One-shot query (fast mode by default)
print(FreeLlama().ask("Tell me a joke"))

# Best quality mode
bot = FreeLlama(mode="best")
print(bot.ask("Write a detailed poem about the ocean"))

# With memory + limit
bot = FreeLlama(mode="fast", limit=20)
bot.ask("My name is Alice")
print(bot.ask("What is my name?")) 
```

### Interactive Chat (CLI)

```bash
freellama                    # fast mode, no memory
freellama --mode best        # higher quality responses
freellama --limit 15         # enable memory (up to 15 messages)
freellama --stream           # token-by-token streaming
freellama --mode best --limit 20 --stream   # all features combined
freellama "Hello world!"     # one-shot message
```

## Usage Examples

```python
# High-quality persistent chat
bot = FreeLlama(mode="best", limit=10)
bot.ask("Explain quantum entanglement in detail")
bot.ask("Now give a real-world analogy")
bot.ask("Make it even simpler")
```

```python
# Fast stateless queries
questions = ["Capital of France?", "2+2?", "Best pizza topping?"]
for q in questions:
    print(FreeLlama(mode="fast").ask(q))
```

## CLI Options

```bash
freellama --help
```

```
usage: freellama [-h] [--mode {fast,best}] [--limit LIMIT] [--stream] [message]

FreeLlama - Free Llama-3.3-70B Chat Client

positional arguments:
  message               Send a single message and exit

options:
  -h, --help            show this help message
  --mode {fast,best}    Quality mode: fast (default) or best
  --limit LIMIT         Enable memory: max user messages before conversation reset
  --stream              Show response token-by-token (streaming)
```

## Important Note on Memory

The underlying public services are **free anonymous proxies** and do **not officially guarantee multi-turn conversation memory**.

When you set `--limit` or `limit=N`, FreeLlama sends the full conversation history with every request — this is the correct format and gives the **best possible chance** of context retention.

Memory works best for short conversations and may vary depending on backend routing and load.

## Author

**IMApurbo**  
GitHub: [@IMApurbo](https://github.com/IMApurbo)

## License

MIT License — free to use, modify, and distribute.

---

Enjoy frontier-level AI for free — no barriers, no costs! 🚀

Made with ❤️ by IMApurbo
