Start here

Getting started

From nothing to a first answer from a customer's twin.

Install

pip install eggai

Python 3.9+ or Node 18+. Both packages have zero dependencies — they are thin clients, and all inference runs on EGGai's servers, so there is nothing to download and no GPU required on your side. TypeScript types ship inside the npm package.

Authenticate

Every client takes a workspace API key. Keys are issued in the EGGai app under Settings → API keys, and are scoped to your workspace — the workspace is also where your uploaded customer data lives. Pass the key directly, or set it once in your environment:

export EGGAI_API_KEY="egg_..."
from eggai import EggAI

client = EggAI()                    # reads EGGAI_API_KEY
client = EggAI(api_key)             # or pass it directly
Practice keys. Alongside your live key you get a practice key. It authenticates everywhere a live key does, but jobs are capped to a small number of rows — so you can wire up your integration, run it end to end, and only switch to the live key when the lists are real.

First call: score one customer

The fastest way to see the model work is score — a synchronous helper that returns bare acceptance probabilities for up to 64 (profile, offer) rows in one batched judge call:

ps = client.score([
    {"id": "c_8813",
     "profile": "shops fortnightly, small baskets, coupon-led",
     "offer":   "15% off produce, min spend 500"},
])
ps   # [0.22] — this customer, this offer, probably not

Second call: the cheapest accepted offer

Now let the proposer negotiate with that same twin — the core of the Offer Optimization SDK:

from eggai import OfferOptimizer

optimizer = OfferOptimizer(api_key)
terms = optimizer.cheapest_accepted(
    customer   = "c_8813",
    profile    = "shops fortnightly, small baskets, coupon-led",
    offer      = "Fresh Picks Weekend — 15% off produce, min spend 500",
    guidelines = """
        discount caps at 12%, min spend above 300.
        the produce section is fixed. the tagline may
        be reworded, but never promise free delivery.
    """,
)

terms.text       # "8% off produce, min spend 349"
terms.tagline    # "Weekend Picks"
terms.changed    # ["discount", "min_spend", "tagline"]
terms.objection  # "threshold above my usual basket"

Behind that one call the SDK created a job, waited for it, and read the result back. Batch the same call over thousands of rows — or take the job handle and stream it — with exactly the same method: see Jobs & streaming.

What each SDK needs

SDKYou provideComes back
Offer Optimization One row per customer: id, profile, the offer on the table The cheapest accepted terms per customer — or none worth making
Lead Generation One row per contact: id, profile; one offer for the run The list ranked, a reason per name, an explicit not-worth-calling line
Survey Response preview Questions; a panel description, or your own respondents A distribution per question, with the reasoning attached
Assortment Optimization A panel of category customers and the shelf change One outcome per customer, spend-weighted retention, the walkers named

A profile is a short free-text description of how this customer shops. Workspaces with onboarded transaction history can pass richer profiles generated from real trips; the profiles guide covers what makes profiles work.

Next steps