nevo-sdk 0.1.0

Python SDK for Nevo — the inbound event gateway.

Nevo Python Library

The official Python library for Nevo.

Documentation

See the Python quickstart and the events reference.

Requirements

• Python 3.10+

Installation

pip install nevo-sdk

The import path stays nevo — only the distribution name carries the -sdk suffix:

from nevo import Nevo

Usage

The library needs to be configured with an API key from the Nevo dashboard.

import asyncio
from nevo import Nevo

client = Nevo(token="nvo_live_...")

@client.on_event()
async def handle(event):
    print(event.id, event.type, event.prompt_ready)

asyncio.run(client.run())

For scripts, there's a blocking convenience:

client.run_sync()

Events

Every event exposes the following fields:

Field	Type
id	str	stable across replays
type	str	webhook.received or email.received
origin	str	live or replay
created_at	datetime
channel	Channel	the channel that received this event
data	dict	the raw source payload
webhook	WebhookData | None	set when type == "webhook.received"
email	EmailData | None	set when type == "email.received"
prompt_ready	str	text rendering of the event

Branch on event.type:

@client.on_event()
async def handle(event):
    if event.type == "email.received":
        print(event.email.from_, event.email.subject)
    elif event.type == "webhook.received":
        print(event.webhook.method, event.webhook.path)

Configuration

client = Nevo(
    token="nvo_live_...",
    url="wss://api.nevo.sh/v1/stream",
    handler_timeout=30.0,
    reconnect_max_backoff=30.0,
    logger=None,
)

Option	Default	Description
token	—	API key from the Nevo dashboard
url	wss://api.nevo.sh/v1/stream	Override for self-hosted Nevo
handler_timeout	30.0	Seconds before a handler is considered stuck
reconnect_max_backoff	30.0	Cap on exponential reconnect delay
logger	logging.getLogger("nevo")	Your own logging.Logger

Handler behavior

Handlers must be declared with async def. Exactly one handler per client — branch on event.type inside it.

• If the handler returns, the event is considered handled.
• If the handler raises, the exception is logged and the stream continues.
• If the handler doesn't return before handler_timeout, it's logged as a timeout and the stream continues.

Events are not re-delivered to the SDK on handler failure. Replay them from the dashboard when you need to.

Reconnects

The client reconnects automatically using exponential backoff with jitter, capped at reconnect_max_backoff. If the server rejects the API key with a 401, the SDK raises AuthError and does not retry.

Logging

The SDK logs under the nevo logger. Enable debug output:

import logging
logging.getLogger("nevo").setLevel(logging.DEBUG)

Errors

All exceptions inherit from nevo.NevoError.

Exception	Raised when
AuthError	The API key is rejected by the server.
ConnectionError	The client cannot connect after exhausting retries.
NevoError	Base class.

from nevo import Nevo, AuthError

try:
    asyncio.run(client.run())
except AuthError:
    # Fix the key and restart.
    ...

Self-hosting

Point url at your instance:

Nevo(token="...", url="wss://events.internal/v1/stream")

Support

• Issues: github.com/nevo-dev/nevo/issues
• Email: [e-mail]

License

MIT