Skip to main content
Version: v1

Python Server Sync

monoverse-voicebot is a Python package that pushes your Python catalog and content to VoiceBot so the assistant can answer about your real products, categories and pages.

PyPI release in progress

The package is complete but not yet published to PyPI — until the release lands, install it from source. Everything on this page works the same either way.

It is a producer client for the VoiceBot canonical signed-ingest contract: it pairs once, sends a full snapshot to establish a baseline, then streams small incremental deltas as your data changes. Everything runs server-to-server over an HMAC-signed HTTP protocol — no browser, no end-user involvement, no LLM SDK on your side. Voice and retrieval stay on the VoiceBot backend. It is the Python twin of the @monoverse/voicebot-node and Laravel/WordPress sync producers.

Data channel — your Python app to VoiceBot ingest
┌──────────────────┐   gzip-NDJSON snapshot       ┌──────────────┐
│  Your Python app │   + signed /events deltas     │  VoiceBot    │
│  + this package  │ ───────────────────────────▶  │  ingest      │
│  (entity         │   HMAC-SHA256, https only      │  (catalog,   │
│   builders)      │                                │   RAG)       │
└──────────────────┘                                └──────────────┘
You need a catalog before the widget says anything

The widget answers questions using this data. Until a backend sync runs, there is nothing for it to talk about. Get the catalog in first.

The lifecycle at a glance​

Four steps from an empty connection to a self-maintaining feed:

  1. Pair — exchange a one-time VB-XXXX-XXXX code for your tenant id + an encrypted shared secret.
  2. Map — build canonical entities from your data with the typed builders (product, category, …).
  3. Snapshot — client.snapshot(...) streams a complete baseline of every kind you emit.
  4. Schedule — deltas every few minutes via client.send_events(...), plus a periodic full to reconcile deletes.

Two channels, two keys​

VoiceBot reads your store over two independent channels. They use different credentials and flow in opposite directions — don't confuse them.

Data channel (this package)Widget channel (browser)
DirectionYour server → VoiceBot (push)End-user browser ↔ VoiceBot (live)
CredentialHMAC shared secret (per-tenant, secret)Publishable key pk_… (public, embeddable)
Obtained viaclient.pair("VB-XXXX-XXXX")Copied from the cabinet, dropped in a <script>
CarriesCatalog + content snapshots and deltasVoice/text conversation traffic
TrustSecret, encrypted at rest, never loggedPublic identifier, safe to ship in markup

The shared secret minted by pairing is stored encrypted at rest (AES-256-GCM, keyed by your encryption_key) and is never printed, logged, or returned in any output.

When to use it​

Use this package when:

  • Your storefront runs on Python (Django, FastAPI, Flask, a headless backend, a custom shop).
  • You want the assistant to answer about live products, prices, stock, categories and pages.
  • You can run a script on a schedule (cron, Celery beat, a worker, a platform scheduler).

You do not need this package if your store runs on WordPress/WooCommerce (use the WordPress sync plugin) or Laravel (use the Laravel package), or if you'd rather not run a producer at all.

Prefer no code?

If you can't run a producer, VoiceBot can ingest your store with no code on your side — a managed crawler reads your public pages, and supported platforms can be pulled read-only. See No-code & read-only alternatives.

What it sends​

The package maps your data to VoiceBot's canonical entity schema via typed builder functions and emits the kinds you have — products, categories, pages and more. Money is integer minor units, categories/tags are slug lists, and page(content_text=...) is plain text; the builders enforce these. See Mapping for how to build entities and Syncing for how to push them.

Requirements​

  • Python 3.11+ (depends on httpx, pydantic, cryptography; ships py.typed).
  • A full-entropy 32-byte encryption_key to encrypt the stored shared secret (openssl rand -hex 32).
  • A reachable VoiceBot ingest endpoint over https (localhost is allowed for local dev).

The five-minute path​

  1. Install & pair — install the package, construct the client, exchange a pair code.
  2. Map your data to canonical entities.
  3. Push a baseline: client.snapshot(catalog()).
  4. Sync deltas + a periodic full.
  5. Operate it — status, unpair, retries, scheduling.

Next steps​