airouter-py 0.1.0__py3-none-any.whl

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/__init__.py ADDED
@@ -0,0 +1,245 @@
1
+ """airouter — one-import way to use airouter from your own Python project.
2
+
3
+ Python port of the Go ``airouter.go`` facade. Free-tier AI providers behind
4
+ one call, with automatic failover, limit tracking and encrypted key storage.
5
+
6
+ Example::
7
+
8
+ import airouter
9
+
10
+ c = airouter.open(airouter.Options(db="ai.db"))
11
+
12
+ # once: put your provider keys in the database (encrypted)
13
+ c.add_free_pool({"GROQ_API_KEY": "gsk_...", "GEMINI_API_KEY": "..."})
14
+
15
+ text = c.chat("Write one sentence about rain")
16
+
17
+ # full control
18
+ resp = c.ask(airouter.Request(system="Be brief", prompt="hi", json=True))
19
+
20
+ # expose OpenAI API + web UI from your own server
21
+ # c.handler(admin_token=os.environ["AIROUTER_ADMIN_TOKEN"])
22
+ """
23
+ from __future__ import annotations
24
+
25
+ import os
26
+ from typing import Optional
27
+
28
+ from .router import (
29
+ BootstrapOptions,
30
+ Options,
31
+ Router,
32
+ TenantLimits,
33
+ TenantPolicy,
34
+ new,
35
+ )
36
+ from .store import (
37
+ EncryptedStore,
38
+ MemoryStore,
39
+ SQLStore,
40
+ Store,
41
+ hash_key,
42
+ master_secret,
43
+ new_api_key,
44
+ open_sqlite_store,
45
+ )
46
+ from .types import (
47
+ Attempt,
48
+ BadRequestError,
49
+ ErrBadRequest,
50
+ ErrNoProviders,
51
+ ErrNotFound,
52
+ ErrTenantDisabled,
53
+ ErrTimeout,
54
+ ErrUnauthorized,
55
+ ErrUnknownTenant,
56
+ ExhaustedError,
57
+ AllFailedError,
58
+ HTTPError,
59
+ Message,
60
+ ProviderConfig,
61
+ Request,
62
+ Response,
63
+ SpeakRequest,
64
+ SpeakResponse,
65
+ Tenant,
66
+ TenantLimitError,
67
+ TranscribeRequest,
68
+ TranscribeResponse,
69
+ )
70
+ from . import preset
71
+
72
+ __version__ = "0.1.0"
73
+
74
+
75
+ # ---------------------------------------------------------------------------
76
+ # Client + Open()
77
+ # ---------------------------------------------------------------------------
78
+
79
+
80
+ class Client:
81
+ """A :class:`Router` plus conveniences.
82
+
83
+ Every :class:`Router` method (``generate``, ``speak``, ``transcribe``,
84
+ ``create_tenant``, ``status``, ``usage`` ...) is available on the client
85
+ too.
86
+ """
87
+
88
+ def __init__(self, r: Router) -> None:
89
+ self.router = r
90
+ # Re-export every Router method on the client for convenience.
91
+ for name in (
92
+ "generate", "speak", "transcribe", "create_tenant", "authenticate",
93
+ "update_tenant_profile", "rotate_tenant_key", "save_provider",
94
+ "delete_provider", "clear_pause", "set_disabled", "set_provider_key",
95
+ "bootstrap_providers", "bootstrap_providers_opts", "status", "usage",
96
+ "list_tenant_providers", "export_tenant_providers",
97
+ "add_tenant_provider", "import_tenant_providers",
98
+ "add_tenant_catalog", "update_tenant_limits",
99
+ "set_tenant_provider_key", "set_tenant_provider_disabled",
100
+ "reset_tenant_provider", "delete_tenant_provider",
101
+ "ollama_models", "add_tenant_ollama", "refresh_providers",
102
+ ):
103
+ setattr(self, name, getattr(r, name))
104
+
105
+ @property
106
+ def store(self) -> Store:
107
+ return self.router.store
108
+
109
+ @property
110
+ def now(self):
111
+ return self.router.now
112
+
113
+ @property
114
+ def session(self):
115
+ return self.router.session
116
+
117
+ @property
118
+ def tpolicy(self) -> TenantPolicy:
119
+ return self.router.tpolicy
120
+
121
+ @property
122
+ def ollama_url(self) -> str:
123
+ return self.router.ollama_url
124
+
125
+ @property
126
+ def logf(self):
127
+ return self.router.logf
128
+
129
+ def _hydrate(self, p, st, now):
130
+ return self.router._hydrate(p, st, now)
131
+
132
+ def _acquire(self, p, st, now):
133
+ return self.router._acquire(p, st, now)
134
+
135
+ def _candidates(self, req):
136
+ return self.router._candidates(req)
137
+
138
+ def _snapshot(self):
139
+ return self.router._snapshot()
140
+
141
+ def _call_provider(self, p, msgs, req):
142
+ return self.router._call_provider(p, msgs, req)
143
+
144
+ def close(self) -> None:
145
+ """Release the database."""
146
+ self.store.close()
147
+
148
+ def chat(self, prompt: str) -> str:
149
+ """Send one prompt and return the answer text."""
150
+ r = self.generate(Request(prompt=prompt))
151
+ return r.text
152
+
153
+ def ask(self, req: Request) -> Response:
154
+ """:meth:`generate` with the full request/response (system prompt, JSON mode, ...)."""
155
+ return self.generate(req)
156
+
157
+ def add_free_pool(self, keys: dict[str, str], categories: Optional[list[str]] = None) -> tuple[list[str], list[str]]:
158
+ """Import the curated free-tier catalog for every provider you supply a key for.
159
+
160
+ ``keys`` is keyed by env var name (``"GROQ_API_KEY"``,
161
+ ``"GEMINI_API_KEY"``, ``"OPENROUTER_API_KEY"``, ...). Keys are stored
162
+ encrypted, so no environment variables are needed afterwards. Keys
163
+ already set in the environment are used too.
164
+ """
165
+ return self.bootstrap_providers_opts(BootstrapOptions(
166
+ keys=keys, store_keys=True, categories=categories,
167
+ ))
168
+
169
+ def handler(self, admin_token: str = ""):
170
+ """Return the HTTP API: OpenAI-compatible ``/v1/chat/completions``, the native API, and the web UI at ``/``.
171
+
172
+ ``admin_token`` enables admin endpoints (empty disables them).
173
+ """
174
+ from .server import new_handler
175
+ return new_handler(self.router, admin_token)
176
+
177
+
178
+ def open(o: Options) -> Client:
179
+ """Open the SQLite database and return a ready client.
180
+
181
+ Provider keys are encrypted with ``$AIROUTER_SECRET`` or a key file next
182
+ to the database.
183
+ """
184
+ if not o.store:
185
+ db = o.db or os.environ.get("AIROUTER_DB", "") or "airouter.db"
186
+ logf = o.logf
187
+ st, _source = open_sqlite_store(db, logf)
188
+ o.store = st
189
+ return new_client(o.store, o)
190
+
191
+
192
+ def new_client(st: Store, o: Options) -> Client:
193
+ """Build a client on any :class:`Store` (for example :class:`MemoryStore` in tests, or your own Postgres impl)."""
194
+ ro = o
195
+ ro.store = st
196
+ r = new(ro)
197
+ return Client(r)
198
+
199
+
200
+ __all__ = [
201
+ "Client",
202
+ "Options",
203
+ "Router",
204
+ "BootstrapOptions",
205
+ "TenantLimits",
206
+ "TenantPolicy",
207
+ "open",
208
+ "new_client",
209
+ # stores
210
+ "Store",
211
+ "MemoryStore",
212
+ "SQLStore",
213
+ "EncryptedStore",
214
+ "open_sqlite_store",
215
+ "master_secret",
216
+ "new_api_key",
217
+ "hash_key",
218
+ # types
219
+ "Message",
220
+ "Attempt",
221
+ "Request",
222
+ "Response",
223
+ "SpeakRequest",
224
+ "SpeakResponse",
225
+ "TranscribeRequest",
226
+ "TranscribeResponse",
227
+ "ProviderConfig",
228
+ "Tenant",
229
+ # errors
230
+ "BadRequestError",
231
+ "ErrBadRequest",
232
+ "ErrNoProviders",
233
+ "ErrNotFound",
234
+ "ErrTenantDisabled",
235
+ "ErrTimeout",
236
+ "ErrUnauthorized",
237
+ "ErrUnknownTenant",
238
+ "ExhaustedError",
239
+ "AllFailedError",
240
+ "HTTPError",
241
+ "TenantLimitError",
242
+ # subpackages
243
+ "preset",
244
+ "__version__",
245
+ ]