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

  1. 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.
  2. Create a key in Nova under Settings, Developer, and set it as NOVA_API_KEY.
  3. 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)

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

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

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