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

Terminal (admin only)

nova.terminal.* runs commands on Nova's servers and is limited to Nova admin accounts. Other keys get NovaPermissionError with code == "admin_required".

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.0

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.0
File Size Uploaded Provenance Actions
novalab_adk-2.15.0.tar.gz 92.9 kB Without provenance Details for novalab_adk-2.15.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for novalab-adk 2.15.0
File Interpreter ABI Platform Actions
novalab_adk-2.15.0-py3-none-any.whl Python 3 none any Details for novalab_adk-2.15.0-py3-none-any.whl

Total release size: 219.8 kB

Release files / novalab_adk-2.15.0.tar.gz

Download URL novalab_adk-2.15.0.tar.gz
Size 92.9 kB
Tags Source
SHA-256 checksum
How to use checksums
549e324146f9fd198f79fbfc72a6e71dc031b5e5327da2c0521878fb0e7294fd
BLAKE2b-256 checksum
How to use checksums
24eaebc624296500dd7d414a589649b9710c7dd7b36b0cd50729371e8f2d2f30
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.3

Release files / novalab_adk-2.15.0-py3-none-any.whl

Download URL novalab_adk-2.15.0-py3-none-any.whl
Size 126.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5bf727e84fbe06e4424f107b2f7efdabde2a1b460c36f6fe12d6ce030d702f41
BLAKE2b-256 checksum
How to use checksums
26195e0c6e02884f5516ce4ba6adef95ce6578268ed23c84d3b748a0c8f608b3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.3

Security for novalab-adk 2.15.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.

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