Metadata-Version: 2.4
Name: freellama
Version: 1.0.0
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, making high-quality AI available to everyone with just a few lines of code.

## Features

- **Zero setup** — no accounts, no keys
- Simple `.ask("your message")` interface
- Optional conversation memory (sends full history when `limit` is enabled)
- Per-conversation message limit with automatic reset
- Clean CLI for interactive chatting
- Streaming support
- Minimal dependencies (only `requests`)

## Installation

```bash
pip install freellama
```

> Requires Python 3.8+

## Quick Start

### Programmatic Use

```python
from freellama import FreeLlama

# One-shot queries (no memory)
print(FreeLlama().ask("Tell me a joke"))

# With conversation memory
bot = FreeLlama(limit=20)  # remembers up to 20 user messages
bot.ask("My name is Alice")
print(bot.ask("What is my name?"))  # → Should recall "Alice" if backend supports it
```

### Interactive Chat (CLI)

```bash
freellama                 # starts interactive chat
freellama --limit 15      # enables memory, resets after 15 messages
freellama "Hello!"        # one-shot message
freellama --stream        # streaming output
```

## Usage Examples

```python
# Persistent conversation
bot = FreeLlama(limit=10)
bot.ask("Explain quantum entanglement")
bot.ask("Now give a real-world analogy")
bot.ask("Make it simpler")
# ... continues with context until limit reached
```

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

## CLI Options

```bash
freellama --help
```

```
usage: freellama [-h] [--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
  --limit LIMIT   Enable memory: max user messages before conversation reset
  --stream        Show response token-by-token
```

## 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 the backend load and model routing.

## 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
