This is sample code, not a production-ready solution. You deploy it into your own AWS account and you are responsible for the AWS charges it incurs and for the security review it needs before production use. See Cost, Security considerations and Known limits.
Adlytics AI is retail-media analytics for brands that sell to Amazon as a first-party (1P) vendor. It runs in your own AWS account, reads your Amazon Marketing Cloud (AMC) advertising data, and lets your team explore it through answer-first pages and a chat assistant. Every figure comes from tested code over your published data; the assistant explains and compares those figures, or says plainly when a question can't be answered. Vendor Central retail data can't be loaded into a customer deployment yet (Known limits).
Each solution is one view of the product, with its own README: who it's for, what it shows, the data it uses and how to adapt it. All of them deploy together with one command (Quickstart).
| Solution | What it gives you | For |
|---|---|---|
| Performance: Growth check and Scorecard | Whether your advertising is growing the business, and which ad channel earns its budget | Brand or category manager; finance or CMO |
| Campaigns | The campaigns to scale, hold or cut, with the reasons behind each change | Media buyer |
| Reach and audiences | Whether Amazon DSP reaches shoppers your sponsored ads miss, where more ads stop paying, and which audiences your buyers belong to | Media buyer |
| New customers and retention | Which ad channels win first-time buyers, at what cost, and whether those customers come back | Brand or category manager; finance or CMO |
| Retail health | Whether your products sell, where sales leak, and which products your ads lean on. A customer deployment can't load its Vendor Central data yet | Brand or category manager |
| Demand forecast | How much each product will sell over the next 13 weeks, in units, shipped revenue and cost of goods, with a range, on a page and in chat. A customer deployment can't load the Vendor Central history it needs yet | Brand or category manager; vendor or supply planner; finance |
| Governed analytics assistant | Answers to "why did it move?" in which every number comes from tested code, with an audit record per turn, optional sampled evaluation (off by default and accepted in any environment; live-accepted in dev only), quality review and versioned insight prompts | Everyone on the team; analysts; administrators |
| Platform | The foundation the others run on: data landing, a governed data lake, the metric layer, page refresh, a signed-in website and make deploy-all |
The builder who deploys it; an engineer reusing one block |
Amazon gives a 1P vendor two reporting systems that disagree by design:
- Amazon Marketing Cloud holds advertising data: who saw an ad, what it cost, and which sales Amazon attributes to it. You query it with SQL in a privacy-protected environment that drops rows describing too few shoppers.
- Vendor Central holds retail facts: what shipped, what Amazon paid, what came back. It has no advertising dimension, a different day boundary and a different revision schedule.
"Is my advertising actually growing the business?" needs both. Today that usually means exporting reports from two consoles and reconciling them in spreadsheets, where it is easy to get silently wrong: spend that arrives in units 1,000 times apart, suppressed rows that make totals stop adding up, distinct-shopper counts summed across days. This sample does that reconciliation once, in declared and tested mappings, so a brand manager can ask the question in a sentence and get an answer they can defend. The full problem statement is in business context.
Who it is for: brand managers at 1P vendors, and the analytics leads and agencies who work with them. Who deploys it: a builder on that team with an AWS account.
What a deployment can answer depends on the Amazon access you bring:
| Your Amazon access | Questions it adds | Examples |
|---|---|---|
| Vendor Central reports | Retail performance (can't be loaded into a customer deployment yet; see Known limits) | What did I sell, what came back, how did glance views convert? |
| An AMC instance mapped to your advertising accounts | Advertising measurement and new customers | What was my return on ad spend (ROAS) by campaign, across display and sponsored ads? How many distinct shoppers saw my ads, and how often? How much of my business is new-to-brand? |
| An AMC Paid Features subscription | Audience profiles and every repeat purchase | Which Amazon audience segments do my buyers belong to? Do new customers buy again by any route, not only after an ad? |
It refuses, and explains why, when the data can't support an honest answer. Some questions can never be answered from these two sources: retail sales attributed to a specific campaign (Vendor Central has no campaign dimension), anything about an individual shopper, competitor activity, or a single merged revenue figure. The complete list, with the wording the assistant uses, is in answerable questions.
Call-flow diagram — from your data delivery to an answer in the browser.
Takeaway. The model chooses which tool to call and writes the explanation; every figure comes from a tool that computed it from your published data.
- Your own pipeline runs the declared AMC SQL and lands each result in this deployment's S3 landing bucket. Vendor Central reports can't be landed yet; see Known limits. Extraction stays outside the sample, so it never holds your Amazon credentials.
- Ingestion validates each delivery against its data contract and publishes it as an immutable version. A delivery that fails validation is refused rather than partly loaded.
- In chat, the Conversation API verifies the user, screens the question with Amazon Bedrock Guardrails, and invokes an agent hosted on Amazon Bedrock AgentCore. The user's identity travels with every call, and each tool verifies it.
- The agent calls measurement and catalog tools through AgentCore Gateway. The tools compute figures with Athena and return them with any caveats (coverage, suppression, measurement basis), or a reason the question can't be answered. The answer streams to the browser, and an audit record of the tools used is written for every turn.
Call-flow diagram — how a page refreshes after new data is published.
Takeaway. A page never shows a half-built result: each page moves to new data once it builds, or stays on its last good version, and a page that keeps failing raises an alarm.
Pages are computed when data is published, so they load fast and every viewer sees the same figures. A page whose data can't be shown yet says what is missing and when to expect it. The bake pipeline is described in preset artifact publisher.
Key terms used across the docs:
| Term | Meaning |
|---|---|
| Governed figure | A number computed by a declared, tested tool from published data, never by the model. |
Publication / CURRENT |
An immutable, validated version of a dataset / the pointer to the version being served. |
| Data contract | The declared shape and meaning of one source report, in contracts/. |
| Designed absence | The message a page shows, instead of a blank or a guess, when its data can't be shown yet. |
| Calibration | An automated test run a prompt or guardrail must pass before it is activated. |
Architecture in depth: the Platform README, block by block; the architecture overview, conversational runtime, and the documentation index. Design decisions are recorded as ADRs in docs/decisions/.
Each page answers one question and leads to one decision. It opens with one answer sentence filled from the figures shown below it. Who each view is for lists every view with its reader, question and decision. Each solution's README shows its pages in screenshots from a development deployment with synthetic data.
- Performance. The Growth check at
/puts ad cost, return and shipped retail sales on one screen. The Scorecard ranks channels with each sale counted once, and shows whether the ranking depends on the attribution model. - Campaigns. Every campaign in one window, ranked by the column you choose. Under All channels it shows only what can be totalled, spend and impressions. Each tile opens to the campaigns that drove the change and the readings that would explain it, and each insight card opens to its full text.
- Reach and audiences. How many distinct shoppers Amazon DSP reaches that sponsored ads don't, how the purchase rate changes with the number of ads seen (association, not cause), and which audience segments are more common among buyers than among shoppers reached. Only the Amazon audience segments profile needs an AMC Paid Features subscription; the DSP-exposed buyers profile and DSP campaigns by segment work without it.
- New customers and retention. New-to-brand purchases and their cost per channel, and the share of customers each channel won who bought again, by quarter.
- Retail health. Vendor Central sales, fulfilment, conversion and returns, reconciled to Vendor Central's own totals, with a page per product, and each product's sales beside one channel's ad credit. It stays empty in a customer deployment until Vendor Central reports can be loaded (Known limits).
- Demand forecast. A 13-week forecast per product of ordered and shipped units, shipped revenue and cost of goods, with a p10 to p90 range, shown only where it beats simpler methods. The Retail hub's Demand forecast tab ranks every product by forecast demand, finds one by its ASIN and opens its weekly range and tested accuracy; four chat tools read the same stored figures. It stays empty in a customer deployment until Vendor Central reports can be loaded (Known limits).
- Governed analytics assistant. Chat beside every page, told which page and window you're on. "How this was answered" lists the governed tools behind each figure. How it stays trustworthy covers the audit record, sampled online evaluation, quality review and prompt administration.
| Requirement | Detail |
|---|---|
| AWS account and Region | One account you control that runs no other workloads; deployment into a shared account is unsupported (O-RESULT-SHARED-ACCOUNT-001). The sample synthesizes only in us-east-1, us-east-2, us-west-2, eu-central-1 and eu-west-1, the Regions it declares a guardrail profile for (route-guardrail.ts). It has been deployed and accepted only in us-east-1. |
| AWS credentials | A named, non-default AWS CLI profile with administrator-level permissions in that account and a Region set. The deployment creates IAM roles and policies. |
| Amazon Bedrock model access | Enable access in your Region to the three models .env.example names, a quick chat model, a deep-dive chat model and a memory model, including the one-time use-case form Anthropic models need (Request access to models, read 2026-10-19). They are US cross-Region inference profiles; in eu-central-1 or eu-west-1, replace each with the ID that aws bedrock list-inference-profiles --profile <your-profile> --region <region> --type-equals SYSTEM_DEFINED lists. The memory model has no fallback (ADR-147). Checked by make deploy-all. |
| Athena concurrent queries | Page refreshes and chat share Athena's "Active DML queries" quota (query path). Read the applied value in your Region with aws service-quotas get-service-quota --service-code athena --quota-code L-FC5F6546 --profile <your-profile> (Athena quotas, read 2026-10-25), and request an increase in Service Quotas if it is below batch_athena_budget + chat_reserve_active_dml in contracts/operations/execution-graphs.yaml (62 at this release). Checked by make deploy-all. |
| Lambda concurrency | One environment reserves 36 concurrent executions for its functions once producer onboarding is on (34 before), and Lambda always keeps 100 of the account's concurrency unreserved. The applied "Concurrent executions" quota in your Region must therefore be at least 136. Read it with aws lambda get-account-settings --profile <your-profile> (AccountLimit.ConcurrentExecutions) and request an increase in Service Quotas if it is below 136; otherwise the first stack that reserves concurrency fails to deploy. Checked by make deploy-all. |
| SageMaker Processing quota | The demand-forecast job runs on SageMaker Processing. The applied "ml.m5.xlarge for processing job usage" quota must be at least ADLYTICS_DEMAND_FORECAST_MAX_PARALLEL_JOBS (8); the documented default is 0 (SageMaker quotas, read 2026-11-11). Read it with aws service-quotas list-service-quotas --service-code sagemaker --profile <your-profile> --query "Quotas[?QuotaName=='ml.m5.xlarge for processing job usage'].Value" and request an increase if it is lower; a lower quota fails a forecast run rather than slowing it. Checked by make deploy-all. |
| Edge rate limit | The website's AWS WAF rule limits requests per source IP per five minutes (ADLYTICS_EDGE_WAF_RATE_LIMIT_PER_FIVE_MINUTES in .env.example, with a separate limit for sign-in). A team behind one corporate IP shares that one budget, and each page view makes several requests. Size it for your team's combined traffic before you invite users. |
| Local tools | Node.js 24 (.nvmrc), Python 3.14 through uv, AWS CLI v2, make, bash, the file utility, and Docker or Finch to build the demand-forecast job image (for Finch, set CDK_DOCKER=finch). Developed and deployed from macOS. |
| Amazon data (needed to see figures) | A deployment shows only designed empty pages until your own pipeline, run from a second AWS account, lands AMC query-pack results (Load your data). Vendor Central reports can't be landed yet (Known limits). |
Complete the Prerequisites first. Before any diff or deploy, make deploy-all reads the Lambda concurrency, Athena active DML and declared Service Quotas values and the Bedrock model access the synthesized app needs, and stops with the fix printed when one falls short (deploy_preflight.py).
cp .env.example .env # fill in the blanks; each value is explained in the file
make deploy-all PROFILE=<your-profile> ENV=<env> # shows the account, Region and changes; deploys nothing
make deploy-all PROFILE=<your-profile> ENV=<env> APPROVE=1 EMAIL=<you@example.com>The command prints the website URL, and the invited user receives a temporary password by email. When you are done:
make destroy-all PROFILE=<your-profile> ENV=<env> CONFIRM=<env>destroy-all keeps resources that hold data, which keep billing until you delete them; see Clean up.
- Configure. Copy
.env.exampleto.envand fill in the blanks. Every value is explained in the file. The Chronos-2 artifact and its digest are not among them: synth reads your Region's reviewed pin fromcontracts/forecasting/model-artifacts.json. - Deploy everything. Run
make deploy-allwithoutAPPROVEfirst: it deploys nothing and shows the target account, Region and the changes. Then run it withAPPROVE=1 EMAIL=<address>to deploy and invite the first user. What the target decides for you, such as CDK bootstrapping and the frontend's second pass on a first deployment, is listed in the header ofscripts/deploy-all.sh. If a step fails, fix the cause and run the same command again: stacks with no changes are skipped, and a user who is already invited is not sent a second invite. If CloudFormation then reports that a name already exists, a failed first create left a retained resource behind: delete it (see Clean up) or use a newENV. - Sign in. Open the printed URL and set a new password at first sign-in. To invite more users:
make create-user PROFILE=<your-profile> ENV=<env> EMAIL=<address>.
An update of an existing development environment with no stack changes took about 11 minutes end to end (2026-10-01). A first deployment of a new environment took about 42 minutes end to end (2026-10-19), in an account already CDK-bootstrapped and with model access enabled; it has not yet been run in a new account (record).
Updating an existing environment. Run the same two commands. make deploy-all doesn't stop for a one-time step between stacks; each is stated in the comment beside its stack in DEPLOY_ORDER (infra/lib/config/index.ts), so read those comments before you update.
An update from a version without staged table writes (ADR-149) or without the sharded sibling index (ADR-145) takes these steps, in this order; no target enforces them:
- Stop landing deliveries.
- Wait until
adlytics-<env>-ingestionandadlytics-<env>-semantic-write.fifoboth report 0 visible, in-flight and delayed messages. If you deploy sooner, a GRAPH write set still in flight collides on its next receive.for q in adlytics-<env>-ingestion adlytics-<env>-semantic-write.fifo; do aws sqs get-queue-attributes --profile <your-profile> --attribute-names ApproximateNumberOfMessages ApproximateNumberOfMessagesNotVisible ApproximateNumberOfMessagesDelayed \ --queue-url "$(aws sqs get-queue-url --profile <your-profile> --queue-name "$q" --query QueueUrl --output text)" done
- Deploy with the two commands above.
- Resume deliveries straight away. Until each page's next bake, Campaigns and Retail health show their failed state and raise an alarm, and Audiences shows "isn't ready to show yet" (ABS-AUD-1). No command starts that bake: it runs when a delivery for that page lands (publisher).
- After that first bake, check Campaigns, Retail health and Audiences.
To deploy one stack on its own, run make deploy STACK=Adlytics-<Area>-<env> PROFILE=<your-profile> ENV=<env> APPROVE=1; it deploys exactly that stack. It takes no deploy lock, and it isn't for a src/ change on a shared environment: every function-bearing stack shares one Lambda source asset, so deploy that change to every stack with make deploy-all-locked (ADR-136).
-
You can sign in with the invited user.
-
The pages load and show their designed empty states. A new deployment has no data: its pages stay empty until you set up your data producers and their first deliveries land in the data lake. Load your data says how.
-
The chat assistant answers a question such as "What metrics can I ask about?".
-
Subscribe to the alarm topic. Every alarm notifies one SNS topic, which the deployment creates with no subscriber, so no alarm reaches anyone until you add one:
aws sns subscribe --profile <your-profile> --protocol email --notification-endpoint <you@example.com> \ --topic-arn "$(aws ssm get-parameter --profile <your-profile> --name /adlytics/<env>/ingestion/alarm-topic-arn --query Parameter.Value --output text)"
Confirm the subscription from the email AWS sends.
-
After a deployment, up to three tamper-detection alarms (
adlytics-<env>-record-*) can go to ALARM and return to OK on their own within about 15 minutes. They fire on a first deployment and on any deployment that changes a record table's policy or the functions it names.
All are off by default and are set in .env.
| Feature | Setting | Read first |
|---|---|---|
| Producer onboarding: a cross-account role your extraction pipeline assumes to land data | ADLYTICS_PRODUCER_ONBOARDING_ENABLED with the role ARN and external ID |
Source acquisition |
| Searchable traces (CloudWatch Transaction Search). An account-wide setting with its own charges. The agent runtime's span diagnostics need it | ADLYTICS_TRANSACTION_SEARCH |
Observability |
| Online answer evaluation: scores a sample of complete answers, 10% by default; answers outside the sample are not checked | ADLYTICS_EVALUATION_INPUT_PROVISIONED adds the evaluation outbox, which keeps each complete turn's exact question and released answer; synth accepts it in any environment. Scoring, ADLYTICS_ONLINE_EVALUATION_PROVISIONED and related settings, needs the outbox; synth accepts it in any environment. Accepted in dev only: live acceptance has run only there |
Agent quality loop |
Operational status plane (preview): the Data pipeline status page, and set-at-once page refresh and operator holds once the operator cuts it over to GRAPH mode |
ADLYTICS_OPERATIONAL_STATUS_PROVISIONED; synth accepts it in any environment. It deploys in LEGACY mode, so pages still refresh one at a time until the one-way cutover. Accepted in dev only: live acceptance and the cutover have run only there, and its probes run only against dev |
Preset artifact publisher, Operational data-flow status |
A new deployment starts with an empty data lake, so every page shows its designed empty state until data lands. The sample does not connect to Amazon itself: data arrives only from producers you set up, and only through producer onboarding, which is off by default.
To turn it on, set ADLYTICS_PRODUCER_ONBOARDING_ENABLED=true in .env with ADLYTICS_LANDING_PIPELINE_ROLE_ARN, one IAM role in a different AWS account from this deployment that your extraction pipeline runs as (synth refuses a role in the same account), and an ADLYTICS_LANDING_EXTERNAL_ID you choose. Then run make deploy-all again. The Adlytics-Ingestion-<env> stack outputs OutLandingRoleArn, the role your pipeline assumes with that external ID, and OutLandingBucketName and OutLandingIncomingPrefix, where it lands. For each AMC query pack in contracts/amc/query-packs/, your pipeline runs the exact SQL against your AMC instance, writes the result, then writes the registration object last. The producer CLI describes a pack, validates a result and renders the landing keys and registration for you. This registration handshake, described in source acquisition, is for the AMC query packs only: the reports the contracts/vendor-central/ contracts declare can't be landed through it yet; see Known limits. For example deliveries of every contract, see the synthetic fixture generator in development seeding.
Call-flow diagram — how a change moves from a declared contract to a deployed environment.
Takeaway. You change what the product means in one declared place; generators and gates keep the code and docs in step with it.
| To add | Edit | Then run |
|---|---|---|
| A metric | contracts/shared/metric-dictionary.yaml |
make check-lineage |
| An AMC query or Vendor Central report | contracts/amc/, contracts/vendor-central/; for a new physical table, also add its name to STAGING_TABLE_NAMES in infra/lib/constructs/data-lake/staging-table.ts, which synth refuses until it matches and the staging grants are built from |
make validate-contracts, make generate-schemas, make generate-producer-packs, make generate-fixtures, then make infra-test |
| An agent tool | src/adapters/inbound/tool_handlers/schemas.py and a handler beside it |
make generate-tool-schemas |
| A page or preset view | presentation/pages/v2/pages.yaml, and for a tab its entry in presentation/navigation.yaml |
uv run python -m adapters.jobs.presentation_validation.generate --schema-version 2, uv run python -m adapters.jobs.presentation_validation.navigation, then make validate-page-schemas, make check-bakeability |
| Insight narration | contracts/insights/, contracts/prompts/insights/ |
make generate-insight-matrix; activate new prompt versions in Prompt administration |
| The agent's instructions | contracts/prompts/v1/managed-conversation.md |
make check-prompt-text, then the agent regression in validation |
| Different models | ADLYTICS_*_MODEL_ID in .env |
make deploy-all |
Then run the gates CONTRIBUTING lists for what you changed, and redeploy with make deploy-all. Repository structure explains where everything lives.
The repository ships guidance for AI coding assistants: Kiro loads .kiro/steering/ automatically, and other assistants read AGENTS.md. Build with an AI assistant lists starter prompts, from a first deploy to tracing a figure, and how the guidance is organised.
What a seller can't do today, as of 2026-10-19; a row dated later says so. A fix described as designed, in review or in progress is not deployed yet; the linked document owns how the product behaves now. Sizes are from the code and from a development deployment with one synthetic dataset, not from a seller's real catalog.
| What you can't do | Who notices | Status |
|---|---|---|
| Load Vendor Central reports. Producer onboarding accepts only the AMC query packs, so a customer deployment has no way to receive Vendor Central data. Retail health, its product pages and Products and ads stay empty, and the Growth check and Scorecard show no shipped sales or ad spend as a share of shipped sales. | Every vendor | No fix designed yet (as of 2026-10-19). Source acquisition |
Load one delivery of more than 20,000 rows, or one table unit of more than 50,000. That's about 6,600 active products for one day of vendor sales; a catalog of about 3,000 lands its history 2 days per delivery [inference from the load design: about 3 rows per active product a day]. Over a ceiling, the delivery is refused before anything is written (delivery_rows_exceed_cap, unit_rows_exceed_cap): land fewer days per delivery. |
The largest catalogs | Since 2026-10-26 (the earlier limit was about 840 active products a day). One day above the ceilings stays refused until they're re-measured at a larger writer memory, an infra/ change (write discipline §11, ADR-149, dated result). Load path |
Publish more than 5,417 Vendor or AMC deliveries into one serving election in GRAPH mode. As of 2026-11-14, one serving election holds at most 5,417 settled publications: the DynamoDB item limit (five items carry one 73-byte entry per publication), not a policy and not a time limit. Elections and alias drains read under each pass's time budget and resume across passes, and no worker reads a cohort's members after the election, so a backfill of any size below the limit finishes. A roster above it is refused with ADLY-EXEC_GRAPH-0045 and reported, and no publication is dropped. At about 22 settled publications a minute it is reached only if serving is held up for about 4 h while a backfill keeps landing [projection]. |
Operators running a large backfill in GRAPH mode |
Paging the roster lists, planned before the customer backfill slice, removes the limit. ADR-162, Sizing for large catalogs |
Forecast more than 200,000 products in one weekly demand forecast, or rely on the forecast publisher's interim sizes at scale. As of 2026-11-19, one run splits its products into at most 100 shards of 2,000: Athena UNLOAD writes at most 100 partitions, not a policy. A larger catalog is refused before any job runs (failed(input_build:ROSTER_TOO_LARGE), DemandForecastRunFailed). A 50,000-product run on dev with synthetic data published its forecast 81 min after its forecast jobs started, about 91 min with the input build's 600 s allowance, and the publisher's commit peaked at 1,783 MB when it had 2,048 MiB [measured, dev, 2026-11-19]. The publisher now has 6,144 MiB, sized for 200,000 products by projection from that run. Publisher memory above 50,000 products is projected, not measured. Its write parallelism is still an interim value. Past any limit the run fails closed and alarms; it never publishes part of a catalog, and the last published forecast stays current. |
Operators with the largest catalogs | The 100-shard limit is the platform's. The publisher's memory was re-set from the 50,000-product run on 2026-11-19; the values and what re-sets each are in Sizing for large catalogs |
| Forecast a product with under 26 weeks of known Vendor history, or see Chronos-2 for one with under 78 weeks of history. As of 2026-11-18. Under 26 known weeks nothing is shown. Chronos-2 is shown only where it beats both simple models, and SeasonalNaive needs 78 weeks to be tested, so below 78 weeks ETS is the only model that can be shown, and only when its backtest and 13-week forecast are valid; otherwise the product is withheld with the reason. | New and intermittent products | By design: every shown forecast carries a tested accuracy (ADR-157) |
| Get a forecast for every product when Vendor days fail to land. As of 2026-11-18. A day that doesn't land makes its week unknown for every product; the models skip that week, and no product's history restarts because of it. Four or more unknown weeks in the last 13 leave products untested and not shown. | Every vendor | By design; DemandForecastUnknownDays alarms when a sales day in the forecast window becomes unknown (ADR-156) |
| See AMC history older than 13 months, or data fresher than your pipeline lands it. AMC keeps 13 months of history, and pages refresh only when a delivery is published. | Everyone | AMC's own limit, not this sample's; history you land is kept. AMC source facts |
| See a list row or detail page past the top 50 products on Retail health. The page works at any catalog size and its product count, sums and movers cover every product; only the top 50 by shipped revenue get a row and a detail page, by design. | Sellers with large catalogs | By design (ADR-152). Retail health design |
See Audiences when a redelivered bake outruns the Baker's run, or, even at 10,240 MiB, count on its writes past the write ceiling below that memory's ceiling. As of 2026-10-29, a redelivered Audiences bake, which re-reads each object it finds already written, is projected to outrun the Baker's 900 s run below each memory's ceiling [derived, unverified: replay at width 23 is unmeasured], and fresh writes wider than the default's are unmeasured on the Lambda. The page keeps its last good version and BakeIsolatedRefusalLimit fires; it never shows wrong figures. |
The largest advertisers | The write width follows the Baker's memory, decided on 2026-10-27 (ADR-145) [derived]; the thresholds and their basis are in the scale envelope. Sizing for large catalogs |
Ask chat for reach by channel last quarter. On dev, chat refused it (ADLY-PLAN-0008) on 2026-10-18 and again on 2026-10-25, while it answered reach last quarter. |
Everyone who asks chat about quarterly reach | Cause not traced. It isn't the partition bound: the 2026-10-25 re-check read one partition. ADR-146 |
| Filter by brand, or use Audiences and Retention outside the US. Top lists mix brands, so the biggest brand dominates, and those two pages serve one marketplace. | Multi-brand and non-US sellers | Not designed yet; brand scope is a planned later capability. Workaround: the Campaigns name filter, or ask chat about a named product. Answerable questions |
| Read the staleness note above the Campaigns table at a glance. As of 2026-10-23, the Campaigns table no longer has a per-row Coverage column, but its one Late data note still repeats the same staleness sentence once for each stale source load, because each sentence names a different load time. Retail health's Products note does the same (seen on dev on 2026-10-22). Its first sentence also reads "in UTC, not by UTC". | Everyone who reads the Campaigns table or Retail health's products | Not fixed; the note shows each distinct served sentence once, and these differ only in their times. A single browser-owned line with the sentences in the Coverage sheet is the suggested fix. Campaign portfolio design, Retail health design |
| Read every refreshed page without repeated or clipped copy. As of 2026-10-23: the Scorecard's channel cards are followed by notes and a pointer that repeat what the cards say, and its insight cards repeat each card's spend-share sentence; New customers repeats "No comparison for calendar periods." in its scope line and insight card; the Growth check's "What changed" shows the full served retail movers sentence (seen on dev on 2026-10-22); the Retention starter question asks about "month 3" while cohorts are quarterly; and, as of 2026-10-19, on a new deployment with no data yet the period picker says "Choose another available reporting window" and "Data as of" today's date, although nothing has been published. | Everyone | Copy and layout follow-ups, not yet fixed. Each figure shown is still the served figure. Reach design, Scorecard design, Overview |
| Rely on chat never restating a remembered figure. Measured figures have been kept out of long-term memory since 2026-10-18 (ADR-147); live checks on 2026-10-18 and 2026-10-19 saw none restated, which is a few turns, not a rate. Memory can still hold a goal the user typed. | Everyone who uses chat | Fixed on dev 2026-10-18. Dated result |
| Ask chat for Amazon DSP cost per click. As of 2026-10-19, a chat question about Amazon DSP cost per click may return no figure. | Everyone who uses chat for DSP campaigns | Campaign detail and the Campaigns page show it. A root fix in the query planner is planned. Dated result |
| Trust that a chat figure is for the channel you asked about. On dev on 2026-10-19, after a refusal, chat answered two of five Sponsored Products questions with Amazon DSP figures. The figures were labelled DSP, but the heading above them did not name DSP. | Everyone who uses chat for sponsored channels | Not investigated; this is model and planner behaviour. Check the channel named next to each figure. Dated result |
| Get fast answers to hard chat questions. On dev on 2026-10-18, a full answer took a median of about 20 s and up to about 51 s at the 95th percentile (11 turns); model calls are most of that time. | Everyone | Being diagnosed; no fix is designed yet. Dated result |
Open the Scorecard and the Growth check right after updating an environment whose Scorecard was built before 2026-10-22. That release added a field the Scorecard requires. An environment whose last Scorecard build predates it shows "This page cannot be shown safely right now" on the Scorecard and at / until a new publication rebuilds the Scorecard. In the set-at-once refresh there is no repository-owned command to request that rebuild. |
Anyone updating an existing environment | Seen on dev on 2026-10-22 and worked around there by republishing data. A target-explicit rebuild command is an open decision. Preset artifact publisher |
| See every page move to new data at the same moment. Pages refresh one at a time, so for a short while after a publication two pages can show different publications. | Every deployment not cut over to GRAPH mode |
The set-at-once refresh needs the operational status plane, an opt-in setting any environment accepts since 2026-11-12 (Optional features), and then the operator's one-way cutover to GRAPH mode; the plane deploys in LEGACY mode. It is live-accepted only in the dev environment (2026-10-18); retiring the one-at-a-time path is the next planned change. The one-at-a-time path that customer deployments run is proven by unit and integration tests, not live, as of 2026-10-19: the fresh-environment deploy loads no data, so it bakes nothing. Preset artifact publisher, dated result |
| Trust every operations signal. The errors-by-operation alarm can return to OK while a page is still broken, and a chat answer can't yet be tied to the insight it cited. | Operators | Alarm fix designed and pending; the chat-to-insight link has no fix built. Dated result |
What has been accepted, and when, is recorded in validation results; what is built and what is deferred is in current state. The sample includes no AMC or Vendor Central client; you bring the extraction pipeline. Several validation tools and optional modes are restricted to an environment named dev.
Pages bake every product and campaign. Loading has its own row ceiling for one day's delivery, and Baker memory doesn't lift it: see the loading row in Known limits. Find your catalog's row below. A row counts campaigns on Campaigns, or DSP campaigns with delivery in a month on Audiences. If your row needs more than the default memory, set bake_tasks.baker_memory_mib and the row's write width, bake_tasks.baker_write_width, in contracts/operations/execution-graphs.yaml, run make generate-execution-graph-protocol and make check-bakeability, which refuses any other width. The write buffer grows with the width, so also set BAKE_FIXED_BYTES in src/domain/operations/bake_memory.py to the intercept the gate derives at the new width; skip it and make check-bakeability fails with bake-memory-derivation, whose message prints that intercept. Run make check-bakeability again, then deploy again (ADR-152, ADR-145).
make check-bakeability derives each ceiling and each write width; that the memory holds up to the ceiling is projected, linear in per-row terms measured locally at 10,000 and 100,000 rows. Widths 12, 23 and 46 each write their row's ceiling within the write allowance at the per-object write budget; width 64 writes only part of the Audiences objects at the 10,240 MiB ceiling [derived; scale envelope]. The count takes each Audiences campaign as one page of at most 50 segments and each profile path at its largest; fresh Audiences writes on dev met that budget at 8 and at 23 in flight, and Campaigns' small bakes at 8 but not at 23, so what that cost means for the 2,048 MiB Campaigns ceiling is unmeasured; widths 46 and 64 are unmeasured on the Lambda, so those rows' writes can bind before their memory ceiling; a redelivered Audiences bake didn't at 8, so it reaches the 900 s invocation first (the last row; scale envelope). Past a limit, the page keeps its last good version and alarms.
| Catalog | Baker memory (bake_tasks.baker_memory_mib) and write width (baker_write_width) |
What alarms beyond it |
|---|---|---|
| Any number of products (Retail health, New customers) | 2,048, the default | Nothing in the bake: these reads are page-sized. The Retail render peaked at 1.57 MB at both 10,000 and 100,000 products [measured, local probe, 2026-10-25] |
| Up to 22,457 | 1,024, width 12, optional: a smaller size than the default | BakeIsolatedRefusalLimit with population_over_ceiling (Campaigns) or rows_over_ceiling (Audiences) [projection] |
| Up to 44,937 | 2,048, width 23, the default | The same [projection] |
| Up to 89,875 | 4,096, width 46 | The same [projection]. Writes this wide are unmeasured on the Lambda and can pass the invocation first, BakeIsolatedRefusalLimit with bodies_over_invocation [unverified] |
| Up to 225,792 | 10,240, width 64, the Lambda maximum | The same on Campaigns [projection]. Writes at width 64 are unmeasured on the Lambda. Either page can pass its budget (BakeTaskOverBudget; nothing is cut) or the invocation (BakeIsolatedRefusalLimit with bodies_over_invocation) below its memory ceiling, at the sizes the scale envelope derives [projection, unverified] |
| A redelivered Audiences bake | Any | BakeIsolatedRefusalLimit with bodies_over_invocation past the 900 s invocation from a catalog below each memory's ceiling; it passes its 600 s budget (BakeTaskOverBudget; nothing is cut) at a smaller catalog [derived, unverified: one dev bake's width-8 replay cost, 2026-10-25, held at the row's width; replay at those widths is unmeasured; the scale envelope owns the thresholds and their basis] |
A serving election and its alias drains run in the promoter's 60 s pass. Each pass reads candidates and drains aliases until 35 s remain, about 200 candidates or 130 aliases a pass at the rates measured on dev (2026-11-13), and keeps what it read for the next pass, so a backlog of any size below the bound completes [projection from the dev rates]. When a backlog of waiting conflict units also fills the promoter's first phase, serving gets about 5 s a pass, about 40 candidates: it still completes, but over hours rather than minutes [inference].
| Publications waiting for one election | What happens | What reports it |
|---|---|---|
| Up to about 200 | Elected in one pass | Nothing extra |
| Up to 5,417 | Read over about one pass per 200; aliases drain about 130 a pass | The promoter's serving_staged and serving_unstaged counts on its terminal line |
| Above 5,417 | Refused: no election, nothing dropped | ADLY-EXEC_GRAPH-0045 in the promoter's errors, until the roster lists are paged |
As of 2026-11-19; the measured values are from one 50,000-product run on dev with synthetic data. One run forecasts every product in its weekly input, in shards of engine.shard_max_asins (2,000) from contracts/forecasting/demand-forecast.yaml. One publisher invocation then commits the whole generation: it merges and ranks every product's entry in memory and writes the list pages. Past every limit below, nothing partial is published and the last published forecast stays current.
| Limit | Value and kind | What happens beyond it | What re-sets it |
|---|---|---|---|
| Products in one run | 200,000 (100 shards × 2,000). Derived: Athena UNLOAD writes at most 100 partitions | Refused before any job runs: failed(input_build:ROSTER_TOO_LARGE) and DemandForecastRunFailed |
Nothing planned; it is the platform's limit |
| Publisher memory | 6,144 MiB, design §10's rung. Sized from the 50,000-product commit peak projected to 200,000 [projection], not measured above 50,000 | The whole commit, which reads the shard parts, merges them and writes the pages, peaked at 684 MB at 10,000 products and 1,783 MB at 50,000 [measured, dev, 2026-11-19]. On the line through those two peaks, about 27.5 KB a product, it needs about 5,900 MB at 200,000 [projection]. Out of memory, the commit fails: failed(publish:…), DemandForecastRunFailed and the publisher's Errors alarm |
A larger scale run on dev: the smallest memory at least 1.5 × its measured commit peak |
| Publisher run time | 900 s. Derived: the Lambda maximum | The commit took 95 s at 50,000, writing 1,000 list pages [measured, dev, 2026-11-19]; writing about 8,000 list pages at 200,000 is unmeasured. Past 900 s the commit fails: failed(publish:…) and DemandForecastRunFailed |
Nothing planned; a commit across invocations isn't designed |
| Write parallelism | 4 conditional writes at a time per publisher call, and 4 shards published at once. Interim | Write speed only; no data is refused. A throttled write makes up to 10 SDK attempts, then 3 Step Functions retries 30 s apart and doubling; then failed(publish:ForecastStoreThrottled), which each of up to 3 later daily checks re-runs. Each publisher call logs store_retry_attempts and throttled |
Re-derived from the 10,000-product scale run's throttle and retry counts and the table's on-demand write throughput |
| One stored item | 350,000 bytes. Derived: the DynamoDB 400 KB item limit less a margin | Nothing is written for that call: held_quality(item_too_large) and DemandForecastHeld |
Nothing planned; it is the platform's limit |
These are designed or in progress, not built, and carry no dates. Every figure they add will come from new governed metrics, under the same rule as every figure today.
- Forecasting: a Vendor Central connector, so a customer deployment can load the history the Demand forecast needs, and a producer for product titles and the product hierarchy. A baseline forecast of ad-attributed purchases and revenue is proposed and not built; it would reuse the same engine. Forecasting
- Budget simulation: try a budget move against each campaign's response curve before making it in Amazon Ads; it changes nothing in Amazon. Response curves and budget simulation
- Amazon DSP's own forecasts as a second opinion: shown beside the sample's curve, labelled as Amazon's and kept out of totals. ADR-091
- First-time buyers per product: a governed per-product new-to-brand metric for the Products and ads First-time purchases column. Products and ads
- Other channels: the data model can map data from other channels into the same structure, though only Amazon sources are loaded today. ADR-052
You are responsible for the cost of the AWS services you use while running this sample. We recommend creating an AWS Budget to monitor costs. Prices below are us-east-1, on-demand, without Free Tier or discounts, and are estimates, not a quote. Use the AWS Pricing Calculator for your Region and usage.
Charged whether or not anyone uses the deployment. Counts are from the default configuration (24 stacks; the alarm count was re-read from a synthesized template on 2026-10-19, plus the 7 alarms on 11 metrics the two demand-forecast stacks add, read from their synthesized templates on 2026-11-16); prices are from the AWS Price List API on 2026-10-01, and alarm billing per metric from the CloudWatch pricing page on 2026-10-19.
| Service | What is deployed | Monthly |
|---|---|---|
| AWS WAF | 3 web ACLs ($5 each) with 8 rules in total ($1 each) | $23.00 |
| CloudWatch alarms | 83 standard-resolution alarms, billed $0.10 per metric each alarm reads: 71 alarms on 84 metrics, plus 12 Metrics Insights query alarms billed per metric their query analyses (at least one each) | from $9.60 |
| AWS Secrets Manager | 3 secrets ($0.40 each) | $1.20 |
| AWS KMS | 1 customer-managed signing key | $1.00 |
| Subtotal | from $34.80 |
Add small charges for scheduled Lambda jobs, DynamoDB point-in-time recovery, S3 and CloudWatch Logs storage, the demand-forecast job image in Amazon ECR (about 0.5 GB), and AgentCore Memory, all of which grow with use. AWS WAF, CloudWatch, Secrets Manager, and KMS pricing pages have current rates.
An illustrative model for chat turns only. Page insight narration also calls Bedrock: after each data publication, and when a user opens a deeper analysis.
| Input | Reference value |
|---|---|
| Turn mix | 80% quick (2,000 input + 500 output tokens), 20% deep (8,000 input + 2,000 output tokens) |
| Illustrative model rate | $6 per million input tokens, $30 per million output tokens. Replace with the prices of the models you configure on Amazon Bedrock pricing. |
| AgentCore Runtime | One session per turn: 18 active vCPU-seconds and 125 GB-seconds (10 s at 1 GB, 20 s at 2 GB, 30 s at 2.5 GB), at $0.0895 per vCPU-hour and $0.00945 per GB-hour |
| AgentCore Gateway | Two operations per turn at $5 per million |
| Athena | 10 MB scanned per turn at $5 per TB |
| Bedrock Guardrails | One check per question, under 1,000 characters: $0.15 per 1,000 text units for content filters and $0.10 for sensitive information (2026-10-01) |
| Scenario | Turns per month | Bedrock | AgentCore Runtime | Gateway | Athena | Guardrails | Subtotal |
|---|---|---|---|---|---|---|---|
| Trial | 100 | $4.32 | $0.08 | <$0.01 | $0.01 | $0.03 | $4.43 |
| Team | 2,000 | $86.40 | $1.55 | $0.02 | $0.10 | $0.50 | $88.57 |
| Department | 10,000 | $432.00 | $7.76 | $0.10 | $0.50 | $2.50 | $442.86 |
Bedrock, AgentCore, Gateway, and Athena rates were checked on 2026-09-04. Not included: CloudFront, Cognito, Lambda, DynamoDB and S3 requests, CloudWatch Logs ingestion, data transfer, the optional features, and any AMC subscription. Monthly total = idle subtotal + usage subtotal + those.
This sample has been reviewed and tested in a development account with synthetic data only. Before production use, review it against your own requirements. In particular:
| Area | What the sample does | What you should do for production |
|---|---|---|
| API endpoint | The HTTP API keeps its default execute-api hostname, which is publicly reachable. Every protected route requires a verified Cognito session, and requests that bypass CloudFront are refused (edge entry). |
Serve the API from your own domain and disable the default endpoint. |
| Viewer TLS | The site uses CloudFront's default *.cloudfront.net certificate. CloudFront fixes its security policy at TLSv1, so browsers may connect with TLS 1.0 or 1.1. |
Serve the site from your own domain with an ACM certificate, and set the distribution's minimum protocol to TLS 1.2 (TLSv1.2_2021) or later. |
| Encryption | S3 and Athena use S3-managed keys (SSE-S3); a customer-managed key mode is not available yet (ADR-018). | Decide whether your data classification needs KMS customer-managed keys. |
| Data residency | Data stays in your account. Question screening uses a guardrail profile, and the example model IDs are cross-Region inference profiles; both may process a request in another Region of the same geography (US or EU). The edge WAF is in us-east-1. | Confirm this meets your residency requirements. Model IDs without a geography prefix keep inference in your Region where the model is offered there. |
| Diagnostic logs | The agent runtime's own log group keeps its runtime logs for 90 days. With ADLYTICS_TRANSACTION_SEARCH on, the runtime's spans, raw tool results included, go to the account-wide Transaction Search group aws/spans. Its retention is the account's Transaction Search setting, and with online evaluation on, the evaluation execution role can read it (observability). |
Restrict who can read CloudWatch Logs in the account, aws/spans included, and decide whether that group's retention and readers fit your data. |
| Sign-in | Self sign-up is off; users are invited by an administrator. | Use your identity provider policies (MFA, password rules) as required. |
| Test tooling | The probes in validation/ are restricted to an environment named dev and use fictional data. |
Do not treat sample test users or probes as production controls. |
Report a potential security issue through the AWS vulnerability reporting page, not a public GitHub issue.
make destroy-all PROFILE=<your-profile> ENV=<env> CONFIRM=<env>scripts/destroy-all.sh states what it removes, what it keeps, and how it reports what is left. Add INCLUDE_ACCOUNT_SETTINGS=1 to also remove Adlytics-Observability-<env>, which holds an account-wide tracing setting. Resources that hold data are retained on purpose and keep billing until you delete them by hand:
| Resource | Where | Before deleting |
|---|---|---|
| S3 buckets: raw deliveries, data lake, Athena results, published page artifacts | Adlytics-DataV2-<env>, Adlytics-PublisherArtifactStore-<env> |
Empty them, including old object versions. |
| S3 bucket: demand-forecast processing (staged weekly inputs and shard candidates) | Adlytics-DemandForecastData-<env> |
Empty it, including old object versions; its runs/ objects also expire after 90 days. |
| DynamoDB tables: publication state, insight cache, prompt registry, artifact pointers, audit records | DataV2, InsightCache, InsightPromptRegistry, PublisherArtifactStore, AgentQuality | None, except the two audit tables adlytics-<env>-agent-quality-audit and adlytics-<env>-agent-quality-findings: they are tamper-protected by design (ADR-080) and are kept. See Remove the audit tables. |
Glue databases adlytics_<env>_v2_source_aligned, adlytics_<env>_v2_candidate and adlytics_<env>_v2_current, with their tables (<env> with each - written as _) |
Adlytics-DataV2-<env>; untagged, so destroy-all lists them by name |
None: aws glue delete-database --profile <your-profile> --name <database> deletes a database and its tables. |
| Cognito user pool, its client secret, and the review-token function and its log group | Adlytics-Auth-<env> |
None. |
| AgentCore Memory (conversation history) | Adlytics-Memory-<env> |
None. |
| Audit log group | Adlytics-AgentQuality-<env> |
Deletion protection; turn it off first. |
| Agent runtime log group | /aws/bedrock-agentcore/runtimes/harness_* |
Expires after 90 days, or delete it. |
| Optional features' data: evaluation evidence tables and result log groups, the evaluator, the operational status table | Adlytics-EvaluationEvidence-<env>, Adlytics-EvaluationV4-<env>, Adlytics-OperationalStatusStore-<env> |
Result log groups have deletion protection; turn it off first. |
| Optional operational plane: the execution-graph tables | Adlytics-ControlPlaneAuthorityStore-<env> |
Every table has deletion protection; turn it off first. |
Deploying the same environment name again fails while these exist, because several have fixed names: delete them first, or choose a new ENV.
The two audit tables bill on demand and cost close to nothing with no traffic, so you can leave them. Their resource policy lets only the deployment's CloudFormation execution role turn off deletion protection; operator tools › remove the audit tables gives the import-and-delete procedure. Deleting them deletes every audit record.
The CDK bootstrap stacks (CDKToolkit) in your Region and us-east-1 are shared by any CDK app in the account; remove them only if nothing else uses them.
See CONTRIBUTING, which lists the local gates.
See CONTRIBUTING for more information.
This library is licensed under the MIT-0 License. See the LICENSE file.