Docs — Polanyi Python SDK, API, and Recsys Event Schema

Quickstart

Create an account and verify your email. New accounts get $10 in free credits.
Create an API key in the dashboard. Keys start with pk_live_ and are shown once.
Install the SDK and run a simulation:

pip install "polanyi>=0.4.2"

import os
os.environ["POLANYI_API_KEY"] = "pk_live_..."

from polanyi import Client

result = Client().simulate(site="https://your-store.com", n=3)

import pandas as pd
events = pd.read_json(result.events_jsonl, lines=True)
personas = pd.read_json(result.personas_json)

While it runs you see live progress for each shopper. If a Colab runtime resets, fetch a finished run again with Client().fetch("sim_...").

Client.simulate parameters

Parameter	Type	Description
site	str	Website URL or hostname to simulate, e.g. https://your-store.com. Shoppers never leave this domain.
n	int	Number of synthetic shoppers (journeys) to run. Default 1, up to 50 per run.
concurrency	int \| None	Shoppers run in parallel. Defaults to min(n, 5).
prompt	str \| None	Optional extra instruction for the shoppers.
seed	int \| None	Seed for reproducible persona casting.
output_dir	str \| Path \| None	Where to write files. Default output/<site>_<timestamp>/.
progress	bool	Show live progress while the run executes. Default True.
download	bool \| None	In Colab, download a zip of the results when done.

Output files

File	Contents
personas.json	Every simulated shopper: demographics, interests, personality, and the journey goal each was given.
recsys_events.jsonl	All recommendation events from all shoppers, one JSON object per line. Also exported as Parquet.
summary.json	Run summary: shoppers, sessions, event counts, and status.

Event schema

Every line of recsys_events.jsonl follows the browser_use_recsys_event schema (v1.0.0).

Field	Type	Description
event_id	string	Unique event ID.
session_id	string	Shopping session the event belongs to.
actor_id	string \| null	Synthetic shopper ID (prefixed syn_). Never joined to real customer IDs.
persona_id	string \| null	Persona from personas.json that drove this shopper.
is_synthetic	boolean	Always true for Polanyi events.
recorded_date	date	Date the run was recorded.
event_time	datetime \| null	When the event happened within the session.
sequence_index	integer	Position of the event in its session. Use for sequential models.
event_type	string	What happened. See event types below.
feedback_class	enum	implicit, explicit, context, derived, or transaction_boundary.
signal_strength	enum	none, weak, medium, strong, very_strong, or ambiguous.
observed	boolean	true if seen directly in the browser; false for inferred signals.
training_use	enum	offline_sandbox_only (default), production_eligible, or do_not_use.
item_id	string \| null	Product or item the event refers to, as identified on your site.
item_type	string \| null	Kind of item, e.g. product.
payload	object	Event-specific details, such as the search query or the filter applied.

Event types and default signal strength

Signal strength says how much an event should count as preference. Use it to set implicit-feedback weights in your training pipeline.

event_type	feedback_class	default signal_strength
session_started	context	none
search_submitted	implicit	medium
filter_applied	implicit	medium
item_impression	implicit	weak
item_viewed	implicit	weak
item_clicked	implicit	medium
dwell	implicit	weak
scroll	implicit	weak
cart_add	implicit	strong
cart_remove	implicit	ambiguous
item_selected	implicit	very_strong
save	explicit	strong
share	explicit	strong
rating	explicit	very_strong
review	explicit	very_strong
checkout_started	implicit	very_strong
checkout_boundary_stop	transaction_boundary	none
inference_signal	derived	ambiguous
session_summary	context	none

REST API

The Python SDK wraps two endpoints. Authenticate with your key as a bearer token.

Method & path	Purpose
POST /v1/simulations	Start a run. Body: { "site": "https://…", "n": 3 }. Returns 202 and a sim_… id.
GET /v1/simulations/{id}	Status, progress, and events for a run. Visible only to the key's owner.

How shoppers behave

Shoppers are cast from NVIDIA Nemotron-Personas-USA. Each gets a different goal.
Polanyi first diagnoses the live site, then runs each shopper in a real cloud browser.
Shoppers are hard-pinned to your domain and stop before entering identity or payment details.
External checkout hand-offs are recorded as checkout_boundary_stop.

Billing

Runs are billed per shopper journey from prepaid credits. Failed journeys are refunded automatically. Your balance and past runs are in the dashboard. For volume or enterprise pricing, talk to the founders.