market-simulation 0.2.0

AI market research simulation using NVIDIA Nemotron personas and Claude Code Agents

market-simulation

AI-powered market research simulation for Korean consumers — no local LLM or API key required.

Simulate how real Korean personas respond to your product, price point, or service concept using NVIDIA Nemotron-Personas-Korea (1M demographically grounded personas, CC BY 4.0) and Claude Code's built-in agent system.

---

How it works

HuggingFace dataset          Claude Code skill
(1M Korean personas)  ──▶   filter by target segment
                      ──▶   batch into groups of 5
                      ──▶   6 parallel sub-agents (isolated context per batch)
                      ──▶   collect responses → CSV + report

Each sub-agent receives a batch of 5 persona profiles and responds in character as each person — independently, with no cross-contamination between batches. Results are saved as a CSV and a structured Markdown report.

---

Requirements

• Claude Code (any plan — uses your existing subscription, no extra API key)
• Python 3.10+

All Python dependencies are installed automatically with the package (step 1 below).

First run streams ~50k persona rows from HuggingFace — no full dataset download. Takes ~15–40s depending on connection speed.

---

Quick start

As a Claude Code skill

1. Install the package and skill (works on macOS, Linux, Windows):

pip install market-simulation
market-simulation install-skill

Then restart your Claude Code session so the skill is loaded.

3. Trigger from any Claude Code session:

서울 30대 직장인들이 월 9,900원 커피 구독 서비스에 어떻게 반응할지 시뮬해줘

Claude will ask for your target segment and question, then run the simulation.

Simulation outputs (CSV + report) are saved to output/ in your current working directory.

Programmatically

from market_simulation import load_pool, filter_pool, occupation_kw

# Load and filter personas
df = load_pool('korea', sample_n=50000)
pool = filter_pool(
    df,
    province='서울',
    age_range=(25, 39),
    occupation_keywords=occupation_kw('IT'),
)
sample = pool.sample(20, random_state=42)
print(f'{len(sample)} personas ready')

---

Simulation limits

	Value	Why
Default	20 personas	Sufficient for theme saturation
Hard cap	30 personas	6 agents × 5 personas. Returns diminish beyond this
Batch size	5 per agent	Context isolation + response quality

Simulation results are LLM-generated hypotheses, not real market data. Use for directional insight and relative comparisons (segment A vs B, price X vs Y), not absolute predictions.

---

Output

output/
├── 2026-05-02_coffee-subscription.csv       # raw responses
└── 2026-05-02_coffee-subscription.report.md # auto-generated stats report

CSV columns: id, age, sex, occupation, province, district, answer

Report includes: response rate, demographic breakdown, full response quotes, and a prompt to synthesize a .summary.md with pattern clusters and key insights.

---

Dataset

Field	Value
Source	nvidia/Nemotron-Personas-Korea
Size	~1M personas
License	CC BY 4.0 (commercial use allowed)
Grounding	Korean census data, demographic distributions
Also available	Japan, USA, France, and more

---

Disclaimer

• Simulation results are LLM-generated hypotheses, not real survey data.
• Response rates and approval ratios are inflated by LLM positive bias — trust relative comparisons within the same simulation, not absolute values.
• Persona dataset is publicly available under CC BY 4.0; cite NVIDIA accordingly.

---

Project structure

market-simulation/
├── SKILL.md               ← Claude Code skill entrypoint
├── market_simulation/
│   ├── personas.py        ← HuggingFace loader, filter, card builder
│   └── analyze.py         ← CSV → stats report generator
└── output/                ← simulation results (gitignored)

---

License

Code: MIT
Persona data: CC BY 4.0 (NVIDIA)