Metadata-Version: 2.5
Name: novalab-adk
Version: 2.15.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

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

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

## 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:

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

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

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