novence (Python)

Python SDK for Novence — static site hosting built for AI agents.

Prefer the CLI for a first publish — no email until you claim:

npx novence deploy ./dist
novence claim --email you@example.com

This SDK is for app and script code after you have an nv_ key.

pip install novence

Requires Python 3.10+. No third-party dependencies — standard library only.

Quick start

import os
from novence import Novence

client = Novence(api_key=os.environ["NOVENCE_API_KEY"])
project = client.create_project("launch")
pid = project["project"]["id"]

client.upload_bytes(pid, "index.html", "text/html; charset=utf-8", b"<h1>hi</h1>")
client.deploy(pid)

deployment = client.wait_for_deployment(pid)     # polls until live or failed
print(deployment["liveUrl"])

One HTML document: client.publish_html(html, title="Report") then wait_for_deployment. CLI: npx novence deploy report.html.

Bootstrap + verify (email path)

When you need a key from email OTP instead of the CLI:

from novence import Novence, bootstrap_account, verify_email

boot = bootstrap_account("you@example.com")     # emails a 6-digit OTP
verify_email("you@example.com", "123456")

client = Novence(api_key=boot["apiKey"])
project = client.create_project("launch")
pid = project["project"]["id"]

client.upload_bytes(pid, "index.html", "text/html; charset=utf-8", b"<h1>hi</h1>")
client.deploy(pid)

deployment = client.wait_for_deployment(pid)     # polls until live or failed
print(deployment["liveUrl"])

Or deploy anonymously from the SDK, then claim: create_demo_account() → ship → claim_account(api_key, "you@example.com").

Configuration

base_url defaults to https://api.novence.ai. Override per client, or set NOVENCE_BASE_URL to point everything at a different control plane:

client = Novence(api_key=key, base_url="http://127.0.0.1:8080")

The variable is read at call time, so setting it after import still works.

Deploys are asynchronous

deploy() returns as soon as the deployment is queued. Use wait_for_deployment(project_id, timeout=300, interval=2) to block until it is live, or poll latest_deployment(project_id) yourself.

checks_results["passed"] is None when checks were skipped (unverified accounts). That is not a pass.

API

Module-level: create_demo_account claim_account bootstrap_account verify_email resend_verification reissue_api_key.

reissue_api_key issues a new key and revokes the old one — rebuild your client with the returned key.

Uploading a directory

result = client.upload_dir(pid, "./dist")
result["uploaded"]   # site paths that went up
result["skipped"]    # local files whose extension the platform does not accept

Dotfiles and dot-directories (.git, .env) are skipped, matching the TypeScript SDK.

Errors

Every API error raises RuntimeError carrying the API's message — including rate limits and quota rejections.

Security

nv_ keys are server-side credentials. Read them from the environment; never commit one or put one in client-side code.

License

MIT