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 +21 -0
- aivana-0.2.0/PKG-INFO +590 -0
- aivana-0.2.0/README.md +564 -0
- aivana-0.2.0/aivana/__init__.py +93 -0
- aivana-0.2.0/aivana/__main__.py +10 -0
- aivana-0.2.0/aivana/cli.py +631 -0
- aivana-0.2.0/aivana/client.py +391 -0
- aivana-0.2.0/aivana/envelopes.py +68 -0
- aivana-0.2.0/aivana/exceptions.py +41 -0
- aivana-0.2.0/aivana/py.typed +0 -0
- aivana-0.2.0/aivana.egg-info/PKG-INFO +590 -0
- aivana-0.2.0/aivana.egg-info/SOURCES.txt +20 -0
- aivana-0.2.0/aivana.egg-info/dependency_links.txt +1 -0
- aivana-0.2.0/aivana.egg-info/entry_points.txt +2 -0
- aivana-0.2.0/aivana.egg-info/requires.txt +2 -0
- aivana-0.2.0/aivana.egg-info/top_level.txt +1 -0
- aivana-0.2.0/pyproject.toml +54 -0
- aivana-0.2.0/setup.cfg +4 -0
- aivana-0.2.0/tests/test_cli.py +121 -0
- aivana-0.2.0/tests/test_conformance.py +112 -0
- aivana-0.2.0/tests/test_errors.py +136 -0
- aivana-0.2.0/tests/test_parity.py +243 -0
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
|