Metadata-Version: 2.4
Name: simplyllm
Version: 0.1.3
Summary: Free AI LLM client with multi-provider fallback and rate limiting
Project-URL: Repository, https://github.com/freeai/simplyllm
License-Expression: MIT
Requires-Python: >=3.9
Requires-Dist: fastapi>=0.100.0
Requires-Dist: openai>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: uvicorn>=0.20.0
Description-Content-Type: text/markdown

# SimplyLLM

OpenAI SDK compatible multi-provider LLM client with automatic fallback and rate limiting.

## Quick Start

```python
from simplyllm import SimplyLLM

llm = SimplyLLM()
result = llm.chat([{"role": "user", "content": "hello"}])
print(result.content)
```

## API

```python
# Chat completion (OpenAI format)
result = llm.chat(messages, model=None, temperature=None, max_tokens=None,
                  debug_provider=None, max_wait=None)

# Shortcut for single prompt
result = llm.complete("hello", max_tokens=500)
```

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `messages` | `list[dict]` | OpenAI format message list |
| `model` | `str` | Model override (optional) |
| `temperature` | `float` | 0.0-2.0 (optional) |
| `max_tokens` | `int` | Max output tokens (optional) |
| `debug_provider` | `str` | Force provider: `"cerebras"` `"groq"` `"openrouter"` `"nvidia_nim"` (optional) |
| `max_wait` | `float` | Max wait for capacity in seconds, default 80 (optional) |

### Result

| Field | Type | Description |
|-------|------|-------------|
| `content` | `str` | Generated text |
| `provider` | `str` | Provider that fulfilled the request |
| `model` | `str` | Model used |
| `latency` | `float` | Time taken in seconds |
| `attempts` | `list[dict]` | Failed attempts before success |

## Providers

| Provider | Model | RPM |
|----------|-------|-----|
| cerebras | zai-glm-4.7 | 5 |
| groq | openai/gpt-oss-120b | 30 |
| openrouter | google/gemma-4-31b-it:free | 20 |
| nvidia_nim | openai/gpt-oss-120b | 40 |

## Server

```bash
make up        # start server on :10000
make down      # stop server
make test      # run benchmark
```
