# Folkscale. — Canonical Machine-Readable Documentation

Base URL: `https://mcp.folkscale.com`
Remote MCP: `https://mcp.folkscale.com/mcp` | `https://mcp.folkscale.com`
Discovery: `https://mcp.folkscale.com/llms.txt` | `https://mcp.folkscale.com/openapi.json` | `https://mcp.folkscale.com/.well-known/api-catalog` | `https://mcp.folkscale.com/.well-known/mcp.json` | `https://mcp.folkscale.com/.well-known/openid-configuration`

---

## 1. What Folkscale Does

Folkscale runs fast, calibrated synthetic consumer market research studies building on **Semantic Similarity Rating (SSR)** (Maier et al., 2025, `arXiv:2510.08338` — whose >0.85 KS distributional match we treat as an empirical floor thanks to our deeper multi-layer psychographics, automatic anti-homogenization profile enrichment, and newer frontier models):

1. **Country-Calibrated Deep Psychographic Panels:** Each respondent is quota-sampled to national demographic distributions and assigned culturally calibrated Big Five (OCEAN) traits, Schwartz Basic Human Values, Hofstede cultural alignment, Rogers adoption segment, price sensitivity, institutional trust, media diet, and local household context.
2. **Qualitative-First Elicitation:** Each synthetic consumer responds in natural first-person prose without outputting raw numbers (preventing LLM Likert mode collapse and sycophancy).
3. **Embedding Projection onto 5-Point Likert PMF:** Responses and `m = 6` reference anchor sets (5 statements each) are embedded and projected via cosine similarity with tunable temperature `T` and smoothing `epsilon`:
   - `s_{r,i} = gamma(sigma_{r,i}, t) - min_l gamma(sigma_{l,i}, t) + epsilon`
   - `p_i(r | T, epsilon) = s_{r,i}^(1/T) / sum_k s_{k,i}^(1/T)`
   - `p_hat(r) = (1/m) * sum_i p_i(r | T, epsilon)`

---

## 2. Frictionless Agent Signup & Live MCP

### Register a Scoped Sandbox API Key (Zero Human Clicks)
```bash
curl -X POST https://mcp.folkscale.com/api/agents/register \
  -H "Content-Type: application/json" \
  -d '{"agentName": "my-product-agent", "monthlySpendCapUsd": 50}'
```
Returns a scoped `fs_sbx_...` key with unlimited free Offline Simulator runs so your agent can validate every tool schema end-to-end. Requesting a live paid study with zero balance returns a structured 1-click Stripe Checkout top-up link.

### Live Streamable HTTP MCP Endpoint (`POST https://mcp.folkscale.com/mcp`)
JSON-RPC 2.0 Streamable HTTP transport supporting `initialize`, `tools/list`, `tools/call`, `resources/list`, and `resources/read`:
- `list_countries` — List built-in and custom synthesized national population blueprints.
- `create_panel` — Generate a census-stratified panel for any country and panel size `N`.
- `estimate_study_cost` — Return deterministic study pricing before running a study.
- `run_market_study` — Run a calibrated SSR study across 1–3 concepts and return structured Likert PMFs, Top-2-Box, subgroup cross-tabs, verbatims, and Executive Brief.
- `get_study_results` — Fetch a completed study by ID or recompute distributions at custom `T` / `epsilon`.
- `synthesize_study` — Generate or refresh the Executive Research Brief for any completed study.
- `score_quote_ssr` — Project any single consumer quote onto a calibrated 5-point Likert PMF.

---

## 3. Built-In National Blueprints

| Code | Country | Currency | Statistical Basis |
| :--- | :--- | :--- | :--- |
| `US` | United States | USD ($) | U.S. Census Bureau ACS (2024) + Pew/Hofstede Cultural Benchmarks |
| `FI` | Finland | EUR (€) | Statistics Finland (Tilastokeskus 2024) + Nordic Values Survey |
| `UK` | United Kingdom | GBP (£) | ONS UK Census & Living Costs Survey (2024) |
| `DE` | Germany | EUR (€) | Destatis Mikrozensus (2024) + GfK Consumer Climate Benchmarks |
| `JP` | Japan | JPY (¥) | Statistics Bureau of Japan (e-Stat 2024) + Cabinet Office Consumer Survey |
| `BR` | Brazil | BRL (R$) | IBGE PNAD Contínua & Censo (2024) |
| `IN` | India | INR (₹) | MOSPI / NFHS-5 Urban-Rural Stratified Consumer Benchmarks |

Need another country? Call `POST /api/countries/synthesize` with `{ "countryName": "South Korea" }`.

---

## 4. Managed Production Models & Scale Presets

### LLM Models
| Model ID | Provider | Reference Cost (In / Out) | Notes |
| :--- | :--- | :--- | :--- |
| `gemini-4-hydrogen` | google | $1.50 / $7.50 per 1M | Google’s high-efficiency Gemini 4 workhorse — strong persona fidelity, cultural nuance, and rich qualitative consumer reasoning. |
| `claude-sonnet-5-5` | anthropic | $2.00 / $10.00 per 1M | Anthropic’s flagship balanced model — deeply expressive, unforced first-person consumer voices with realistic skepticism. |
| `claude-haiku-5-5` | anthropic | $0.10 / $0.50 per 1M | Ultra-affordable high-throughput Claude 5.5 model — run a 100-consumer national panel for ~$0.02 with strong SSR calibration. |
| `gemini-3.8-flash` | google | $0.35 / $1.50 per 1M | Fast, economical Gemini 3.8 model suitable for high-volume concept screening alongside Gemini 4 Hydrogen. |
| `gemini-3.5-flash-lite` | google | $0.10 / $0.40 per 1M | Lowest-cost Gemini model for very large synthetic sample sizes (N = 100–200). |
| `demo-simulator` | demo | $0.00 / $0.00 per 1M | Deterministic psychographic response simulator using each persona’s Big Five, price elasticity, cultural norms, and values so you can test the full SSR pipeline without keys. |

### Embedding Models
- `gemini-embedding-2` (google) — Google’s latest semantic embedding model ($0.10/1M tokens). Automatically normalized; ideal for multi-language & nuanced SSR cosine projection.
- `gemini-embedding-001` (google) — Text-only Gemini embedding model with explicit SEMANTIC_SIMILARITY task type optimization.
- `text-embedding-3-small` (openai) — Exact embedding model benchmarked in arXiv:2510.08338 (requires OPENAI_API_KEY).
- `local-semantic-v1` (local) — Zero-dependency local intent/sentiment semantic vector space for Demo Mode or Anthropic-only setups without a Gemini/OpenAI embedding key.

### Scale Presets
| Preset ID | Name | Description |
| :--- | :--- | :--- |
| `purchase-intent` | Purchase Intent (Paper Standard — 6 Sets) | After reading this product concept carefully, how likely would you be to buy this product for yourself or your household if it were available where you normally shop? Please explain your honest gut reaction in 2–4 sentences. |
| `value-for-money` | Price & Value-for-Money (6 Sets) | Considering the stated price and what this product offers, how do you feel about its value for money given your household budget? Share your candid reaction in 2–4 sentences. |
| `concept-uniqueness` | Concept Uniqueness & Differentiation (6 Sets) | How new, differentiated, and meaningfully better does this concept feel compared to products you already know or use? Explain your honest reaction in 2–4 sentences. |

---

## 5. Key REST + SSE Endpoints

- `GET /api/config` — Platform countries, presets, and public runtime metadata.
- `POST /api/recon` — Paste a live landing-page URL or rough pitch to auto-extract a clean consumer brief.
- `POST /api/teaser/run` — Run a 6-consumer instant homepage teaser (Turnstile + rate-limited).
- `POST /api/panels/generate` — Create a census-stratified national panel.
- `POST /api/studies/run` — Execute an SSE-streamed SSR concept study.
- `GET /api/studies/:id/pdf` — Download boardroom-ready Executive Research Brief PDF (cached in R2).
- `POST /api/studies/:id/synthesize` — Generate/refresh Executive Research Brief JSON.
- `POST /api/studies/:id/benchmark` — Attach a 5-element real human survey PMF to compute exact KS similarity.
- `POST /api/billing/checkout` — Create a Stripe Checkout session ($29 Quick Screen, $99 Full Study, $499/mo Growth, $1,499/mo Agency).
- `POST /api/agents/register` — Provision a scoped sandbox agent API key with spend guardrails.
