Metadata-Version: 2.4
Name: freebuff-gateway
Version: 0.1.0
Summary: Free OpenAI-compatible API gateway — route requests to free LLM providers with zero-code setup. Save thousands on API costs.
Author: FreeBuff Gateway Contributors
License: MIT
Project-URL: Homepage, https://github.com/freebuff-gateway/freebuff-gateway
Project-URL: Source, https://github.com/freebuff-gateway/freebuff-gateway
Project-URL: Documentation, https://freebuff-gateway.readthedocs.io
Keywords: openai,api-gateway,free-llm,freebuff,proxy
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn[standard]>=0.20.0
Requires-Dist: httpx>=0.24.0

# FreeBuff Gateway

**Free OpenAI-compatible API gateway — route requests to free LLM providers with zero-code setup. Save thousands on API costs.**

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

---

## Why?

OpenAI API costs add up fast. **FreeBuff Gateway** is a transparent proxy that sits between your existing tools (anything that speaks OpenAI API) and free LLM providers:

- **Primary**: FreeBuff ([freebuff.llm.pm](https://freebuff.llm.pm)) — free MiniMax M2.7, Gemini Flash, and more
- **Fallback**: OpenRouter free tier — additional free models
- **Last resort**: Local Ollama — completely free, runs on your machine

Just point your existing code at `http://localhost:8080/v1` and keep using `gpt-4`, `gpt-3.5-turbo`, or any model name — the gateway maps it to the real free model automatically.

---

## Quick Start

```bash
# Install
pip install freebuff-gateway

# Run the setup wizard
freebuff-gateway setup

# Start the gateway
freebuff-gateway start --port 8080
```

That's it. Your existing OpenAI-compatible tools now talk to free LLMs.

---

## Features

| Feature | Description |
|---------|-------------|
| **OpenAI-compatible API** | Drop-in replacement for `api.openai.com` |
| **Streaming + Non-streaming** | Full SSE streaming support |
| **Multi-provider failover** | FreeBuff → OpenRouter → Ollama |
| **Model mapping** | `gpt-4` → MiniMax M2.7, `gpt-3.5` → MiniMax M2, etc. |
| **Rate limiting** | Per-IP and per-key sliding window |
| **Usage dashboard** | Beautiful HTML dashboard with live stats |
| **Cost tracking** | See how much you've saved vs. OpenAI pricing |
| **SQLite storage** | Lightweight, no external DB needed |
| **CLI-first** | `freebuff-gateway start`, `setup`, `status`, `config` |

---

## Usage

### Start the server

```bash
# Default port 8080
freebuff-gateway start

# Custom port
freebuff-gateway start --port 9090 --host 127.0.0.1
```

### Test with curl

```bash
# List models
curl http://localhost:8080/v1/models

# Chat completion (non-streaming)
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

# Chat completion (streaming)
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "stream": true,
    "messages": [{"role": "user", "content": "Write a poem"}]
  }'
```

### Dashboard

Open [http://localhost:8080/v1/dashboard](http://localhost:8080/v1/dashboard) to see:
- Total tokens saved
- Costs avoided (vs. OpenAI pricing)
- Provider breakdown
- Recent request log

### Status

```bash
freebuff-gateway status
```

Shows configuration and usage statistics.

---

## Configuration

### Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `FREEBUFF_TOKEN` | — | FreeBuff auth token (from freebuff.llm.pm) |
| `FREEBUFF_BASE_URL` | `https://freebuff.llm.pm/v1` | FreeBuff API endpoint |
| `OPENROUTER_API_KEY` | — | OpenRouter API key (free tier) |
| `OLLAMA_BASE_URL` | `http://localhost:11434/v1` | Local Ollama endpoint |
| `PORT` | `8080` | Gateway listen port |
| `HOST` | `0.0.0.0` | Gateway bind address |
| `RATE_LIMIT_PER_IP` | `60` | Max requests per minute per IP |
| `RATE_LIMIT_PER_KEY` | `120` | Max requests per minute per API key |

### Config file

Configuration is stored in `~/.config/freebuff-gateway/config.json`.

### Model mapping

The gateway automatically maps common model names:

| Your request | Actual model |
|-------------|-------------|
| `gpt-4` | `minimax/minimax-m2.7` (via FreeBuff) |
| `gpt-4-turbo` | `minimax/minimax-m2.7` |
| `gpt-3.5-turbo` | `minimax/minimax-m2` |
| `claude-3-opus` | `minimax/minimax-m2.7` |
| `claude-3-haiku` | `google/gemini-2.5-flash-lite` |
| `gemini-pro` | `google/gemini-2.5-flash-lite` |

You can customize mappings in `~/.config/freebuff-gateway/config.json`.

---

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    Your Application                      │
│  (OpenAI SDK, curl, LangChain, any OpenAI-compatible)    │
└─────────────────────┬───────────────────────────────────┘
                      │ POST /v1/chat/completions
                      ▼
┌─────────────────────────────────────────────────────────┐
│              FreeBuff Gateway (localhost:8080)            │
│                                                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐ │
│  │ Rate     │→│ Model    │→│ Provider │→│ Usage  │ │
│  │ Limiter  │  │ Mapper   │  │ Router   │  │ DB     │ │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘ │
│                                      │                   │
└──────────────────────────────────────┼───────────────────┘
                                       │
              ┌────────────────────────┼────────────────┐
              ▼                        ▼                ▼
     ┌────────────────┐      ┌──────────────┐    ┌──────────┐
     │ FreeBuff       │      │ OpenRouter   │    │ Ollama   │
     │ (Primary)      │      │ (Fallback 1) │    │(Fallback2)│
     │ free.llm.pm    │      │ openrouter.ai│    │ localhost │
     └────────────────┘      └──────────────┘    └──────────┘
```

## Provider Setup

### FreeBuff (Primary)

1. Visit [https://freebuff.llm.pm](https://freebuff.llm.pm)
2. Log in or create an account
3. Open DevTools → Application → Local Storage → copy your auth token
4. Run `freebuff-gateway setup` and paste the token

Or set `FREEBUFF_TOKEN=your_token_here` in your environment.

### OpenRouter (Fallback)

1. Visit [https://openrouter.ai/keys](https://openrouter.ai/keys)
2. Create a free API key
3. Run `freebuff-gateway setup` or set `OPENROUTER_API_KEY`

### Ollama (Local Fallback)

1. Install Ollama from [https://ollama.com](https://ollama.com)
2. Pull a model: `ollama pull llama3.2`
3. Start Ollama: `ollama serve`
4. The gateway will auto-detect it at `http://localhost:11434`

---

## Development

```bash
# Clone and install in dev mode
git clone https://github.com/freebuff-gateway/freebuff-gateway.git
cd freebuff-gateway
pip install -e .

# Run tests
pytest
```

---

## License

MIT

---

*FreeBuff Gateway is not affiliated with OpenAI, FreeBuff, OpenRouter, or Ollama.*
