Concepts
Five ideas explain everything the SDKs do: the twin, the proposer, guidelines, jobs, and keys.
The twin — the judge
EGGai‑v1 is a Large Behavior Model trained on real shopping behaviour: the till history of a major SEA grocery retailer. Given a customer's profile, it answers as that customer — first-person, from their own habits — and returns a decision, how sure it is, and the sentence they would say.
The twin never sees what the caller was trying to achieve. It is the half of the system that can be checked: its predictions are scored against held-out real outcomes, and the published studies on the research pages report exactly how it does — including where a purpose-built system beats it.
Every SDK is a different way of pointing this one model at a decision. None of them fine-tune it, prompt it with your goal, or let another model overrule it.
Offerwright — the proposer
Two of the four SDKs also use a second model, Offerwright, which writes offers. It drafts terms and words together, opens at the stingiest version your guidelines allow, and each round moves only the lever the twin objected to.
The two models take turns and neither sees the other's reasoning — that separation is what stops a search from marking its own homework. The proposer never gets the last word: an offer only survives if the twin accepts it.
| SDK | Proposer | Judge |
|---|---|---|
| Offer Optimization | Offerwright, up to a bounded number of rounds | The twin, every round |
| Lead Generation | Offerwright, only when tailoring is on | The twin, once per contact |
| Survey Response | None — a questionnaire is not an offer | One twin per respondent |
| Assortment Optimization | None — the range decision is yours | The twin, once per customer |
Guidelines and constraints
You steer the proposer two ways, and they are deliberately different:
- Guidelines are free text — "discount caps at 12%, the produce section is fixed, never promise free delivery". The proposer reads and honours them; they can express intent no schema can ("the tagline may be reworded").
- Constraints are numeric backstops enforced by the harness itself:
max_depth,min_depth,min_spend_min,min_spend_max. Whatever the language models do, terms outside these bounds never reach a customer.
Use guidelines for intent, constraints for the numbers you would be fired for breaching. The profiles & guidelines guide has patterns that work.
Jobs
Every batch call is a job: created with one POST, run on EGGai's engines,
finished as done, stopped or failed. The SDKs hide this by
default — rank(...) creates the job, waits, and returns the result — but the handle is
one argument away (wait=False / wait: false), and with it you can stream
live events, poll progress, stop the job, or page the raw rows.
Jobs are sized and admission-controlled per workspace: row caps per job, a cap on concurrently
open jobs, and a rate limit on job creation. Every refusal is a structured error carrying the
server's own message. Pass an idempotency_key when you retry creates — the same key
returns the same job instead of starting a second one. Details in
Jobs & streaming.
Two calls are not jobs, by design: score (≤64 rows, bare probabilities,
one synchronous judge call) and assortment.preview (≤64 rows, a sampled what-if,
nothing persisted). They exist for try-it loops and conversational tools, not campaigns.
Workspaces and keys
Your workspace is where your data, jobs, metering and keys live. API keys are
issued in the EGGai app (Settings → API keys) and sent as
Authorization: Bearer <key> — one key is all the SDKs need.
- Live keys run real volume and are metered.
- Practice keys authenticate identically but cap rows per job, so integration work never spends real volume by accident.
usage() returns the same metering rollup the app's billing screen reads — billable
units per product, job by job.
What the model will not do
- Invent a customer. Every answer is grounded in the profile you pass. Thin profiles get honest, low-confidence answers, not confident fiction.
- Agree with itself. The survey panel's training reward was distribution-matching — a panel that agrees with itself more than real people do is the failure it was built to avoid.
- Improve the scenario it is marked on. In assortment runs the prices hold and nothing is on promotion; the shelf change you specify is the only thing that changes.