How Does an Agent Work with SPINS, Circana & Nielsen Data?
An agent works with syndicated data by pairing a semantic layer (a shared dictionary that defines every measure the same way everywhere) with a provider rulebook (how each measure may be added up), then verifying every query against both before an answer ships. Skip either layer and the agent becomes the most dangerous thing in analytics: a fast producer of numbers that look right and are wrong.
What syndicated data is
Syndicated data is the shared measurement system US retail runs on: when you and your buyer argue about your velocity, you are both looking at a syndicated number, which is why getting its math wrong in a retailer meeting is so costly. For what the data is, how it is collected, and how SPINS, Circana, and Nielsen differ, see The Complete Guide to Syndicated Data; this chapter assumes that ground and focuses on what an agent must do to handle the data safely.
Two facts about how the data is built explain most of its quirks. It is projected: providers observe a universe of cooperating stores and extrapolate to the market, so measures are defined against weighted universes rather than raw store counts. And it is periodized: data arrives in provider-defined weeks and periods, on the provider's calendar, with restatements when the universe changes. Neither fact is visible in a CSV's column headers, and both change what math is legal. The rules that make syndicated data trustworthy live outside the file.
One more fact shapes the architecture: no single feed shows a multi-channel brand its whole business. The same item carries different codes across feeds, the same retailer appears under different market definitions, and "last month" means different weeks on different provider calendars. That is why Sous connects to all three syndicated providers plus retailer portals and internal files, rather than treating one extract as the world.
The aggregation trap
Here is where a naive question-to-query system dies quietly. Syndicated measures are constructed, with rules baked into their definitions, rather than raw columns you can freely sum and average.
Start with ACV, All Commodity Volume. NielsenIQ defines it as the total dollar sales of a store or retailer across all products, and it exists to weight distribution: your % ACV distribution is the share of total market ACV flowing through stores that scanned your product, so placement in a high-volume store counts for more than placement in a small one [1]. TDP, total distribution points, builds on it: your brand's TDP is the sum of % ACV distribution across all of your items [2]. And velocity is a family of measures of rate of sale, each calculated against a different denominator: dollars per point of % ACV distribution, dollars per TDP, and dollars or units per store per week are all velocity [3]. Sales = distribution × velocity is the fundamental decomposition of CPG performance, and every term in it carries construction rules. The canonical definitions and worked examples live in what ACV, TDP, and velocity actually mean.
Now watch a few example queries that run without error break those rules:
| Query that executes fine | Why the math is illegal |
|---|---|
| Average % ACV across 4 weeks and 3 markets for a "national average" | Shares of different-sized ACV bases neither average across markets nor add across periods |
| Sum weekly velocity into monthly velocity | The denominator (TDP) changed every week |
| Sum the "only" merchandising conditions and add an "any" condition | The conditions are mutually exclusive only at item, chain and week; above that they overlap and double-count |
The full catalog of syndicated math that breaks silently, organized by failure type with the correct read for each, is in the aggregation trap. Every one of these returns a plausible-looking figure. The database cannot tell you the math is illegal. Only the rulebook can. A category manager with a few years of scars knows each row of that table by feel. An AI model that has never seen your provider's conventions knows none of them, and nothing in the file's column layout will teach it.
And the rulebook is provider-specific. Measure names, market definitions, period conventions, and which aggregations are legal all differ across SPINS, Circana, and Nielsen. An agent that learned "the right way" on one provider's extract will confidently apply it to another's and be wrong in ways that only surface in a buyer meeting. The rulebook layer is the judgment experienced analysts carry in their heads, written down and enforced on every query instead of applied when someone remembers.
Rulebooks, semantics, and verification
The architecture that survives this has three layers, and the order matters.
The semantic layer defines what things are, the same way everywhere: this column is % ACV distribution, this product roll-up runs brand then sub-brand then UPC, this market contains that one, "last period" means the latest completed period. Without it, the agent is pattern-matching column names instead of reasoning about measures.
The provider rulebook defines what is allowed: which measures sum, which never do, which are period-locked, how each provider builds its markets and periods.
Verification is the layer that makes the other two count. Before an answer ships, the agent checks the executed query against the semantic layer and the rulebook: right measure, legal aggregation, correct period and product level. The query stays attached to the answer inside the workbook, so a human can audit the math behind any number.
One more architectural consequence: because the agent knows how each extract is structured, it can also validate the next period's file when it lands and rebuild everything on top of it, covered in how agents keep syndicated reports current. For how much this architecture buys in accuracy, "how accurate are AI agents on syndicated data?" puts benchmark numbers on why raw question-to-query AI is not safe.