airouter-py 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- airouter_py-0.1.0/LICENSE +21 -0
- airouter_py-0.1.0/PKG-INFO +411 -0
- airouter_py-0.1.0/README.md +372 -0
- airouter_py-0.1.0/airouter/__init__.py +245 -0
- airouter_py-0.1.0/airouter/cli.py +743 -0
- airouter_py-0.1.0/airouter/limiter.py +448 -0
- airouter_py-0.1.0/airouter/preset.py +419 -0
- airouter_py-0.1.0/airouter/ratelimit.py +245 -0
- airouter_py-0.1.0/airouter/router.py +618 -0
- airouter_py-0.1.0/airouter/router_admin.py +230 -0
- airouter_py-0.1.0/airouter/router_client.py +113 -0
- airouter_py-0.1.0/airouter/router_status.py +219 -0
- airouter_py-0.1.0/airouter/router_tenantprov.py +306 -0
- airouter_py-0.1.0/airouter/server.py +1054 -0
- airouter_py-0.1.0/airouter/speak.py +266 -0
- airouter_py-0.1.0/airouter/store.py +693 -0
- airouter_py-0.1.0/airouter/transcribe.py +405 -0
- airouter_py-0.1.0/airouter/types.py +514 -0
- airouter_py-0.1.0/airouter/web/index.html +225 -0
- airouter_py-0.1.0/airouter_py.egg-info/PKG-INFO +411 -0
- airouter_py-0.1.0/airouter_py.egg-info/SOURCES.txt +28 -0
- airouter_py-0.1.0/airouter_py.egg-info/dependency_links.txt +1 -0
- airouter_py-0.1.0/airouter_py.egg-info/entry_points.txt +2 -0
- airouter_py-0.1.0/airouter_py.egg-info/requires.txt +13 -0
- airouter_py-0.1.0/airouter_py.egg-info/top_level.txt +1 -0
- airouter_py-0.1.0/pyproject.toml +51 -0
- airouter_py-0.1.0/setup.cfg +4 -0
- airouter_py-0.1.0/tests/test_e2e_failover.py +94 -0
- airouter_py-0.1.0/tests/test_e2e_generate.py +107 -0
- airouter_py-0.1.0/tests/test_server_smoke.py +205 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 airouter-py contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,411 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: airouter-py
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Route prompts across free-tier AI providers (Groq, Gemini, OpenRouter, Z.AI, SambaNova, Ollama, any OpenAI-compatible URL) with automatic failover. Supports text chat, TTS and STT. Python port of github.com/mrmhthegreat/airouter.
|
|
5
|
+
Author: airouter-py contributors
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/mrmhthegreat/airouter-py
|
|
8
|
+
Project-URL: Source, https://github.com/mrmhthegreat/airouter-py
|
|
9
|
+
Project-URL: Documentation, https://github.com/mrmhthegreat/airouter-py/tree/main/docs
|
|
10
|
+
Project-URL: Bug Tracker, https://github.com/mrmhthegreat/airouter-py/issues
|
|
11
|
+
Project-URL: Original (Go), https://github.com/mrmhthegreat/airouter
|
|
12
|
+
Keywords: llm,openai,groq,gemini,failover,router,tts,stt,free-tier,openai-compatible
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
22
|
+
Classifier: Topic :: Internet :: WWW/HTTP
|
|
23
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
24
|
+
Requires-Python: >=3.10
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
License-File: LICENSE
|
|
27
|
+
Requires-Dist: requests>=2.28
|
|
28
|
+
Requires-Dist: cryptography>=40
|
|
29
|
+
Provides-Extra: server
|
|
30
|
+
Requires-Dist: fastapi>=0.100; extra == "server"
|
|
31
|
+
Requires-Dist: uvicorn>=0.23; extra == "server"
|
|
32
|
+
Requires-Dist: starlette>=0.27; extra == "server"
|
|
33
|
+
Requires-Dist: python-multipart>=0.0.6; extra == "server"
|
|
34
|
+
Provides-Extra: dev
|
|
35
|
+
Requires-Dist: pytest>=7; extra == "dev"
|
|
36
|
+
Requires-Dist: build>=1; extra == "dev"
|
|
37
|
+
Requires-Dist: twine>=4; extra == "dev"
|
|
38
|
+
Dynamic: license-file
|
|
39
|
+
|
|
40
|
+
# airouter (Python port)
|
|
41
|
+
|
|
42
|
+
[](https://www.python.org/downloads/)
|
|
43
|
+
[](./LICENSE)
|
|
44
|
+
[](https://pypi.org/project/airouter-py/)
|
|
45
|
+
|
|
46
|
+
> One Python package + CLI that routes your prompt across many free-tier AI
|
|
47
|
+
> providers (Groq, Gemini, Gemma, OpenRouter, Z.AI GLM, Mistral, SambaNova,
|
|
48
|
+
> Ollama, any OpenAI-compatible URL) and **auto-switches when one hits its
|
|
49
|
+
> limit**. Supports **text chat**, **text-to-speech (TTS)**, and
|
|
50
|
+
> **speech-to-text (STT)** — same failover behaviour for all three.
|
|
51
|
+
|
|
52
|
+
This is a faithful Python port of the Go project at
|
|
53
|
+
[github.com/mrmhthegreat/airouter](https://github.com/mrmhthegreat/airouter).
|
|
54
|
+
Every feature of the original is reproduced: per-provider per-model limits,
|
|
55
|
+
timezone-aware daily resets, three flavours of cooldown, SQLite persistence
|
|
56
|
+
with AES-256-GCM-encrypted provider keys, the curated free-pool catalog,
|
|
57
|
+
tenants with hashed API keys, JSON mode, the OpenAI-compatible HTTP API,
|
|
58
|
+
the web UI, the same CLI subcommands.
|
|
59
|
+
|
|
60
|
+
> **Package name:** published on PyPI as **`airouter-py`** (the bare name
|
|
61
|
+
> `airouter` is already taken on PyPI by an unrelated package). The CLI
|
|
62
|
+
> script is still `airouter` (the script name and the package name are
|
|
63
|
+
> independent — see `[project.scripts]` in `pyproject.toml`). See
|
|
64
|
+
> [docs/PUBLISHING.md](docs/PUBLISHING.md) for how to publish new versions.
|
|
65
|
+
|
|
66
|
+
`airouter` is for: hobby projects, prototypes, internal tools, hackathons,
|
|
67
|
+
and anyone who wants free LLM access without managing API keys in every
|
|
68
|
+
script. Configure it once with the providers you have free keys for, then
|
|
69
|
+
send prompts from the CLI, the HTTP server, or any Python program. The
|
|
70
|
+
router picks the best available provider, sends the request, and on a
|
|
71
|
+
429 / 5xx / bad-key error fails over to the next one before your code
|
|
72
|
+
even notices.
|
|
73
|
+
|
|
74
|
+
## Three ways to use airouter
|
|
75
|
+
|
|
76
|
+
You can use any combination of these — they share the same SQLite DB file,
|
|
77
|
+
so provider configs, encrypted keys, daily-limit pauses, and usage counters
|
|
78
|
+
are consistent across all three.
|
|
79
|
+
|
|
80
|
+
### 1. As a published Python package (embedded library)
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
pip install airouter-py # once published; or: pip install -e . from a clone
|
|
84
|
+
pip install airouter-py[server] # adds FastAPI / uvicorn for the HTTP server
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
import airouter
|
|
89
|
+
|
|
90
|
+
c = airouter.open(airouter.Options(db="ai.db")) # keys encrypted at rest
|
|
91
|
+
c.add_free_pool({"GROQ_API_KEY": "gsk_..."}) # one-time seed
|
|
92
|
+
|
|
93
|
+
text = c.chat("Write one sentence about rain.") # auto-failover happens inside
|
|
94
|
+
|
|
95
|
+
# full control
|
|
96
|
+
resp = c.ask(airouter.Request(system="Be brief", prompt="hi", json=True))
|
|
97
|
+
print(resp.text, resp.provider, resp.model, resp.tokens, resp.attempts)
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
All request types are available: `c.generate()`, `c.speak()` (TTS),
|
|
101
|
+
`c.transcribe()` (STT). See [docs/EMBEDDED_USAGE.md](docs/EMBEDDED_USAGE.md)
|
|
102
|
+
for the full API including multi-turn conversations, custom Stores, and
|
|
103
|
+
typed error handling.
|
|
104
|
+
|
|
105
|
+
### 2. As a CLI
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
pip install airouter-py # installs the `airouter` script on your PATH
|
|
109
|
+
airouter bootstrap # seed the DB from the curated free-pool catalog
|
|
110
|
+
airouter provider list # live status
|
|
111
|
+
airouter ask "Write one sentence about rain"
|
|
112
|
+
airouter speak -o hello.wav "Hello world"
|
|
113
|
+
airouter transcribe recording.mp3
|
|
114
|
+
airouter serve -addr :8080 # run the HTTP API + web UI
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Every subcommand documented in [docs/CLI_CHEATSHEET.md](docs/CLI_CHEATSHEET.md).
|
|
118
|
+
|
|
119
|
+
### 3. As an HTTP server (standalone or mounted inside your own app)
|
|
120
|
+
|
|
121
|
+
**Standalone:**
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
airouter serve -addr :8080
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
**Mounted inside your own FastAPI / Starlette app** at `/airouter/`:
|
|
128
|
+
|
|
129
|
+
```python
|
|
130
|
+
import airouter
|
|
131
|
+
from airouter.server import new_handler
|
|
132
|
+
from fastapi import FastAPI
|
|
133
|
+
from starlette.routing import Mount
|
|
134
|
+
|
|
135
|
+
c = airouter.open(airouter.Options(db="ai.db"))
|
|
136
|
+
c.add_free_pool({"GROQ_API_KEY": "gsk_..."})
|
|
137
|
+
airouter_app = new_handler(c.router, admin_token="change-me")
|
|
138
|
+
|
|
139
|
+
app = FastAPI()
|
|
140
|
+
app.router.routes.append(Mount("/airouter", app=airouter_app))
|
|
141
|
+
|
|
142
|
+
# Use the Client directly from your own routes — no HTTP hop.
|
|
143
|
+
@app.get("/summarize/{text}")
|
|
144
|
+
def summarize(text: str):
|
|
145
|
+
return {"summary": c.chat(f"Summarize in one sentence: {text}")}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
See [examples/mount_in_existing_app.py](examples/mount_in_existing_app.py)
|
|
149
|
+
for a full working example.
|
|
150
|
+
|
|
151
|
+
## Features
|
|
152
|
+
|
|
153
|
+
- **Three request types, one router:** text chat (`r.generate`), text-to-speech
|
|
154
|
+
(`r.speak`), speech-to-text (`r.transcribe`). Each one filters the provider
|
|
155
|
+
pool by category so a TTS call never hits a chat model and vice versa.
|
|
156
|
+
- **Per-provider per-model limits** with RPM / RPD / TPM for chat and TTS,
|
|
157
|
+
plus ASH (audio seconds per hour) and ASD (audio seconds per day) for TTS
|
|
158
|
+
and STT. Every model entry is independent.
|
|
159
|
+
- **Per-provider timezone-aware daily resets.** Gemini's quota resets at PT
|
|
160
|
+
midnight; the router knows that and unpauses the provider at the right time.
|
|
161
|
+
- **Three flavours of cooldown:** seconds (a transient 429), until-local-midnight
|
|
162
|
+
(a daily cap), 24 hours (a bad key or model id).
|
|
163
|
+
- **Pauses persist** to SQLite — restarts and separate CLI invocations respect
|
|
164
|
+
the same state.
|
|
165
|
+
- **Tenants** with hashed API keys and optional daily request caps. Provider
|
|
166
|
+
keys are shared across tenants; a provider can also be restricted to one.
|
|
167
|
+
- **JSON mode** that asks the provider for JSON and validates the response,
|
|
168
|
+
failing over if a model returns junk. Models without JSON mode or a system
|
|
169
|
+
role (Gemma) are handled transparently.
|
|
170
|
+
- **Curated free-pool catalog** with three categories: `text` (20 models),
|
|
171
|
+
`tts` (6 models), `stt` (3 models). One `bootstrap` command seeds whichever
|
|
172
|
+
categories you want.
|
|
173
|
+
- **Same shape, three faces:** the CLI, the HTTP server, and the Python
|
|
174
|
+
library all expose the same Request/Response types.
|
|
175
|
+
|
|
176
|
+
## Quick start
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
git clone https://github.com/mrmhthegreat/airouter # original Go repo
|
|
180
|
+
# or this Python port
|
|
181
|
+
pip install -r requirements.txt
|
|
182
|
+
# or: pip install -e . (with the [server] extra for FastAPI / uvicorn)
|
|
183
|
+
|
|
184
|
+
export GROQ_API_KEY=gsk_... GEMINI_API_KEY=... # set the ones you have
|
|
185
|
+
airouter bootstrap # import curated free-pool entries
|
|
186
|
+
airouter provider list # live status
|
|
187
|
+
|
|
188
|
+
airouter ask "Write one sentence about rain"
|
|
189
|
+
airouter ask -json -system 'Reply as {"emotion":"..."} only.' "I failed my exam today"
|
|
190
|
+
echo "long text..." | airouter ask -envelope # full Response JSON
|
|
191
|
+
|
|
192
|
+
airouter usage # today's usage per provider
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
The `bootstrap` command imports every entry from the curated free-pool catalog
|
|
196
|
+
whose env var is set. Entries without a key (Z.AI, OpenRouter, etc.) are
|
|
197
|
+
skipped with a clear message — set their env vars and re-run.
|
|
198
|
+
|
|
199
|
+
## Output format
|
|
200
|
+
|
|
201
|
+
The CLI auto-detects stdout:
|
|
202
|
+
|
|
203
|
+
- **stdout is a terminal** → text on stdout + a short `[provider / model, N tokens, Xms]` footer on stderr.
|
|
204
|
+
- **stdout is piped** → raw text only, no footer. So `airouter ask ... | grep` works cleanly.
|
|
205
|
+
- `-json` → ask the model for JSON and pretty-print only that JSON.
|
|
206
|
+
- `-envelope` → full Response as JSON (text + provider + model + tokens + attempts).
|
|
207
|
+
- `-text` → force raw text with no footer.
|
|
208
|
+
|
|
209
|
+
The HTTP server mirrors this with `?format=text` and the `Accept: text/plain`
|
|
210
|
+
header.
|
|
211
|
+
|
|
212
|
+
## Library usage
|
|
213
|
+
|
|
214
|
+
```python
|
|
215
|
+
import airouter
|
|
216
|
+
|
|
217
|
+
c = airouter.open(airouter.Options(db="ai.db")) # keys encrypted at rest
|
|
218
|
+
# once: put your keys in the DB (encrypted). Afterwards no env vars are needed.
|
|
219
|
+
c.add_free_pool({"GROQ_API_KEY": "gsk_...", "GEMINI_API_KEY": "..."})
|
|
220
|
+
|
|
221
|
+
text = c.chat("Write one sentence about rain") # auto-failover
|
|
222
|
+
|
|
223
|
+
# full control
|
|
224
|
+
resp = c.ask(airouter.Request(system="Be brief", prompt="hi", json=True))
|
|
225
|
+
print(resp.text, resp.provider, resp.model, resp.tokens, resp.attempts)
|
|
226
|
+
|
|
227
|
+
# expose OpenAI API + web UI from your own server
|
|
228
|
+
# c.handler(admin_token=os.environ["AIROUTER_ADMIN_TOKEN"])
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
`airouter.new_client(store)` takes any `airouter.Store` (memory, or your own
|
|
232
|
+
Postgres) if you do not want SQLite. All `Router` methods (`generate`,
|
|
233
|
+
`speak`, `transcribe`, `status`, `usage`, ...) are on the client. Share the
|
|
234
|
+
same DB file with the CLI and server: usage and pauses are shared.
|
|
235
|
+
|
|
236
|
+
## HTTP server, web UI and OpenAI-compatible API
|
|
237
|
+
|
|
238
|
+
```bash
|
|
239
|
+
export AIROUTER_ADMIN_TOKEN=change-me
|
|
240
|
+
export AIROUTER_SECRET=$(python3 -c "import secrets;print(secrets.token_hex(32))") # encrypts provider keys
|
|
241
|
+
airouter tenant add acme -limit 2000 # prints the tenant API key once
|
|
242
|
+
airouter serve -addr :8080 # add -cors https://myapp.com for browser apps
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
- **Web UI:** open `http://localhost:8080/`, paste a tenant key (or the admin
|
|
246
|
+
token). Tabs: **Chat** (shows which provider answered and any failovers),
|
|
247
|
+
**Usage** (live provider status, daily usage, what the provider itself
|
|
248
|
+
reports as remaining), **Connect your app** (base URL + copy-paste
|
|
249
|
+
Python/curl snippets), **Admin** (bootstrap, list providers / tenants).
|
|
250
|
+
- **OpenAI-compatible:** base URL `http://localhost:8080/v1`, API key = your
|
|
251
|
+
airouter tenant key, `model: "auto"`.
|
|
252
|
+
|
|
253
|
+
```python
|
|
254
|
+
from openai import OpenAI
|
|
255
|
+
client = OpenAI(base_url="http://localhost:8080/v1", api_key="air_...")
|
|
256
|
+
print(client.chat.completions.create(model="auto",
|
|
257
|
+
messages=[{"role": "user", "content": "Hello"}]).choices[0].message.content)
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
Supported: `POST /v1/chat/completions` (incl. `stream: true`, `response_format`
|
|
261
|
+
json, `max_tokens`, `temperature`), `GET /v1/models`, `POST /v1/audio/speech`,
|
|
262
|
+
`POST /v1/audio/transcriptions`. `model` is `auto` (router chooses and fails
|
|
263
|
+
over) or a provider name / exact model id to pin one. **Not supported yet:**
|
|
264
|
+
tool/function calling and image input (clear `400`). `stream: true` is
|
|
265
|
+
*buffered streaming*: the router needs the whole answer to fail over safely, so
|
|
266
|
+
chunks are sent after it completes.
|
|
267
|
+
|
|
268
|
+
Native API (richer: attempts, provider, latency):
|
|
269
|
+
|
|
270
|
+
```bash
|
|
271
|
+
curl -s localhost:8080/v1/generate -H "Authorization: Bearer air_..." -d '{"prompt":"Say hi","system":"Be brief"}'
|
|
272
|
+
curl -s localhost:8080/v1/usage -H "Authorization: Bearer air_..." # usage + live provider status
|
|
273
|
+
curl -s localhost:8080/v1/whoami -H "Authorization: Bearer air_..."
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
### Status codes you will see
|
|
277
|
+
|
|
278
|
+
| Code | Meaning | Retry? |
|
|
279
|
+
|------|---------|--------|
|
|
280
|
+
| 400 | Your request is invalid (empty messages, every provider rejected it as bad) | No, fix it |
|
|
281
|
+
| 401 | Missing/invalid key | No |
|
|
282
|
+
| 403 | Tenant disabled | No |
|
|
283
|
+
| 429 | **Your tenant's** daily cap is used up (`Retry-After`) | After reset |
|
|
284
|
+
| 502 | Providers were tried and all failed (`attempts` lists why) | Yes, soon |
|
|
285
|
+
| 503 | Every provider is limited / cooling down right now (`Retry-After`, `reasons`) | Yes, after `Retry-After` |
|
|
286
|
+
| 504 | The whole request timed out (default 2 min) | Yes |
|
|
287
|
+
|
|
288
|
+
OpenAI SDKs retry 429/503 automatically, so they behave well against airouter.
|
|
289
|
+
|
|
290
|
+
Admin endpoints (`Authorization: Bearer <admin token>`):
|
|
291
|
+
`GET/POST /v1/providers`, `DELETE /v1/providers/{id}`,
|
|
292
|
+
`POST /v1/providers/{id}/enable|disable|reset`,
|
|
293
|
+
`POST /v1/providers/{id}/key` (`{"api_key": "..."}`),
|
|
294
|
+
`GET/POST /v1/tenants`, `POST /v1/tenants/{id}/rotate-key`,
|
|
295
|
+
`POST /v1/bootstrap?store_keys=1`.
|
|
296
|
+
|
|
297
|
+
Public endpoints: `GET /` (UI), `GET /healthz`, `GET /v1/presets`, `GET /v1/presets/free-pool`.
|
|
298
|
+
|
|
299
|
+
## How switching works
|
|
300
|
+
|
|
301
|
+
Providers are tried by `priority` (lower first; a tenant's own providers go
|
|
302
|
+
before shared ones). A provider is skipped when its daily cap is reached
|
|
303
|
+
(paused to its local midnight), its per-minute window is full (90% safety
|
|
304
|
+
margin), it is busy (`workers`), or it is paused/cooling down.
|
|
305
|
+
|
|
306
|
+
What happens when a provider fails:
|
|
307
|
+
|
|
308
|
+
| Upstream result | Reaction |
|
|
309
|
+
|-----------------|----------|
|
|
310
|
+
| 401, 403, 404 | Pause 24h (bad key / model id), then try the next provider |
|
|
311
|
+
| 402 | Pause 1h (out of credits) |
|
|
312
|
+
| 429 with daily hint (`PerDay`, "daily", Retry-After > 5 min, or headers say 0 left for hours) | Pause until the provider's local midnight |
|
|
313
|
+
| other 429 | Cool down for `Retry-After` / Gemini `retryDelay` (30s if none) |
|
|
314
|
+
| 400, 413, 422 | **No penalty** (it is usually your request). If every provider rejects it you get a 400. 3 config-looking 400s in a row (bad model / json mode) pause 24h; any success resets this |
|
|
315
|
+
| 408, 5xx, timeout, network error | Exponential backoff 20s, 40s, ... up to 5 min; reset on success |
|
|
316
|
+
| 200 but empty / invalid JSON when JSON was requested | Try the next provider, no penalty |
|
|
317
|
+
|
|
318
|
+
**When limits are hit it does not hammer or loop forever:** each provider is
|
|
319
|
+
tried at most once per request. If everything is only briefly limited,
|
|
320
|
+
`generate` waits up to `MaxWait` (20s) for the soonest provider; otherwise it
|
|
321
|
+
returns `503` with `Retry-After`. A single call is bounded by
|
|
322
|
+
`AttemptTimeout` (60s) and the whole request by `RequestTimeout` (2 min).
|
|
323
|
+
|
|
324
|
+
## Keys and secrets: what is stored how
|
|
325
|
+
|
|
326
|
+
| Secret | Storage | Why |
|
|
327
|
+
|--------|---------|-----|
|
|
328
|
+
| Tenant API keys (`air_...`) | **SHA-256 hash only** in the DB | Shown once; a DB leak reveals no working key. Rotate with `airouter tenant rotate NAME`. |
|
|
329
|
+
| Provider keys (Groq, Gemini, ...) | **AES-256-GCM encrypted** in the DB | They must be sent upstream, so they cannot be hashed. The DB alone is useless without the master secret. |
|
|
330
|
+
| Master secret | `$AIROUTER_SECRET`, else a `0600` file `<db>.key` | Back it up **separately** from the DB. Lose it and stored provider keys cannot be decrypted (re-enter them). |
|
|
331
|
+
|
|
332
|
+
```bash
|
|
333
|
+
airouter provider add -preset groq -model openai/gpt-oss-120b -key-stdin # paste key; stored encrypted
|
|
334
|
+
airouter provider set-key 3 # replace a key later
|
|
335
|
+
airouter bootstrap -store-keys # copy keys from env vars into the DB, then unset the env vars
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
`provider list` shows where each key comes from (`db` / `env`) without ever
|
|
339
|
+
printing it. Databases from older versions with plaintext keys are encrypted
|
|
340
|
+
automatically on first open.
|
|
341
|
+
|
|
342
|
+
## Free-tier catalog
|
|
343
|
+
|
|
344
|
+
`airouter free-pool` lists the curated catalog. Every entry has a `Category`,
|
|
345
|
+
real model ID, RPM/RPD/TPM from the provider's console, and a `VerifiedOn`
|
|
346
|
+
date. Limits move — re-check before relying on them.
|
|
347
|
+
|
|
348
|
+
Three categories are supported:
|
|
349
|
+
|
|
350
|
+
| Category | What it is | Routed? |
|
|
351
|
+
| -------- | --------------------------------------------------------- | ------------------------------------ |
|
|
352
|
+
| `text` | Chat, OpenAI-compatible `/chat/completions` | Yes — `r.generate` / `airouter ask` / `POST /v1/generate` |
|
|
353
|
+
| `tts` | Text-to-speech | Yes — `r.speak` / `airouter speak` / `POST /v1/speak` |
|
|
354
|
+
| `stt` | Speech-to-text | Yes — `r.transcribe` / `airouter transcribe` / `POST /v1/transcribe` |
|
|
355
|
+
|
|
356
|
+
### Importing categories
|
|
357
|
+
|
|
358
|
+
```bash
|
|
359
|
+
airouter bootstrap # default = text only
|
|
360
|
+
airouter bootstrap -category text # explicit text only
|
|
361
|
+
airouter bootstrap -category tts,stt # only TTS + STT
|
|
362
|
+
airouter bootstrap -category all # everything
|
|
363
|
+
airouter bootstrap -preset groq # only Groq entries
|
|
364
|
+
airouter bootstrap -overwrite # update existing same-name entries
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
## Project layout
|
|
368
|
+
|
|
369
|
+
```
|
|
370
|
+
airouter/
|
|
371
|
+
__init__.py one-import facade (airouter.open / Client.chat / .ask / .handler / .add_free_pool)
|
|
372
|
+
types.py public data shapes (ProviderConfig, Tenant, Request, ...)
|
|
373
|
+
preset.py built-in provider catalog + curated free-pool model list
|
|
374
|
+
store.py Store ABC, MemoryStore, SQLStore (sqlite3), EncryptedStore (AES-256-GCM)
|
|
375
|
+
ratelimit.py parse rate-limit headers / Retry-After / Gemini retryDelay / quotaDetail
|
|
376
|
+
limiter.py ProviderState, acquire/release, classify_failure, observe_rate_headers
|
|
377
|
+
router.py core Router: candidates, Generate, Options, TenantPolicy
|
|
378
|
+
router_client.py call_provider (OpenAI-compatible + Ollama)
|
|
379
|
+
router_admin.py CreateTenant, Authenticate, SaveProvider, BootstrapProviders, ...
|
|
380
|
+
router_status.py Status, Usage, ProviderStatus, UsageReport
|
|
381
|
+
router_tenantprov.py Tenant self-service (AddTenantProvider, OllamaModels, ...)
|
|
382
|
+
speak.py r.speak — TTS via Groq (OpenAI-compat) or Gemini (native)
|
|
383
|
+
transcribe.py r.transcribe — STT via Groq Whisper or Gemini Files API
|
|
384
|
+
server.py Starlette app: native + OpenAI-compatible + /v1/me/* + web UI
|
|
385
|
+
cli.py argparse dispatcher: ask / speak / transcribe / serve / provider / tenant / me / ...
|
|
386
|
+
web/index.html embedded web UI
|
|
387
|
+
examples/ runnable examples (chat.py, serve.py, audio.py)
|
|
388
|
+
tests/ end-to-end tests against a mock OpenAI-compatible server
|
|
389
|
+
pyproject.toml pip install -e .[server]
|
|
390
|
+
```
|
|
391
|
+
|
|
392
|
+
## Differences from the Go original
|
|
393
|
+
|
|
394
|
+
The Python port is a 1:1 functional port. Notable implementation differences:
|
|
395
|
+
|
|
396
|
+
- HTTP server uses **FastAPI / Starlette / uvicorn** instead of `net/http`.
|
|
397
|
+
- HTTP client uses **`requests`** instead of `net/http`.
|
|
398
|
+
- Encryption uses **`cryptography`'s AESGCM** instead of `crypto/cipher`.
|
|
399
|
+
- SQLite uses the stdlib **`sqlite3`** module instead of `mattn/go-sqlite3` /
|
|
400
|
+
`modernc.org/sqlite`.
|
|
401
|
+
- CLI uses **`argparse`** instead of `flag`.
|
|
402
|
+
- Provider state is protected by `threading.Lock` instead of `sync.Mutex`.
|
|
403
|
+
|
|
404
|
+
All public APIs (Request/Response shapes, error types, Router methods, CLI
|
|
405
|
+
subcommand flags, HTTP endpoint paths, encrypted-key storage format) match the
|
|
406
|
+
Go original so that databases created by either implementation work with the
|
|
407
|
+
other (assuming you set `AIROUTER_SECRET` to the same value).
|
|
408
|
+
|
|
409
|
+
## License
|
|
410
|
+
|
|
411
|
+
MIT — same as the original Go project. See [LICENSE](https://github.com/mrmhthegreat/airouter/blob/main/LICENSE).
|