Skip to main content

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)

Source distribution for novalab-adk 2.15.1
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)

Table of built distributions (wheels) for novalab-adk 2.15.1
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page