| name | survey |
| description | Create and run a synthetic audience research study with AudienceKit. Use when a user wants to test a product concept, message, price, ad, brand idea, or treatment comparison against a weighted audience frame. |
Synthetic Audience Survey
Use AudienceKit to turn a research brief into a structured study, run it on a sampled audience frame, and summarize directional findings.
Inputs
Extract these from the brief:
- Research objective: the decision or hypothesis being pressure-tested.
- Stimulus: product, message, ad, concept, price, or image path.
- Audience frame: prepared CSV, GSS file, or custom DataFrame.
- Segment: broad population, named segment, or explicit row-filter rule.
- Treatments: alternate framings or concepts to compare.
- Panel size: default 25 for live exploration; use 100+ only when requested.
- Backend: Gemini is the default; use OpenAI, Anthropic, or a custom backend only when requested.
Ask one clarifying question only when the core research objective or audience is ambiguous.
Study Spec
Create a JSON/YAML-compatible audiencekit.Study with:
- 3-8 questions total.
- At least one
likert item and one text item.
choice items for forced verdicts or treatment comparisons.- Neutral wording. Avoid leading language.
- Short snake_case question ids.
Use benchmarks/reference cells when interpreting a score would otherwise be ambiguous.
Run
Use the Python API first:
import audiencekit as ak
pool = ak.load_panel()
respondents = ak.sample_panel(pool, n=50, segment="broad", seed=42)
study = ak.Study.from_json("examples/my_study/study.json")
results = ak.SyntheticPanel(respondents).run_survey(study)
For a user-prepared panel:
pool = ak.load_panel("data/gss_panel.csv")
For full GSS files:
pool = ak.load_gss("path/to/gss7224_r3.dta", years=[2024])
For non-GSS datasets, create an ak.AudienceFrame and pass a custom persona template:
frame = ak.AudienceFrame(df, id_column="person_id", weight_column="survey_weight")
respondents = frame.sample(n=50, segment_name="target")
template = ak.PersonaTemplate("You are {age}, live in {region}, and buy {category}.")
results = ak.SyntheticPanel(respondents, persona_template=template).run_survey(study)
Use prompt_builder(row, study_dict) only when the default survey prompt is too generic for the research design. Preserve JSON-only output instructions and exact question ids.
Report
Summarize:
- Valid and invalid response counts.
- Mean scores and distributions for Likert items.
- Treatment effects against baseline or benchmark cells.
- Demographic or segment cuts only when they are material.
- 3-5 verbatims that explain the pattern.
Frame every result as a directional pressure test, not as a fieldwork substitute. Include limitations around model choice, prompt sensitivity, panel fit, and response-distribution compression.
