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
import asyncio
from novalab_adk import NovaClient
from novalab_adk.types.chat import ChatMessageParams
async def main():
async with NovaClient(api_key="nova_...") as nova:
reply = await nova.chat.send(ChatMessageParams(message="Summarise the latest sales report"))
print(reply.response)
asyncio.run(main())
model defaults to "auto" (Nova picks the right model per task). You can
pin a Nova tier instead: nova-max, nova-flagship, nova-reasoning or
nova-fast (see novalab_adk.NovaModel).
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)
Handling out-of-credits
Billable calls raise NovaInsufficientCreditsError (HTTP 402) with the
details needed to prompt an upgrade or top-up. nova.chat.stream() raises
the same error when the stream ends with quota_exceeded:
from novalab_adk import NovaInsufficientCreditsError
try:
await nova.chat.send("...")
except NovaInsufficientCreditsError as e:
print(f"Out of credits for {e.operation}: balance {e.balance}, cost {e.cost}")
print("Upgrade:", e.upgrade_url)
Errors
| Error | When |
|---|---|
NovaAuthError |
401, bad or missing key |
NovaInsufficientCreditsError |
402, or a stream ending with quota_exceeded |
NovaPermissionError |
403, e.g. admin_required, team role forbidden |
NovaRateLimitError |
429 |
NovaAPIError |
any other error; .code holds the server's code |
Documentation
Full docs: https://novalab.build/docs
Metadata
Release files for novalab-adk 2.15.1
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.15.1.tar.gz | 91.4 kB | Without provenance | Details for novalab_adk-2.15.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| novalab_adk-2.15.1-py3-none-any.whl | Python 3 | none | any | Details for novalab_adk-2.15.1-py3-none-any.whl |
Total release size: 216.1 kB
Release files / novalab_adk-2.15.1.tar.gz
| Download URL | novalab_adk-2.15.1.tar.gz |
|---|---|
| Size | 91.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b6d8ae87e9d13c0bcb8ff3984e4e035efcfae39cbfba3b60de7eede4ef2f4608
|
|
BLAKE2b-256 checksum How to use checksums |
39fbce8b049b47216c9bbf465c8e3735faea017acc036f1f9578f9b7af73581d
|
| 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.15.1-py3-none-any.whl
| Download URL | novalab_adk-2.15.1-py3-none-any.whl |
|---|---|
| Size | 124.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a5b22ab7cfc2d7507174baa73182681f9c2e043e0b9056cdfc3e3fb45ccd7d26
|
|
BLAKE2b-256 checksum How to use checksums |
ebc923c169a81d7f113ac737d4058594ed99b502d3d7f1dab4a4c5e4a470a87c
|
| 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.15.1
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.