Karum

Autonomous retail expansion for brands: tell Karum your brand and your city, and it tells you which doors to pitch, where to open, who to partner with, who to skip, and how to get there.

Comment

Inspiration

Emerging brands often guess where to sell their products. A field sales representative might walk into ten stores in a day, but half of those stores have customers who do not match the product. The brand wastes time, and the store misses a product its customers would actually buy.

We saw this problem and realized the data to fix it already existed. Qloo's Taste Graph can answer "where do the people who love this brand actually go?" instead of just "what is popular on Yelp?" We combined Qloo with Vertex AI for checking live menus and Google Maps for planning driving routes. The result is Karum: a brand-operated expansion agent. You give it a brand identity and a city, and it tells you which stores to pitch, where to open a pop-up, which partners to work with, which stores to skip, what is on each store's menu right now, and the best route to visit them all.

What it does

Karum is a business-to-business platform that helps consumer brands find the right physical stores and locations. You give Karum a brand (or a mix of reference brands, music genres, and lifestyle tags that describe your customers) and a target city. Karum then:

  • Finds stores to pitch (wholesale doors) — ranks independent stores, bars, and cafes whose customers share the same tastes as your brand, using Qloo's cultural data.
  • Finds flagship and pop-up locations — identifies city blocks and neighborhoods where your target customers are concentrated, using Qloo heatmaps.
  • Finds competitor displacement opportunities — spots stores already selling a competing product and creates a battlecard explaining why your brand fits better.
  • Suggests collaborations — finds non-competing shops, such as bookstores or galleries, whose customers match yours for joint events.
  • Checks live menus and shelves — uses Vertex AI with Google Search to look at each store's current menu, delivery listings, or retail shelf for competitors and complementary products.
  • Scores every store — combines cultural fit, shelf opportunity, and customer demographics into one easy-to-understand score from 0 to 100.
  • Writes sales pitches and battlecards — creates a personalized script for the shopkeeper, a recommended product (SKU), and a competitor battlecard for each store.
  • Plans the field route — calculates the best driving order to visit all qualified stores using Google Maps.
  • Exports PDF documents — creates a field run-sheet or a site-selection brief, with facts from Qloo in normal text and AI guesses in italic text.
  • Shows which stores to skip — a "Doors to Skip" list flags popular stores that do not match your brand or already have too many competing products.
  • Compares against a plain AI — shows a side-by-side view proving that a regular AI without Qloo data gives generic tourist recommendations while Karum finds high-potential stores.

Every piece of information is labeled with its source: Qloo fact, Google fact, AI inference, or your input. If Karum cannot find an answer, it says so instead of guessing.

How we built it

Two people built Karum as a set of connected services, each with a single job, so the brand-facing website stays fast while the heavy work happens behind it. Everything leans on three outside sources of truth: Qloo for cultural taste, Google (Vertex AI, Search, Maps, and Places) for live menus, locations, and routes, and the brand's own input.

We agreed on the rules first. Before building any feature, we decided exactly what information the services would exchange, and we gave every single piece of data a source label: Qloo fact, Google fact, AI inference, or your input. No number is allowed to ship without saying where it came from. This one rule is what makes the evidence drawer and the "plain AI vs. Karum" comparison trustworthy later on.

The taste engine is the only part of Karum allowed to talk to Qloo. It turns a brand — or a mix of reference brands, genres, and lifestyle tags — into Qloo's cultural identifiers, then ranks stores by how closely their customers match the brand, scores customer age-group fit, and pulls neighborhood heatmaps for pop-up scouting. It remembers Qloo's answers for a day so repeated searches never waste the monthly request budget, and it can even replay recorded answers with no internet at all.

The AI engine uses Google's Gemini model with live Google Search to read each store's current menu or shelf, check for competing and complementary products, and write the shopkeeper pitch, the competitor battlecard, and the recommended product. It also writes a deliberately "plain AI" answer with no Qloo data, so we can show the difference side by side. If it cannot verify something, it says so instead of inventing an answer.

The coordinator receives each request, looks up the city once, then calls the taste engine, Google Places for store details, the AI engine, and Google Maps for the best driving route. It combines everything into the final store score, decides which stores go on the skip list, saves every run, and streams live progress to the screen so you watch the work happen.

The website is the view judges and users see, with no login required. It shows the mode selector and one-click examples (Austin, Brooklyn, Mumbai), a live timeline of each step, a map with store stops, heatmap, and skip pins, the ranked store list with score bars and menu citations, and the toggle that compares Karum against a plain AI.

How the store score works

The taste engine provides cultural fit and demographic fit. The AI engine provides shelf opportunity. The coordinator combines the three into a single score, shown from 0 to 100:

Store score = 50% × Taste fit + 30% × Shelf opportunity + 20% × Demographic fit

  • Taste fit — how well the store's customers match your brand
  • Shelf opportunity — how much room there is on the menu or shelf for your product
  • Demographic fit — how well the store's customer age groups match your target customers

If the menu check is unavailable, the shelf term is marked unknown and the score is recalculated using only the other two. Stores that fall below the score floor of the returned list, or that already carry four or more direct competitors, go on the skip list with a reason.

Challenges we ran into

Some brands do not exist in Qloo. Madre Mezcal does not appear in Qloo at all, even when searching by brand or place. We replaced it with Qloo-verified brands (Ilegal Mezcal, Aesop, and Khruangbin) for the Austin example. Common names can also point to the wrong city — for example, "Blind Pig" resolved to a city in Ukraine, not the US. So the brand builder makes the user confirm the exact store before starting.

Qloo responses can be misleading. A successful response does not mean a setting was actually used. Some settings are silently ignored for certain search types, and a location search returns zero results unless it is formatted in one exact way. We only use the search spellings that we tested and verified, and we document the rest as having no effect.

Limited monthly requests. The hackathon Qloo key allows 10,000 requests per month. We stay under this limit by remembering responses for 24 hours, making sure repeated requests share one call, keeping a backup cache, and stopping before the reserve is used up. We also have a mode that replays recorded responses with no internet calls, so the system runs without any API keys.

Failing without lying. When menu checking is unavailable, we do not invent shelf data. We mark it unknown, recalculate the score without it, and show the menu as unverified. When the AI service fails, the store list still appears with a "degraded" label. If a browser window closes, the run keeps going in the background so the user can come back and see the results.

Honest scoring. Raw Qloo match scores change depending on the brand and city, so we never show a raw score as if it were absolute. Instead, we show each store's rank within the current list. The score floor for skipping stores comes from actual test data, not a guessed number.

Accomplishments that we're proud of

  • Qloo is essential to the product. Without Qloo, a regular AI just lists famous bars. Karum uses six or more distinct Qloo features inside a reliable, multi-service setup: brand resolution, store ranking, heatmaps, taste tags, explainability data, and audience comparison.
  • Honesty rules are built into the code. Every field is labeled with its source. A missing answer is shown as missing, never guessed. Undocumented Qloo settings never appear in code, test data, or AI prompts.
  • Skipping stores is a featured capability. The "Doors to Skip" list tells brands which popular-looking stores to avoid, which is just as valuable as the recommended list.
  • Plain AI comparison. A side-by-side view shows that a regular AI without Qloo gives generic tourist recommendations while Karum finds stores with real customer fit.
  • Transparent store score. Every number in the score cites its source, and the formula comes from tested data, not intuition.
  • Works even when parts fail. If the AI fails, stores still appear. If menu checking fails, stores still appear with "unknown" shelf data. The system is degraded but never empty.
  • Five services built by two people. Two people built the website, the coordinator, the taste and AI engines, the shared data rules, and the full cloud deployment — all under an MIT license.
  • Fast example loading. Stored example runs load in under one second with no live processing.

What we learned

  • Qloo matters, but only when used carefully. At first we thought a regular AI could just know which stores fit a brand. It cannot. It lists famous places without knowing whether their customers match your product.
  • Telling brands what to skip is valuable. Telling a brand which stores to avoid changes field sales from "visit every popular place" to "visit the right places."
  • Honesty rules slow you down but build trust. Labeling every fact with its source meant we built more slowly, but the evidence drawer and AI comparison view earn trust because every number can be traced.
  • The score formula tells a story. Raw match scores move with each brand and city, so a store's rank within the current list matters more than the raw number.
  • Test search spellings before using them. We tested Qloo settings during a two-week spike before writing production code. Using only verified spellings prevented silent failures.

What's next for Karum

Improvements to current features

  • Improve the store score formula. Today's weights (50% taste, 30% shelf, 20% demographics) come from our own testing, not from real sales results. With sales data from field representatives, we can tune the weights through A/B tests, and add a fourth factor for how quickly a store sells through its stock.
  • Speed up first-time searches. A new search currently targets under 8 seconds. Running the address lookup, store search, menu check, and route planning more in parallel should bring the slowest searches down to 4–5 seconds.
  • Add more skip reasons. Today stores are skipped for low match scores or for having four or more competitors. Adding reasons like "exclusive contract with a competitor" or "store category is paused" from menu data would make the skip list more useful.
  • Deepen the evidence drawer. Link each Qloo fact directly to the exact search behind it, so anyone can replay a single search.
  • Support mobile phones. The website currently targets desktop browsers for judges. The same screens should work on iOS and Android so sales representatives can use Karum in a store.

New features to add

  • Sync product inventory. Connect to a brand's product catalog (Shopify, Square, Lightspeed) so recommended products reflect what the brand actually has in stock, not just taste matching.
  • Watch competitors. Track competing brands across stores and alert the user when a competitor disappears from a menu — that empty shelf space is an opportunity to pitch your brand.
  • Run searches across many cities. Today one search covers one city. Allow one search across Austin, Brooklyn, and Mumbai, with a comparison board showing where your brand fits best.
  • View past searches and changes. Save every search so a brand can repeat it six weeks later and see which stores entered or left the list, which skip reasons changed, and which products shifted.
  • Let teams work together. Add shared project spaces, comments on store cards, and the ability to export the field route to Google Calendar or a route-planning app.
  • Work offline. Save the most recent completed search on the phone so a sales representative can view store cards and pitches inside a building with no internet signal.

Platform and infrastructure

  • Send emails from the platform. Add the ability to send a pitch or brief by email, recording who received each message and when, but never storing the message text.
  • Add Qloo trending data. Qloo trending needs at least six months of data; we will add it once the monthly request budget has enough room.
  • Show how much each Qloo signal matters. Build a tool that removes one Qloo feature at a time to show how much each one changes the final store ranking.
  • Let brands connect their own tools. Allow brands to query Karum directly from their own software.
  • Track empty storefronts. Save vacant store locations and alert the user when a newly empty unit appears in a high-fit neighborhood.
Share this project:

Updates

Submission history