Skip to content

About

No description, website, or topics provided.

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

1 watching

Forks

Latest commit

 

History

35 Commits

Folders and files

Repository files navigation

Adlytics AI

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).

Solutions

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

The problem it solves

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 it answers, and what it refuses

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.

How it works

Call-flow diagram — from your data delivery to an answer in the browser.

Call-flow diagram: from your data delivery to an answer in the browser. Your extraction pipeline runs the AMC SQL (Vendor Central reports can't be landed yet) and lands each result in an S3 landing bucket; ingestion validates it against the data contracts and publishes an immutable version to the data lake, which the measurement tools read. A browser question reaches the Conversation API, which checks it with Amazon Bedrock Guardrails and invokes the AgentCore agent as the signed-in user; the agent calls the tools through AgentCore Gateway, and its answer streams back to the browser with an audit record written before the stream ends.

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.

  1. 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.
  2. 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.
  3. 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.
  4. 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.

Call-flow diagram: how a page refreshes after new data is published, by default. A new published version in the data lake starts one bake per page and window, which computes that page from the version with the measurement layer. When that page builds, with data or a designed absence, its own pointer advances to the new immutable artifact and the Presentation API serves it to the browser; when it fails, that page keeps serving its last good version, and a bake that keeps failing raises a CloudWatch alarm. Insight narration from Amazon Bedrock is attached to a page by its revision. A box labelled opt-in operational status plane notes that a deployment with that plane on and cut over to GRAPH mode instead builds every affected page as one set, whose pointers advance together or not at all; the plane is live-accepted only in the dev environment.

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/.

What each solution shows

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.

Prerequisites

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).

Quickstart

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.

Deploy

  1. Configure. Copy .env.example to .env and 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 from contracts/forecasting/model-artifacts.json.
  2. Deploy everything. Run make deploy-all without APPROVE first: it deploys nothing and shows the target account, Region and the changes. Then run it with APPROVE=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 of scripts/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 new ENV.
  3. 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:

  1. Stop landing deliveries.
  2. Wait until adlytics-<env>-ingestion and adlytics-<env>-semantic-write.fifo both 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
  3. Deploy with the two commands above.
  4. 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).
  5. 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).

Check the deployment

  • 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.

Optional features

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

Load your data

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.

Extend it

Call-flow diagram — how a change moves from a declared contract to a deployed environment.

Call-flow diagram: how a change moves from a declared contract to a deployed environment. You edit a declared contract, such as a metric, a data contract, a page or a prompt. A make generate target regenerates the schemas, fixtures and typed code that depend on it. The local gates make check and make verify refuse any drift between contract, code and docs. Only a passing tree is deployed, with make deploy-all, first as a diff and then with approval.

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.

Build with an AI assistant

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.

Known limits

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.

Sizing for large catalogs

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]

Backfills in GRAPH mode

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

Weekly demand forecast

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

What's coming next

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

Cost

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.

While idle

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.

With use

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.

Security considerations

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.

Clean up

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.

Remove the audit tables (optional)

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.

Contributing

See CONTRIBUTING, which lists the local gates.

Security

See CONTRIBUTING for more information.

License

This library is licensed under the MIT-0 License. See the LICENSE file.

About

No description, website, or topics provided.

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages