Metadata-Version: 2.5
Name: novalab-adk
Version: 2.17.0
Summary: NovaLab Agent Development Kit — agents, chat streaming, conversations, artifacts, teams, multimodal and training on the Nova platform
License-Expression: MIT
Keywords: adk,agents,ai,multi-agent,novalab,orchestration,parallel,pipeline,routing,workflows
Requires-Python: >=3.10
Requires-Dist: boto3>=1.34.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# Nova ADK (Python)

The official Python SDK for the [Nova](https://novalab.build) agentic AI platform —
agents, chat, orchestration, voice, billing, and more, over a typed async client.

## Install

```bash
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:

```python
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.

```python
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

```python
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)

```python
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

```python
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.

```python
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

```python
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

```python
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

```python
s = await nova.agent.get_settings()
await nova.agent.update_settings(agent_mode=True, company_name="Acme")
```

## Files

```python
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:

```python
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.

```python
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
