Metadata-Version: 2.4
Name: openrouter-free-models
Version: 0.1.0
Summary: openrouter-free-models - Find the best working free model on OpenRouter
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.34.2

# openrouter-free-models

Find the best working free LLM model on OpenRouter.

Automatically tests available free models and returns the first one with available quota.

## Installation

```bash
pip install openrouter-free-models
```

## Requirements

- Python 3.8+
- OpenRouter API key (get one at https://openrouter.ai/keys)

## Quick Start

```python
from openrouter_free_models import get_best_free_model

# Get the best working free model
model = get_best_free_model(api_key="your_api_key")

# Access model information
print(model.name)              # 'google/gemini-flash-1.5'
print(model.context_length)    # 1000000
print(model.provider)          # 'google'
print(model.supports_tools)    # True

# Get all info as dictionary
info = model.to_dict()
```

## Usage

### Using convenience function

```python
from openrouter_free_models import get_best_free_model

model = get_best_free_model(api_key="your_api_key")
print(f"Using: {model.name}")
```

### Using FreeModel class directly

```python
from free_router import FreeModel
from openrouter_free_models import FreeModel

model = FreeModel(api_key="your_api_key")
print(model.name)
print(model.context_length)
```

### Environment variable

Set your API key as environment variable:

```bash
export OPENROUTER_API_KEY="your_api_key_here"
```

```python
import os
from openrouter_free_models import get_best_free_model

model = get_best_free_model(api_key=os.environ['OPENROUTER_API_KEY'])
```

## API Reference

### `get_best_free_model(api_key: str) -> FreeModel`

Convenience function that returns a FreeModel instance with the best working model.

**Parameters:**
- `api_key` (str): Your OpenRouter API key (required)

**Returns:** FreeModel instance

**Raises:** Exception if no working free model is found

### `FreeModel(api_key: str)`

Main class for finding the best free model.

**Parameters:**
- `api_key` (str): Your OpenRouter API key (required)

**Properties:**
- `name` (str): Model identifier (e.g., 'google/gemini-flash-1.5')
- `context_length` (int): Maximum context length in tokens
- `provider` (str): Provider name (e.g., 'google', 'meta-llama')
- `supports_tools` (bool): Whether model supports function calling

**Methods:**
- `to_dict() -> dict`: Returns all model information as a dictionary

### ModelInfo Object

Returned model information includes:

| Attribute | Type | Description |
|-----------|------|-------------|
| name | str | Full model identifier |
| context_length | int | Context window size in tokens |
| provider | str | Provider (extracted from name) |
| supports_tools | bool | Function calling support |

## How It Works

1. Fetches all free models from OpenRouter API
2. Sorts them by context length (largest first)
3. Tests each model with a tiny request to check for available quota
4. Returns the first working model with quota
5. Raises exception if no model has available quota

## Example Output

```python
>>> from openrouter_free_models import get_best_free_model
>>> model = get_best_free_model(api_key="sk-...")
🔍 Searching for free models on OpenRouter...
📋 Found 23 free models. Testing for available quota...
   [1/10] Testing google/gemini-flash-1.5... ❌ No quota (402)
   [2/10] Testing meta-llama/llama-3-8b-instruct... ✅ WORKING

>>> print(model.name)
meta-llama/llama-3-8b-instruct

>>> print(model.context_length)
8192

>>> print(model.to_dict())
{'name': 'meta-llama/llama-3-8b-instruct', 'context_length': 8192, 'provider': 'meta-llama', 'supports_tools': True}
```

## Error Handling

```python
try:
    model = get_best_free_model(api_key="your_key")
except Exception as e:
    print(f"Failed: {e}")
    # All free models have exhausted their quota
    # Try again later or use a paid model
```

## License

MIT

## Links

- [OpenRouter](https://openrouter.ai)
- [Get API Key](https://openrouter.ai/keys)
- [Source Code](https://github.com/sashagra/free-router)

## Contributing

Issues and pull requests are welcome.
