aivana 0.2.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.
aivana-0.2.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Aivana
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.
aivana-0.2.0/PKG-INFO ADDED
@@ -0,0 +1,590 @@
1
+ Metadata-Version: 2.4
2
+ Name: aivana
3
+ Version: 0.2.0
4
+ Summary: Aivana Intelligence API — Python SDK
5
+ License-Expression: Apache-2.0
6
+ Project-URL: Homepage, https://github.com/Aivana-Inc/aivana-sdk-python
7
+ Project-URL: Repository, https://github.com/Aivana-Inc/aivana-sdk-python
8
+ Project-URL: Issues, https://github.com/Aivana-Inc/aivana-sdk-python/issues
9
+ Keywords: ai,llm,intelligence,api,aivana
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
18
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
19
+ Classifier: Typing :: Typed
20
+ Requires-Python: >=3.10
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Requires-Dist: httpx>=0.27
24
+ Requires-Dist: pydantic>=2
25
+ Dynamic: license-file
26
+
27
+ # aivana
28
+
29
+ Python client for the [Aivana Intelligence API](https://github.com/Aivana-Inc/aivana-sdk-python).
30
+
31
+ Requires Python 3.10 or newer. Built on `httpx`, with sync, async, and streaming
32
+ interfaces.
33
+
34
+ ## Install
35
+
36
+ ```bash
37
+ pip install aivana
38
+ ```
39
+
40
+ ## Quick start
41
+
42
+ Configuration is module-level, Stripe-style:
43
+
44
+ ```python
45
+ import aivana
46
+
47
+ aivana.api_key = "ai_live_xxx"
48
+
49
+ res = aivana.generate("Should we enter the EU market in 2027?")
50
+ print(res.answer)
51
+ ```
52
+
53
+ Your API key is the only required setting. `aivana.api_key = ...` and
54
+ `aivana.set_api_key(...)` are equivalent.
55
+
56
+ `api_base` defaults to the hosted API at `https://developers.aivana.ai`, the same
57
+ default as `@aivana/sdk`. Point it elsewhere only to run against your own
58
+ deployment:
59
+
60
+ ```python
61
+ aivana.set_api_base("http://localhost:8088") # local engine
62
+ ```
63
+
64
+ ## Command line
65
+
66
+ The package also installs an `aivana` command. To use it without adding the SDK
67
+ to a project, install it as a standalone tool:
68
+
69
+ ```bash
70
+ pipx install aivana # or run it without installing: uvx aivana "..."
71
+ export AIVANA_API_KEY=ai_live_xxx
72
+ aivana "Should we enter the EU market in 2027?"
73
+ ```
74
+
75
+ The answer streams to stdout as it is written; progress, the trace and errors go
76
+ to stderr. So `aivana "..." > answer.md` saves just the answer, and the command
77
+ works in pipes. Text piped in is sent ahead of the question:
78
+
79
+ ```bash
80
+ git diff | aivana "Review this change" --effort high
81
+ aivana "Summarise the three biggest risks" < contract.txt
82
+ aivana "What's driving the dip in this chart?" --image chart.png
83
+ aivana "Postgres or DynamoDB for a write-heavy API?" --shape tradeoffs --trace
84
+ aivana "Extract the invoice number and total" --shape extract --json < invoice.txt
85
+ ```
86
+
87
+ Every option maps to one the SDK already has:
88
+
89
+ | option | SDK equivalent |
90
+ |---|---|
91
+ | `--effort auto\|low\|medium\|high` | `effort` |
92
+ | `--shape SHAPE` | `output_shape` |
93
+ | `--web` / `--no-web` | `web_search=True` / `False`; neither means no search, the default for API keys |
94
+ | `--system TEXT` | `system` |
95
+ | `--assistant-name NAME` | `assistant_name` |
96
+ | `--max-tokens N` | `max_tokens` |
97
+ | `--temperature T` | `temperature` |
98
+ | `--image PATH` (repeatable) | `attachments` |
99
+ | `--trace` | `intelligence_trace=True`, printed to stderr |
100
+ | `--json` | the whole `GenerateResponse` as JSON, without streaming |
101
+
102
+ As in the SDK, there is deliberately no option to choose a model or provider.
103
+ `AIVANA_API_BASE` points the command at another deployment, like
104
+ `set_api_base()`; `python -m aivana` runs the same program.
105
+
106
+ The Node CLI (`npm install -g @aivana/cli`) installs a command with the same name,
107
+ and both must behave identically. That is enforced by a shared conformance suite,
108
+ [`conformance/cli.json`](conformance/cli.json), which each implementation runs in
109
+ its own tests.
110
+
111
+ Scripts can branch on the exit code:
112
+
113
+ | code | meaning |
114
+ |---|---|
115
+ | 0 | success |
116
+ | 1 | the request failed |
117
+ | 2 | bad usage |
118
+ | 3 | authentication problem: no key, or an invalid or expired one |
119
+ | 4 | rate limited: wait, then retry |
120
+ | 5 | out of credits: top up in AI Studio |
121
+ | 6 | temporary failure (network, timeout, upstream): safe to retry |
122
+ | 130 | interrupted |
123
+
124
+ Two things worth knowing:
125
+
126
+ - **The key comes from `AIVANA_API_KEY` only.** There is no `--api-key` flag, on
127
+ purpose: a key typed as an argument is saved in your shell history and is
128
+ visible to other users in the process list.
129
+ - **Quote the question.** Unquoted words work, but the shell acts on characters
130
+ such as `?`, `*` and `'` before `aivana` sees them. `aivana ask "..."` is the
131
+ same as `aivana "..."`, for a question that starts with a word the CLI keeps
132
+ for future commands (`chat`, `usage`, ...).
133
+
134
+ ## Streaming
135
+
136
+ ```python
137
+ async for chunk in aivana.generate_stream("Explain the CAP theorem"):
138
+ print(chunk.delta, end="")
139
+ ```
140
+
141
+ ## Async
142
+
143
+ ```python
144
+ res = await aivana.generate_async("Summarise our Q3 churn drivers.")
145
+ ```
146
+
147
+ ## Conversation history
148
+
149
+ Aivana is stateless — it never stores your conversations. To ask a follow-up you
150
+ send the prior turns back with the next question. Two ways to do that.
151
+
152
+ **Let the SDK track it.** `Chat` keeps the history in memory and appends each turn:
153
+
154
+ ```python
155
+ chat = aivana.Chat()
156
+ chat.send("We're choosing between Postgres and DynamoDB.")
157
+ chat.send("What changes if write volume triples?") # remembers the above
158
+ chat.reset() # start fresh
159
+ ```
160
+
161
+ **Or manage it yourself** — which is what you want when the history lives in your
162
+ own database and spans processes, requests or machines:
163
+
164
+ ```python
165
+ messages = [
166
+ {"role": "user", "content": "We're choosing between Postgres and DynamoDB."},
167
+ {"role": "assistant", "content": previous_answer},
168
+ {"role": "user", "content": "What changes if write volume triples?"},
169
+ ]
170
+
171
+ res = aivana.generate(messages=messages)
172
+ ```
173
+
174
+ Pass `messages` **instead of** a prompt — the last `user` message is the current
175
+ question. Each item is `{"role": ..., "content": ...}` in chronological order, with
176
+ role `"user"`, `"assistant"` or `"system"`.
177
+
178
+ A `"system"` message is lifted into the `system` field for you, so these are
179
+ equivalent:
180
+
181
+ ```python
182
+ aivana.generate(messages=[{"role": "system", "content": "Answer in bullets."},
183
+ {"role": "user", "content": "Why did latency spike?"}])
184
+
185
+ aivana.generate("Why did latency spike?", system="Answer in bullets.")
186
+ ```
187
+
188
+ If you pass **both**, the explicit `system` argument wins and the system message is
189
+ ignored — the two are never concatenated, because a merge order you cannot see is
190
+ worse than a rule you can.
191
+
192
+ ### Follow-ups that refer back
193
+
194
+ For replies like "yes, do that" or "the second one", also pass `previous_intent`
195
+ and `pending_action` from the previous response. They are what let Aivana resolve
196
+ a bare "yes" against what was actually offered:
197
+
198
+ ```python
199
+ first = aivana.generate("Should we migrate to DynamoDB?")
200
+
201
+ second = aivana.generate(
202
+ messages=messages,
203
+ previous_intent=first.intent.name,
204
+ pending_action=first.pending_action,
205
+ )
206
+ ```
207
+
208
+ `Chat` does this for you automatically — it is only manual history that needs it.
209
+
210
+ ### Limits
211
+
212
+ | | current default |
213
+ |---|---|
214
+ | Messages per request | 40 |
215
+ | Characters per message | 200,000 |
216
+ | Characters per prompt | 200,000 |
217
+
218
+ History is re-sent on every turn and **billed every turn**, because nothing is
219
+ stored server-side. On a long conversation, trim or summarise old turns rather
220
+ than replaying all 40 — that is the single biggest lever on what a chat costs.
221
+
222
+ ## Files and documents
223
+
224
+ **Only images can be attached.** `image/png`, `image/jpeg`, `image/webp`,
225
+ `image/gif` — up to 6 per request, 8 MiB each decoded.
226
+
227
+ PDF, Word and Excel files are **not** supported. Sending one raises
228
+ `InvalidRequestError` — the file is rejected, never silently ignored. The message
229
+ is deliberately terse ("request input was rejected"): it confirms the request was
230
+ the problem, but it does not name the offending type, so check the list above
231
+ rather than the error text.
232
+
233
+ To ask about a document, extract its text yourself and pass that as the prompt.
234
+ The extraction libraries below are not dependencies of this SDK — install
235
+ whichever you need:
236
+
237
+ **PDF** — `pip install pypdf`
238
+
239
+ ```python
240
+ from pypdf import PdfReader
241
+ text = "\n".join(page.extract_text() or "" for page in PdfReader("report.pdf").pages)
242
+ ```
243
+
244
+ **Word** — `pip install python-docx`
245
+
246
+ ```python
247
+ from docx import Document
248
+ text = "\n".join(p.text for p in Document("contract.docx").paragraphs)
249
+ ```
250
+
251
+ **Excel / CSV** — `pip install pandas openpyxl`
252
+
253
+ ```python
254
+ import pandas as pd
255
+ text = pd.read_excel("q3.xlsx").to_markdown(index=False)
256
+ ```
257
+
258
+ Then send the text as the prompt:
259
+
260
+ ```python
261
+ res = aivana.generate(
262
+ f"Summarise the three biggest risks in this document.\n\n{text}",
263
+ system="Quote the passage each risk comes from.",
264
+ )
265
+ ```
266
+
267
+ Two things worth doing:
268
+
269
+ - **Send text, not markup.** Stripped text costs far fewer tokens than raw HTML or
270
+ XML, and answers are usually better for it.
271
+ - **Watch the size.** A long document can approach the 200,000-character prompt
272
+ limit. For a large file, extract the relevant sections rather than the whole
273
+ thing — and remember every character is billed.
274
+
275
+ A scanned PDF with no text layer extracts to nothing. Render those pages to PNG
276
+ and send them as image attachments instead.
277
+
278
+ ## Options
279
+
280
+ Every option is optional, and every entrypoint — `generate`, `generate_async`,
281
+ `generate_stream`, `Chat` — accepts all of them as keyword arguments.
282
+
283
+ Omitting one is not a gap to fill in: it hands the decision to Aivana, which tunes
284
+ temperature, answer length and web search per question. Pass a value to override
285
+ that.
286
+
287
+ | option | type | default when omitted |
288
+ |---|---|---|
289
+ | `system` | str | no persona — Aivana's own voice |
290
+ | `assistant_name` | str | the assistant does not name itself |
291
+ | `web_search` | bool | no search: the default for API keys |
292
+ | `effort` | `"auto"`/`"low"`/`"medium"`/`"high"` | `"auto"` — Aivana decides |
293
+ | `temperature` | 0.0–2.0 | chosen per request |
294
+ | `top_p` | 0.0–1.0 | each model's own default |
295
+ | `stop_sequences` | list[str] | none — the answer ends naturally |
296
+ | `intelligence_trace` | bool | off — no trace is returned |
297
+ | `max_tokens` | int | sized to the question |
298
+ | `output_shape` | str | `"auto"` |
299
+ | `attachments` | list | none |
300
+ | `metadata` | dict | none |
301
+
302
+ ## Choose how much intelligence to spend
303
+
304
+ `effort` is the one option that is about Aivana rather than about a model.
305
+ `temperature`, `top_p` and `max_tokens` shape how a model writes; `effort`
306
+ decides how much work goes into the answer in the first place.
307
+
308
+ ```python
309
+ # A lookup you want back fast and cheap.
310
+ aivana.generate("What's the default port for Postgres?", effort="low")
311
+
312
+ # A decision you are going to act on.
313
+ aivana.generate(
314
+ "Should we move billing off Stripe before the Series A?",
315
+ effort="high",
316
+ )
317
+ ```
318
+
319
+ | band | what happens | when to reach for it |
320
+ |---|---|---|
321
+ | `"auto"` | Aivana judges from the question | the default — leave it alone unless you know better than the question does |
322
+ | `"low"` | the fastest, cheapest path: one independent perspective | lookups, classification, formatting, anything with one right answer |
323
+ | `"medium"` | two independent perspectives, compared and reconciled | contested or subjective questions with a bounded blast radius |
324
+ | `"high"` | three or more perspectives | hard, high-stakes, open-ended questions |
325
+
326
+ Two things worth knowing:
327
+
328
+ - **It is a bound, not an instruction.** Aivana still reads the question and
329
+ still decides how to answer it — `effort` only constrains how far it may go.
330
+ - **It is not a length control.** `"low"` does not mean "short"; use
331
+ `max_tokens` for that. Cost scales roughly with the band, so `"high"` on a
332
+ trivial question spends more for no gain — which is exactly the judgement
333
+ `"auto"` exists to make.
334
+
335
+ ## Give the assistant a persona
336
+
337
+ `system` is your own instructions — tone, format, domain, things to refuse:
338
+
339
+ ```python
340
+ res = aivana.generate(
341
+ "A customer wants a refund after 40 days.",
342
+ system=("You are a support lead for a UK retailer. Answer in three short "
343
+ "bullets. Cite the policy rule you applied. Never promise a refund "
344
+ "outside policy."),
345
+ )
346
+ ```
347
+
348
+ `assistant_name` sets the name it presents as:
349
+
350
+ ```python
351
+ res = aivana.generate("Who are you?", assistant_name="Acme Copilot")
352
+ # → "I'm Acme Copilot..."
353
+ ```
354
+
355
+ Use `assistant_name` rather than writing "your name is Acme" into `system`. A name
356
+ asked for inside a system prompt is only a request the model may or may not honour
357
+ — measured at roughly one time in three. `assistant_name` is substituted before the
358
+ model sees anything, so it always holds.
359
+
360
+ Two things to know:
361
+
362
+ **`system` is additive, not a replacement.** Aivana keeps its own instructions and
363
+ they win on conflict. You can shape persona, tone, format and domain focus — you
364
+ cannot use it to make Aivana reveal which underlying models produced an answer.
365
+
366
+ **Keep it short.** Aivana may re-send your system prompt internally more than once
367
+ while answering, so a long persona costs more tokens than its length suggests. The
368
+ 8000-character limit is checked client-side, so an oversized prompt raises
369
+ `InvalidRequestError` before the request is sent.
370
+
371
+ ## Web search
372
+
373
+ ### Randomness: `temperature` or `top_p`, not both
374
+
375
+ Both control how varied an answer is; they just do it differently. `temperature`
376
+ reshapes the whole probability distribution, `top_p` narrows the pool to the most
377
+ likely tokens whose probabilities add up to your value.
378
+
379
+ ```python
380
+ aivana.generate("Extract the invoice number", top_p=0.1) # tight, predictable
381
+ aivana.generate("Ten campaign taglines", temperature=1.2) # varied
382
+ ```
383
+
384
+ Set **one** of the two. Sending both is accepted, but you are then steering the
385
+ same thing with two dials and the result is harder to reason about — and for some
386
+ questions Aivana cannot pass both through, in which case `top_p` wins and the
387
+ temperature is dropped for that call.
388
+
389
+ `top_p=0.0` is legal and is the most deterministic setting there is. Omitting the
390
+ option is **not** the same as `1.0`: omitted leaves the choice to Aivana.
391
+
392
+ ### Stop sequences
393
+
394
+ Up to four strings. The answer ends where the first one appears, and the string
395
+ itself is not returned.
396
+
397
+ ```python
398
+ aivana.generate("Answer, then stop.", stop_sequences=["###", "\n\nUser:"])
399
+ ```
400
+
401
+ Useful when you are parsing the answer and know its end marker. Two things to
402
+ know: it shapes the output you receive, so it behaves the same on every question
403
+ — and the text past the marker is still generated and still billed, so this is not
404
+ a way to spend less.
405
+
406
+ ### Intelligence Trace
407
+
408
+ Aivana decides how much intelligence each request needs. `intelligence_trace`
409
+ asks it to show its working.
410
+
411
+ ```python
412
+ resp = aivana.generate(
413
+ "Compare Postgres and DynamoDB for a write-heavy API.",
414
+ intelligence_trace=True,
415
+ )
416
+
417
+ print(resp.trace["summary"]["route"]) # "2-model verification"
418
+ for step in resp.trace["steps"]:
419
+ print(step["at_ms"], step["title"], "—", step["detail"])
420
+ ```
421
+
422
+ ```
423
+ 1204 Understanding Request — Multi-part request with several considerations
424
+ 1240 Fresh Data Check — Existing knowledge is sufficient; no live lookup needed
425
+ 1255 Selecting Intelligence Path — A 2-model verification path would provide the most reliable answer
426
+ 3980 Establishing Lead Perspective — Primary analysis generated
427
+ 6310 Independent Perspectives — A second perspective independently analyzed the request
428
+ 6402 Evaluating Perspectives — Perspectives agreed; the answer was confirmed rather than changed
429
+ 8120 Final Synthesis — Findings combined into a single coherent answer
430
+ 8155 Completed — Response delivered
431
+ ```
432
+
433
+ The trace changes with the route. A simple question shows four steps and says
434
+ additional perspectives were unlikely to improve the answer; a question needing
435
+ current information shows the live-source lookup and the validation against what
436
+ came back. `trace["summary"]` carries the route, how many perspectives were
437
+ engaged, and whether fresh data was used; `trace["why_this_route"]` explains the
438
+ choice in plain sentences.
439
+
440
+ With `stream=True` the same information arrives as `trace` chunks while the
441
+ answer is being produced, so you can render the run as it happens:
442
+
443
+ ```python
444
+ for chunk in aivana.generate("...", stream=True, intelligence_trace=True):
445
+ if chunk.event == "delta":
446
+ print(chunk.delta, end="")
447
+ elif chunk.event == "trace" and "step" in chunk.data:
448
+ step = chunk.data["step"]
449
+ print(f"\n[{step['status']}] {step['title']}")
450
+ ```
451
+
452
+ Each step arrives twice — once as it starts, once as it finishes — followed by a
453
+ single consolidated trace at the end.
454
+
455
+ The trace describes decisions and outcomes. It does not name the models that
456
+ answered, and it never exposes scoring, thresholds or prompts.
457
+
458
+ `web_search` has three states:
459
+
460
+ ```python
461
+ aivana.generate("What did the EU AI Act change in August?", web_search=True)
462
+ aivana.generate("Explain how quicksort works", web_search=False)
463
+ aivana.generate("Is our pricing still competitive?") # the default: no search
464
+ ```
465
+
466
+ | value | behaviour |
467
+ |---|---|
468
+ | `True` | always search the web before answering |
469
+ | `False` | never search |
470
+ | *omitted* | the API's default applies; for an API key, that is no search |
471
+
472
+ On an API key the default is **off** — a search never happens unless you ask for
473
+ one, so it cannot turn up unannounced on your bill. Omitting the option and
474
+ passing `False` are still different requests: `False` stays "never search" even
475
+ if the API's default changes, while an omitted option follows it. Grounding costs extra tokens
476
+ and latency, so reach for `True` on current events, prices, releases, competitors
477
+ and anything else that dates; leave it off for reasoning, code, writing and
478
+ explanation, which do not improve with a web lookup.
479
+
480
+ ## Temperature and length
481
+
482
+ ```python
483
+ res = aivana.generate(
484
+ "Draft a launch plan.",
485
+ temperature=0.2, # omit → chosen per request
486
+ max_tokens=500, # omit → sized to the question
487
+ )
488
+ ```
489
+
490
+ `temperature` accepts `0.0`–`2.0`. Lower is more deterministic, higher more varied.
491
+
492
+ `max_tokens` is a **ceiling, not a target.** It can only shorten an answer — it
493
+ never raises the model-aware limit, so a very large value has no effect. When you
494
+ lower it, Aivana shortens what it aims to write rather than letting a full-length
495
+ answer get cut off mid-sentence.
496
+
497
+ ## Recipes
498
+
499
+ **A support assistant that never searches the web.** Options passed to `Chat` apply
500
+ to every turn, so set the persona and the search policy once:
501
+
502
+ ```python
503
+ support = aivana.Chat(
504
+ assistant_name="Acme Support",
505
+ system=("You are a support lead for Acme. Three bullets maximum. "
506
+ "If the answer isn't in policy, say so and offer to escalate."),
507
+ web_search=False, # answers come from policy, not the open web
508
+ temperature=0.2, # consistent phrasing across tickets
509
+ )
510
+
511
+ support.send("Customer wants a refund after 40 days.")
512
+ support.send("They're now threatening a chargeback.") # remembers the above
513
+ ```
514
+
515
+ **A research assistant that always searches**, overridden per turn where it does
516
+ not need to:
517
+
518
+ ```python
519
+ research = aivana.Chat(web_search=True)
520
+
521
+ research.send("What are the current enterprise pricing tiers for our competitors?")
522
+ research.send("Summarise that as a table", web_search=False) # no lookup needed
523
+ ```
524
+
525
+ Keyword arguments passed to `send()` win over the ones set on `Chat` for that turn.
526
+
527
+ **Structured output you can parse.** Combine a low temperature with `output_shape`:
528
+
529
+ ```python
530
+ res = aivana.generate(
531
+ transcript,
532
+ output_shape="extract",
533
+ temperature=0,
534
+ system="Return only the fields asked for. Use null when a field is absent.",
535
+ )
536
+
537
+ print(res.structured) # parsed dict, or None
538
+ print(res.structured_error) # why parsing failed, if it did
539
+ ```
540
+
541
+ **Streaming with a persona.** Options behave identically on the streaming calls:
542
+
543
+ ```python
544
+ for chunk in aivana.generate(
545
+ "Explain our outage to a customer.",
546
+ stream=True,
547
+ assistant_name="Acme Copilot",
548
+ system="Plain language. No blame. Lead with impact, then the fix.",
549
+ max_tokens=300,
550
+ ):
551
+ print(chunk.delta, end="", flush=True)
552
+ ```
553
+
554
+ **Images.** Send a screenshot or diagram with the question:
555
+
556
+ ```python
557
+ import base64
558
+
559
+ res = aivana.generate(
560
+ "What's driving the dip in this chart?",
561
+ attachments=[{
562
+ "mime_type": "image/png",
563
+ "data": base64.b64encode(open("chart.png", "rb").read()).decode(),
564
+ }],
565
+ )
566
+ ```
567
+
568
+ `data` takes raw base64 or a full data URL. Up to 6 images per request, 8 MiB each
569
+ decoded, in `image/png`, `image/jpeg`, `image/webp` or `image/gif`. Attachments
570
+ apply to the **current turn only** and are never replayed, so resend the image with
571
+ a follow-up about it.
572
+
573
+ ## Errors
574
+
575
+ Every failure raises a subclass of `AivanaError`:
576
+
577
+ `AuthError` · `RateLimitError` · `InvalidRequestError` · `UpstreamError`
578
+
579
+ ```python
580
+ from aivana import RateLimitError
581
+
582
+ try:
583
+ aivana.generate("...")
584
+ except RateLimitError as err:
585
+ backoff(err)
586
+ ```
587
+
588
+ ## License
589
+
590
+ Apache-2.0