Nova ADK (Python)
The official Python SDK for the Nova agentic AI platform — agents, chat, orchestration, voice, billing, and more, over a typed async client.
Install
pip install novalab-adk
Quickstart
- API keys come with every paid plan, from Pro (a Free plan's key gets
PlanRequired). Pick a plan at https://app.novalab.build/plans. - Create a key in Nova under Settings, Developer, and set it as
NOVA_API_KEY. - First call:
import asyncio
from novalab_adk import NovaClient
async def main():
async with NovaClient() as nova: # reads NOVA_API_KEY (or NovaClient(api_key="nova_..."))
msg = await nova.messages.create(
model="nova-flagship",
max_tokens=512,
messages=[{"role": "user", "content": "Write one sentence about the fjords."}],
)
print(msg.text)
asyncio.run(main())
Nova models: nova-max, nova-flagship, nova-reasoning, nova-fast. The
model you name in messages.create is the model that runs. Hosted in the EU.
Chat
nova.chat.send() is Nova's full chat: model="auto" (the default) lets
Nova pick the model per message, and the conversation is kept server-side.
from novalab_adk import ChatMessageParams
reply = await nova.chat.send(ChatMessageParams(message="Summarise the latest sales report"))
print(reply.response)
again = await nova.chat.send(ChatMessageParams(message="Shorter, please.", session_id=reply.session_id))
Messages: streaming, your own tools, images
from novalab_adk import image_block, tool_result_block
# Streaming
async for event in nova.messages.stream(model="nova-fast", messages=[{"role": "user", "content": "Hello"}]):
print(event.text, end="", flush=True)
# Your own tools: run them when the answer stops with "tool_use", send the result back
tools = [{"name": "get_weather", "description": "Current weather",
"input_schema": {"type": "object", "properties": {"city": {"type": "string"}}}}]
messages = [{"role": "user", "content": "Weather in Oslo?"}]
msg = await nova.messages.create(tools=tools, messages=messages)
while msg.stop_reason == "tool_use":
results = [tool_result_block(c.id, my_weather(**c.input)) for c in msg.tool_uses] # my_weather: your code
messages += [{"role": "assistant", "content": [b.model_dump() for b in msg.content]},
{"role": "user", "content": results}]
msg = await nova.messages.create(tools=tools, messages=messages)
print(msg.text)
# Images (PNG, JPEG, GIF, WebP)
msg = await nova.messages.create(messages=[{"role": "user", "content": [
image_block("photo.png"), {"type": "text", "text": "What is in this picture?"}]}])
JSON answers, files, thinking (2.17)
from novalab_adk import document_block, json_schema_format
# JSON that matches your schema (InvalidJsonOutput when it cannot)
msg = await nova.messages.create(messages=[{"role": "user", "content": "Invoice: ACME, total 12 EUR"}],
response_format=json_schema_format({"type": "object", "properties": {
"vendor": {"type": "string"}, "total": {"type": "number"}},
"required": ["vendor", "total"]}))
print(msg.parsed["total"])
# Answer from a file, with page numbers
f = await nova.files.upload(path="contract.pdf")
msg = await nova.messages.create(messages=[{"role": "user", "content": [
document_block(f.file_id), {"type": "text", "text": "What is the notice period?"}]}])
print(msg.text, [(c.page, c.quote[:40]) for c in msg.citations])
# Think longer (Pro plan and higher)
msg = await nova.messages.create(thinking={"effort": "high"}, messages=[{"role": "user", "content": "Check this spec ..."}])
print(msg.thinking, msg.text)
Try them first in the API Playground: https://app.novalab.build/playground
Plan features and credits
plan = await nova.plan_features() # GET /v1/plan/features
print(plan.plan, plan.allows("helpers"), plan.limits["monthly_credits"])
credits = await nova.billing.credits() # balance, used %, at_zero, top-up link
packs = await nova.billing.topup_packs()
link = await nova.billing.topup_checkout(packs[0].credits) # open link.checkout_url to pay
Also: nova.models.list(), nova.billing.usage_history(days),
nova.billing.operation_costs(), nova.billing.catalog(),
nova.billing.invoices(), nova.billing.portal(), and
nova.chat.completions(messages) for the common chat completions format.
Streaming chat and agent mode
nova.chat.stream() yields typed events as the turn runs. With
agent_mode=True Nova works through tools step by step; tools with side
effects pause for your approval.
from novalab_adk.types.chat_stream import (
ChatStreamParams, TokenEvent, ArtifactEvent, TaskListEvent,
ToolStartEvent, ToolResultEvent, ApprovalRequestEvent, DoneEvent, UnknownEvent,
)
params = ChatStreamParams(message="Write a one-page brief for Acme AI", agent_mode=True)
async for ev in nova.chat.stream(params):
if isinstance(ev, TokenEvent):
print(ev.content, end="", flush=True)
elif isinstance(ev, TaskListEvent):
print([f"{t.status}: {t.text}" for t in ev.tasks])
elif isinstance(ev, ToolStartEvent):
print("tool:", ev.name)
elif isinstance(ev, ApprovalRequestEvent):
await nova.agent.approve(ev.id) # or nova.agent.reject(ev.id)
elif isinstance(ev, ArtifactEvent):
print("artifact:", ev.artifact.title, "v", ev.artifact.version, ev.artifact.formats)
elif isinstance(ev, DoneEvent):
print("\nconfidence", ev.confidence)
elif isinstance(ev, UnknownEvent):
pass # newer server event; full payload in ev.raw
Other events: MetaEvent (session_id, conversation_id), PipelineEvent,
UsageEvent (token usage), ModelFallbackEvent, PlanEvent,
ApprovalResolvedEvent, ToolResultEvent, plus the design / document /
pdf / pptx / image / audio events. Continue a stored conversation with
ChatStreamParams(conversation_id=...).
Conversations and artifacts
page = await nova.conversations.list(limit=20)
conv = await nova.conversations.get(page.conversations[0].id)
await nova.conversations.update(conv.id, title="Q3 planning")
for a in await nova.conversations.artifacts(conv.id):
latest = await nova.conversations.get_artifact(conv.id, a.artifact_id)
pdf = await nova.conversations.export_artifact(conv.id, a.artifact_id, "pdf")
open(f"{latest.title}.pdf", "wb").write(pdf)
await nova.conversations.delete(conv.id)
Also: summary(id), download_file(id, file_id),
add_artifact_version(id, artifact_id, content=... | restore_version=n),
get_settings() / update_settings(memory_mode_default).
Team
team = await nova.team.get() # None if you are not in a team
await nova.team.invite("kari@example.com", name="Kari", role="member")
await nova.team.remove("user_123")
Agent settings
s = await nova.agent.get_settings()
await nova.agent.update_settings(agent_mode=True, company_name="Acme")
Files
up = await nova.files.upload(path="deck.pptx") # works as the first call
Running code
nova.terminal was removed (the /v1/terminal API is gone). Ask Nova to
run code in chat instead; it runs in the chat's private EU code sandbox.
Usage & consumption
See exactly what your account is spending, split by account type (API vs Workspace) and by operation:
c = await nova.usage.consumption()
print(c.total_credits, "credits across", c.total_events, "requests")
for op in c.by_operation:
print(op.operation, op.product, op.credits)
# Per-request ledger
for ev in await nova.usage.events(limit=20):
print(ev.created_at, ev.operation, ev.credits)
Out of credits
At 0 credits a new request is refused (HTTP 402) and nothing runs; a request
that already started finishes. CreditsExhausted carries both links. A
credit pack works at once.
from novalab_adk import ChatMessageParams, CreditsExhausted
try:
await nova.chat.send(ChatMessageParams(message="..."))
except CreditsExhausted as e:
print(f"Out of credits: balance {e.balance}, needs {e.cost}")
print("Buy a credit pack:", e.topup_url, "or upgrade:", e.upgrade_url)
Errors
| Error | When | What to do |
|---|---|---|
NovaAuthError |
401 auth_error |
Check the key |
CreditsExhausted |
402 insufficient_credits (also a stream ending with quota_exceeded) |
topup_url or upgrade_url |
PlanRequired |
403 api_requires_paid_plan: the key belongs to a Free plan |
upgrade_url |
FeatureNotInPlan |
403 feature_not_in_plan |
required_plan, upgrade_url |
NovaPermissionError |
other 403, e.g. team role forbidden |
|
RateLimited |
429 (the SDK already waited Retry-After and retried short waits) |
wait retry_after seconds |
NovaAPIError |
anything else; .code and .body hold the server's error |
The 2.16 errors are subclasses of the 2.15 ones (CreditsExhausted of
NovaInsufficientCreditsError, PlanRequired and FeatureNotInPlan of
NovaPermissionError, RateLimited of NovaRateLimitError), so older
except blocks keep working.
Documentation
Guides and the API reference: https://app.novalab.build/docs. The OpenAPI 3.1 document: https://app.novalab.build/openapi.json
Metadata
Release files for novalab-adk 2.17.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| novalab_adk-2.17.0.tar.gz | 109.1 kB | Without provenance | Details for novalab_adk-2.17.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| novalab_adk-2.17.0-py3-none-any.whl | Python 3 | none | any | Details for novalab_adk-2.17.0-py3-none-any.whl |
Total release size: 245.1 kB
Release files / novalab_adk-2.17.0.tar.gz
| Download URL | novalab_adk-2.17.0.tar.gz |
|---|---|
| Size | 109.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
449f2f2a969d08b9ee44fee7634365965ac17d4fceba16012711e78bff76018d
|
|
BLAKE2b-256 checksum How to use checksums |
0d1ed81943214028aa01ab73d25827decb50505b593ae96eaec06b8659d28fe5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.17
|
Release files / novalab_adk-2.17.0-py3-none-any.whl
| Download URL | novalab_adk-2.17.0-py3-none-any.whl |
|---|---|
| Size | 136.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
521dda1bcb2d8f900d335ccfb58f8d2aca631d6834d8e8f1f22f894963abfd0b
|
|
BLAKE2b-256 checksum How to use checksums |
8681666049c946acf60e5acf831d74c4f072592cbe7942d522e082d107f3b4a8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.17
|
Security for novalab-adk 2.17.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.