Skip to content

Overview

Consumr.ai is a consumer-intelligence platform. It pulls real audience, search, and social signals from the major advertising and analytics platforms, turns them into a library of intelligence reports, and uses those same signals to build AI “twins” — LLM personas that stand in for real consumer cohorts — so brands can run research and plan activation at speed and scale.

If you read nothing else, the product does three things, end to end:

  1. Generates intelligence reports — audience, intent, social, market, product and more, each built from real platform data plus an LLM insight layer.
  2. Builds AI twins & respondents — LLM personas grounded in those reports, used for qualitative and quantitative research.
  3. Turns insight into activation — audience, keyword and creative plans, plus cross-channel budget and audience optimization.

Twins are the best-known piece, but they sit on top of a much larger report engine — they are one output of the platform, not the whole platform.

The key distinction from fully synthetic tools: Consumr.ai twins are not random responses. Each twin is compiled from real-signal reports drawn from Meta audience data and other social/search sources, making it a credible representative of a defined cohort rather than a statistical hallucination.

📎 Evidence

Consumr.ai is a consumer-intelligence and research platformscratchpad/sdd/icp-findings.md:3-5 — positioning doc frames it as AI twins grounded in real audience signals; pw-enterprise/pyproject.toml:8 description is consumr.ai. ✅

Twins are LLM personas grounded in real signalsconsumr-ai-intro/.work/transcripts/daily-connect-1.txt:92-94 (twins from intent/mentions/behavior reports of real cohorts) + pw-enterprise/ai_twin/respondents/respondent_prompt_composer.py:57-64 (prompt uses behavior_summary/intent_summary/mentions_summary). ✅

Not random — distinct from syntheticconsumr-ai-intro/.work/transcripts/daily-connect-1.txt:186-234 (founder contrasts central-limit-theorem synthetic tools vs real social consumers) + scratchpad/sdd/icp-findings.md:6-7 (do NOT call it synthetic). ✅

Twin compiled from three reportsconsumr-ai-intro/.work/transcripts/daily-connect-1.txt:92-94 (intent, mentions, behavior) + pw-enterprise/research_setup/FLOW.md:33-38 (create-twin enqueues Behavior, Intent, Mentions, Persona jobs). ✅

Consumr.ai is organised around a report engine. Almost everything the product produces is a “report” — a stored, searchable analysis object that is registered in one central index and generated on demand or on a schedule. Reports group into a handful of capability families:

Capability family What it produces Examples
Audience & market intelligence Who a cohort is; how audiences compare, overlap, and where to expand Behavior / Audience Insights, Professional (LinkedIn), Contrast, Overlap / Receptivity, Household, Market Finder
Intent & search What a cohort is actively searching for, and keyword/contextual plans Intent (contextual), Intent Planner (keyword / Amazon ASIN / video)
Social & product What people say about brands, topics, and products Mentions / Social listening, Product & app-review analysis
Activation & creative Turning insight into media and creative plans Audience Plan, Creative Planner (ideas, briefs, assets), budget & audience optimizers
AI twins & research LLM personas and the research run on them Twins, Respondents, focus groups, surveys, aggregated Research PDF — see below

Each report answers one specific question. All are rows in the central global_run_report index; the three that build a twin (Behavior, Intent, Mentions) are detailed further under How a twin is built.

Report What it is — the question it answers
Behavior / Audience Insights Who is this audience? Demographics, interests and behaviors of an audience, category, interest or website — per ad platform. The base report, and the persona a twin is built on.
Professional (LinkedIn) The same “who is this audience?” for a B2B / professional cohort, from LinkedIn facets (seniority, titles, skills, industries). Built on the shared audience-insights generator rather than a separate pipeline.
Contrast / Funnel How do two or three audiences differ? A side-by-side delta across behavior reports.
Overlap / Receptivity How much do two audiences overlap, and how receptive is one to the other? An affinity “Receptivity Index” — for influencer/partner selection and cannibalization checks.
Intent (Contextual) What is this cohort actively searching for? Top keywords and URLs, questions, seasonality and funnel stage, from real search data.
Mentions / Social What are people saying? Aggregated social, forum, review and news conversations with sentiment, themes and speaker types.
Market Finder Where is the demand? Geographic sizing (country → state → city → zip) for an audience or keyword set.
Product / App-review How is a product perceived? Pros/cons, sentiment and clustering from Amazon, app-store and retailer reviews.
Household What’s the local household context? Census / geo-demographic enrichment (income, home value, vehicles, commute) around an address or zip.
Custom A catch-all record so any conversational or agent answer (twin chat, meeting, persona) can be saved, listed and shared like a report.
Audience Plan A launch-ready targeting plan — interest ranking, ad-set / theme structure, and budget allocation across ad platforms.
Intent Planner An activatable keyword / URL / video / ASIN plan built from intent insights.
Creative Planner Campaign ideas, briefs and generated ad assets (images + copy), ready to publish.
Aggregated Research PDF An executive, McKinsey-style PDF that stitches a Behavior + Intent + Mentions report plus AI Q&A into one CMO-ready deliverable — emailed and archived.

Not every report is AI-generated: Household, Overlap, Market Finder and Contrast are deterministic vendor-API / math pipelines; only their narrative/copy layers use LLMs. The full per-report catalog — purpose, exact route → generator, and file:line evidence for all ~14 types — is kept in the internal research report (pw-docs/research/consumr-ai-research-report.md, §5).

How a report is created (the common pattern): a request pulls live data from one or more external platforms → the backend runs analysis and an LLM insight layer over it → the result is persisted as a row in the central global_run_report index → a background job builds search embeddings so the report is retrievable and can feed twins and downstream reports.

📎 Evidence

Central report registry — every report type maps to a storage table in table_name_mappingpw-enterprise/api/reports.py:1079-1092 lists explore_saved_runs→behavior, funnel→contrast, fb_receptivity→overlap, contextual_funnel_run→intent, social_report→social, market_finder_run→market, product_report→product, household_report→household, planner_runs→behavior_planner, intent_planner→intent_planner, plan_creative→creative_planner, custom_report→custom. Master cross-type index global_run_report queried at pw-enterprise/api/reports.py:485. ✅

Audience & market intelligence — Behavior generator create() pw-enterprise/api/audience_insights.py:23973 (route /create :24979); Contrast create_behaviour() pw-enterprise/api/contrast.py:2630; Overlap OverlapCreateRun pw-enterprise/api/overlap.py:1169; Household generate_report_id_func() pw-enterprise/api/household.py:38; Market Finder market_finder_run_fun() pw-enterprise/api/market_finder.py:1321. ✅

Intent & search — Intent generator create() pw-enterprise/api/intent_insights.py:11810; Intent Planner INSERT into intent_planner pw-enterprise/api/intent_planner.py:337. ✅

Social & product — Social/Mentions generate_report_id_func() pw-enterprise/api/social_insights.py:1217; Product/app-review analyze_app_func() pw-enterprise/api/product.py:3890. ✅

Activation & creative — Audience Plan CreateAudiencePlan pw-enterprise/api/planner.py:4384; Creative Planner route /create_campaign_ideas pw-enterprise/api/planner_creative.py:382; budget optimizer blueprint pw-enterprise/api/market_budget_optimiser.py:45 + audience optimizer blueprint pw-enterprise/api/market_audience_optimiser.py:66. ✅

Aggregated Research PDFcreate_research_report() pw-enterprise/api/reports.py:1848. ✅

Report → embeddings pattern — per-type embedding builders run in pw-enterprise/cron/run_reports.py (e.g. create_behavior_report_embeddings() :192), making generated reports searchable and reusable. ✅

Beyond the report engine and twins, a set of named modules package the platform for specific jobs. Each is a real capability in code — not just marketing.

  • Answer Engine. Measures how AI answer engines (ChatGPT, Gemini, Perplexity) shift consumer trust, preference and brand rank — twins re-rate a brand before and after reading an AI answer, producing a quantified impact score. Positioned to “complete AEO, not replace it” (consumr.ai-website/src/content/modules/answer-engine-influence.ts). In code it is a first-class research objective (objective_type: "aeo", name “Answer Engine Influence”, pw-enterprise/maven/research_constraints.py:1591; objective entry pw-enterprise/maven/research_inputs.py:1814, frontend type answerEngineInfluence).
  • Creative Evaluation. Instant AI-Twin reactions to ads, landing pages and assets — scored on clarity, appeal, fit and intent — so weak creative is caught “before risking a single dollar on media” (consumr.ai-website/src/content/modules/creative-assessment/index.ts:93). In code it is the creative_evaluation research objective (frontend label “Creative Tweaking”, qual pillar, pw-enterprise/maven/research_constraints.py:655).
  • Channel-based optimization. Cross-channel campaign optimization across the major ad platforms: a budget optimiser that reallocates spend across ad sets/channels by performance, and an audience optimiser that reclusters and refines targeting audiences. This is the campaign-activation layer — the twins inform it but do not buy media — detailed under Campaign planning below (pw-enterprise/api/market_budget_optimiser.py:45, pw-enterprise/api/market_audience_optimiser.py; blueprints registered at pw-enterprise/app.py:244-245).
📎 Evidence

Answer Engine — objective defined at pw-enterprise/maven/research_constraints.py:1591 ("name": "Answer Engine Influence", objective_type/mode: "aeo"); routable objective entry pw-enterprise/maven/research_inputs.py:1814 (frontend_meeting_type: "answerEngineInfluence"). Website module consumr.ai-website/src/content/modules/answer-engine-influence.ts (branded “Answer Engine Influence”). ✅

Creative Evaluationcreative_evaluation block pw-enterprise/maven/research_constraints.py:655 ("name": "Creative Tweaking (Qual)", qual pillar). Website module consumr.ai-website/src/content/modules/creative-assessment/index.ts:85,93 (branded “Creative Assessment”). ✅

Channel-based optimization — budget optimiser blueprint pw-enterprise/api/market_budget_optimiser.py:45 registered pw-enterprise/app.py:244 (/budget_optimiser); audience optimiser pw-enterprise/api/market_audience_optimiser.py registered pw-enterprise/app.py:245 (/audience_optimiser); cross-channel blueprint at pw-enterprise/app.py:248. No dedicated marketing-site module page. ✅

The reports and twins are grounded in real data pulled from many external platforms — Meta is one source among many, not the only one:

  • Advertising platforms (audiences, targeting, reach, insights): Meta / Facebook, Google Ads, TikTok, Pinterest, LinkedIn, Snapchat, Amazon Advertising.
  • Search, analytics & demographics: DataForSEO (search results, news, trends, app & product reviews), ValueSERP (search fallback), Google Analytics (Universal + GA4), and the U.S. Census Bureau (ACS demographics).
  • Warehouse & index: BigQuery (analytics warehouse) and Elasticsearch (search/index over audiences, keywords, and reports).

Everything above is actively wired into the product. A few older integrations (DV360’s live API, Twitter/X Ads, Spotify, YouTube Data) still exist in the code but are legacy or dormant.

📎 Evidence

Advertising platforms — Meta/Facebook Graph API pw-enterprise/library/facebook_package.py:75; Google Ads keyword-plan service pw-enterprise/library/google_ads_package.py:200; TikTok Business API pw-enterprise/library/tiktok_package.py:37; Pinterest audience insights pw-enterprise/library/pinterest_package.py:234; LinkedIn ad-targeting entities pw-enterprise/library/linkedin_package.py:157; Snapchat targeting insights pw-enterprise/library/snapchat_package.py:102; Amazon Advertising API pw-enterprise/api/amazon.py:1135. ✅

Search, analytics & demographics — DataForSEO SERP pw-enterprise/api/social_insights.py:259; ValueSERP pw-enterprise/library/ai_services.py:237; Google Analytics 4 pw-enterprise/library/google_analytics_4_package.py:59; U.S. Census ACS pw-enterprise/ai_twin/respondents/universe_stage_fetcher.py:310. ✅

Warehouse & index — BigQuery client pw-enterprise/api/common.py:11; Elasticsearch client pw-enterprise/library/utils.py:85. ✅

Legacy / dormant — DV360 live wrapper pw-enterprise/library/dv360_package.py imported by 0 modules (its interest taxonomy is still served from Postgres); Twitter/X Ads pw-enterprise/api/twitter.py has no blueprint registered in app.py; Spotify caller sites commented out pw-enterprise/api/audience_insights.py:23741; YouTube Data wrapper pw-enterprise/library/youtube_package.py referenced by 0 modules. ✅

A twin is assembled from three report types plus persistent memory:

Report Source What it captures
Behavior Meta audience data Demographic and psychographic profile of the cohort
Intent Search keyword data What the cohort is actively looking for
Mentions Social commentary What the cohort is saying about topics, brands, and categories

A twin represents a whole cohort of real people — not a single individual. Even though it presents as one persona (for example, “a 41-year-old male named Ethan Mitchell”), it answers on behalf of the masses, not a niche — reflecting the aggregate behavior, intent, and social signals of thousands to millions of real people, never a fabricated character.

You interact with a twin by talking to it. Users can type in a text chat or hold a live voice call with a twin; it replies in the voice of the cohort it represents and carries memory across conversations.

📎 Evidence

Behavior = Meta audience dataconsumr-ai-intro/.work/transcripts/daily-connect-1.txt:64-66 (build behavior report from Facebook lookalikes/uploaded data) + scratchpad/sdd/icp-findings.md:8-10 (behavior = demographic/psychographic from Meta) + pw-enterprise/model/models.py:688 intelligence column. ✅

Intent = search keyword dataconsumr-ai-intro/.work/transcripts/daily-connect-1.txt:74-76 (mentions and intent reports built using keywords) + pw-enterprise/api/intent_insights.py:1035-1037 (get_search_keywords_with_funnel_run pulls Google Trends). ✅

Mentions = social commentaryconsumr-ai-intro/.work/transcripts/daily-connect-1.txt:74-76 (mentions built from keywords) + pw-enterprise/model/models.py:926-936 SocialReport with mention_type column + respondent_prompt_composer.py:10 --mentions report input. ✅

Twin has persistent memorypw-enterprise/model/models.py:1374 OrgUserPersona.user_memory column + consumr-ai-intro/.work/transcripts/daily-connect-2.txt:638 (twin carries memory summary across portfolio interactions). ✅

Represents a cohort, not an individualconsumr-ai-intro/.work/transcripts/daily-connect-1.txt:134 (founder Danish Khan: “he is a representative of a cohort. He’s not the cohort itself… he would still be able to reply on behalf of the masses, not niche”). ✅

Talk to a twin — text chat and live voice call — Text chat: the twin’s persona reply is generated in pw-enterprise/api/assets/routers/conversations.py:4121 (google/gemma-4-26b-a4b-it via OpenRouter). Voice call: pw-enterprise-frontend/src/components/atoms/AitwinAudioCall.jsx — a 1,090-line WebRTC component (RTCPeerConnection :697, realtime model gpt-realtime-1.5 :737, live session to https://api.openai.com/v1/realtime/calls :809). ✅

Three report typespw-enterprise/research_setup/FLOW.md:148-156 (global_run_report.intelligence = behavior, intent, mentions). ✅

The platform supports both modes of research — quantitative at survey scale and qualitative in depth:

  • Qualitative (Twins) — conversational research you run by talking with twins (text chat or live voice call): focus groups, investigative interviews, open-ended probing. Uses full twins with depth and memory.
  • Quantitative (Respondents) — survey-scale research: brand-tracking, segmentation studies, concept testing, creative/ad testing, message prioritization, polls. Uses lighter “respondent” personas optimized for volume and consistency.

Research workflow: Research Setup → AI Twins → Workspace / Focus Groups → Insights — which in turn inform brand strategy, messaging, targeting, and creative decisions.

📎 Evidence

Qual = AI twins (focus groups, interviews)consumr-ai-intro/.work/transcripts/daily-connect-2.txt:455 (qual done by AI twins) + :592-594 (focus groups, custom, quick) + pw-enterprise/api/meetings.py:2230 objective_types incl. investigation. ✅

Qual twins carry memorypw-enterprise/ai_twin/group/main.py:575 focus_group_recommended_ai_twins + :590 query filters user_memory IS NOT NULL on user_persona. ✅

Quant = lighter respondentsconsumr-ai-intro/.work/transcripts/daily-connect-2.txt:455 (respondents are light/mini twins) + dedicated pw-enterprise/ai_twin/respondents/agents.py:1 module + pw-enterprise/api/respondents.py:22-23 separate blueprint. ✅

Quant survey typesconsumr-ai-intro/.work/transcripts/daily-connect-2.txt:467-469 names brand-track, segmentation, media-consumption, polls, concept testing + pw-enterprise/api/survey.py:2160 _build_brand_track_mapping; but transcript lists ‘media consumption’ not ‘creative/ad testing’ or ‘message prioritization’ — those two doc items are not in the cited transcript lines (creative_evaluation objective exists in meetings.py:2230 as qual). ⚠️

Research workflow stagespw-enterprise/research_setup/FLOW.md:1-9 (Research Setup creates twins) + :22-26 (segments→brief→recommendations→create-twin) + pw-enterprise/api/meetings.py:1394 ai_twin_focused_group_execute_plan_func. ✅

Insights inform marketing decisionsscratchpad/sdd/icp-findings.md:20-21 (research insights inform strategy/messaging/targeting/creative, do not run/buy campaigns). ✅

Distinct from the research flow, the backend also contains a cross-channel campaign planning and optimization layer. This integrates the major ad platforms (Google, Meta, TikTok, and others) and includes:

  • DBO (Budget Optimization) allocates spend across channels
  • AO (Audience Optimization) — audience targeting refinement

Insights from the research flow inform these campaign decisions, but the twins do not plan or buy media directly.

📎 Evidence

Cross-channel campaign layerpw-enterprise/api/market_budget_optimiser.py:4543-4549 handles facebook/tiktok/pinterest/google_ads + pw-enterprise/app.py:136-137 registers both optimiser blueprints + pw-enterprise/.env:35 tiktok_client_id key present. ✅

DBO budget optimiserpw-enterprise/api/market_budget_optimiser.py:45-46 budget_optimiser blueprint + pw-enterprise/cron/budget_optimiser_cron.py:1-7 scheduled cross-platform job. ✅

AO audience optimiserpw-enterprise/api/market_audience_optimiser.py:66-67 audience_optimiser blueprint + dedicated cron pw-enterprise/cron/audience_optimiser_cron.py exists (finder snippet text wrong but file confirmed). ✅

Twins don’t buy mediascratchpad/sdd/icp-findings.md:20-25 (research product informs marketing, does not run/buy/optimize ad campaigns; campaign layer is separate). ✅

Who it’s for (ICP — Ideal Customer Profile)

Section titled “Who it’s for (ICP — Ideal Customer Profile)”

Primary buyers: in-house brand marketing, insights, and research teams at mid-to-large consumer brands that already think in audience cohorts and segments. These teams need a faster and more honest alternative to traditional primary research, without the cost and delay.

Example industries: financial services, insurance, FMCG/retail, automotive, consumer electronics.

Geography: US-primary; India is also an active market.

Secondary audience: media agencies. SMBs can use the platform but lack the segment sophistication that makes Consumr.ai most powerful.

📎 Evidence

Primary ICPscratchpad/sdd/icp-findings.md:28-29 (in-house brand marketing/insights/research teams at mid-to-large consumer brands thinking in cohorts/segments). ✅

Faster/honest vs traditional researchconsumr-ai-intro/.work/transcripts/daily-connect-1.txt:223-228 (traditional research meets 2000-3000 people, six months, market moves on, black box). ✅

Industry verticalsscratchpad/sdd/icp-findings.md:30-32 (Amex, GEICO, Walmart, Mercedes, consumer electronics, gold loans) + consumr-ai-intro/.work/transcripts/daily-connect-2.txt:57-62 (GEICO insurance shown live). ✅

US-primary, India activescratchpad/sdd/icp-findings.md:33 + consumr-ai-intro/.work/transcripts/daily-connect-2.txt:501 (India also doing 10,000 respondents). ✅

Secondary media agencies / SMB gapscratchpad/sdd/icp-findings.md:34-35 (media agencies ‘implied, not primary’; SMBs lack segment sophistication) + transcript-2.txt:31 (SMBs lack dedicated marketing team, don’t know segments). Media agencies are inferred, not named in transcripts. ⚠️

Clients upload first-party data directly to Meta (a “walled garden”). Consumr.ai never holds or processes raw PII — the audience signals are derived from aggregated platform data, not individual records.

📎 Evidence

Privacy: upload to Meta, no raw PIIconsumr-ai-intro/.work/transcripts/daily-connect-1.txt:67-70 (don’t take first-party data, upload to Facebook, compliant) + scratchpad/sdd/icp-findings.md:16-17 + pw-enterprise/.env:39 facebook_client_id key. ✅

Term Meaning
Report A stored, searchable analysis object (audience, intent, social, market, product, plan, etc.), registered in the central global_run_report index. The product’s core unit of output.
Twin An LLM persona that represents a whole cohort of real people — not one individual — grounded in real behavioral, intent, and social signals. Users interact with it by text chat or live voice call.
Respondent A lighter twin variant used for quantitative surveys and polls.
Segment / Brief A defined audience group and the research question framing applied to it.
Focus group / meeting A structured session where twins answer research questions qualitatively.
Insight Analyzed output from a focus group: behavior patterns, intent signals, brand mentions, themes.
Portfolio The brand context a twin is evaluated against.
📎 Evidence

Report definition — central registry table_name_mapping pw-enterprise/api/reports.py:1079-1092 + master index global_run_report queried at pw-enterprise/api/reports.py:485. ✅

Twin definitionpw-enterprise/ai_twin/respondents/respondent_prompt_composer.py:57-64 (prompt grounded in behavior/intent/mentions summaries). ✅

Respondent definitionconsumr-ai-intro/.work/transcripts/daily-connect-2.txt:455 (respondents = light twins for quant) + pw-enterprise/ai_twin/respondents/respondent_matrix_step2.py exists. ✅

Segment/Brief definitionpw-enterprise/research_setup/FLOW.md:104-121 (user_segment has segment, user_brief, detailed_brief columns) + research_setup/api/routes.py:47 segment_to_detailed_brief. ✅

Focus group/meeting definitionpw-enterprise/api/meetings.py:44-45 meetings blueprint + :1394 ai_twin_focused_group_execute_plan_func. ✅

Insight definitionpw-enterprise/api/meetings.py:3120 (day-in-the-life from focus-group transcript) + :3291 (word-cloud theme analysis from transcript). ✅

Portfolio definitionpw-enterprise/model/models.py:1527-1540 PortfolioActivityLog + consumr-ai-intro/.work/transcripts/daily-connect-1.txt:146-148 (portfolio = American Express brand context twin always speaks in). ✅

Repo Stack Role
pw-enterprise Flask / Python Backend: REST APIs, background jobs, AI agent orchestration, campaign optimization.
pw-enterprise-frontend React 19 / Vite+, hosted on Cloudflare Frontend: the single-page application users interact with.

These docs cover both repos. Individual sections will call out which side of the stack is relevant.

📎 Evidence

pw-enterprise = Flask/Python backendpw-enterprise/pyproject.toml:6-10,44 (name pw-enterprise, py>=3.12, flask>=3.1.2) + pw-enterprise/app.py:250-276 registers blueprints + pw-enterprise/CLAUDE.md:5-11 (Flask, Redis+RQ, LangGraph/CrewAI). ✅

Frontend = React 19 / Vite+ on Cloudflarepw-enterprise-frontend/package.json:108 react ^19.1.0, :168 vite via @voidzero-dev/vite-plus-core, :15 wrangler pages deploy + wrangler.toml:1-5 Cloudflare Pages config. ✅

~50 cron jobspw-enterprise/CLAUDE.md:30 (~50 files) + cron/ directory has 55 files including __init__.py (~54 actual jobs); approximation holds. Doc page does not state a count. ✅

60+ blueprints (overcount)pw-enterprise/CLAUDE.md:21 claims 60+, but pw-enterprise/app.py has only 52 register_blueprint calls (grep -c). Overview.mdx does not actually state a number, so doc is safe; the CLAUDE.md figure is inflated. ⚠️

Redis + RQpw-enterprise/requirements.txt:1143 rq==2.6.1 + :1067 redis==7.1.0 (via rq, flask-sse). ✅

LangChain/LangGraph/CrewAIpw-enterprise/requirements.txt:518 langchain==1.2.7, :563 langgraph==1.0.7, :154 crewai==1.6.1. ✅