# SekerAI (סקר AI) – Full Technical & Scientific Specification

> Comprehensive architectural, statistical, and algorithmic specification of SekerAI, the synthetic market research SaaS platform within the Kesher Ecosystem (kesher.me).

Parent Hub: https://kesher.me
Parent Hub LLM Index: https://kesher.me/llms.txt
SekerAI Summary Index: https://seker.kesher.me/llms.txt
Canonical Domain: https://seker.kesher.me
Author: Dor Posner (https://kesher.me/#dor-posner)
Publisher: Kesher (https://kesher.me)

---

## 1. System Overview & Problem Domain
Market research in Israel has historically suffered from:
1. Long turnaround cycles: 14 to 21 business days to field and normalize panel data.
2. High financial threshold: 15,000 to 35,000 ILS for representative quantitative surveys.
3. Panel fatigue and bot spam: human survey panels suffer from disengaged clicking and automated survey completion.
4. Rigid questionnaires: once a traditional survey is closed, researchers cannot follow up with individual respondents to ask "Why did you select this option?".

SekerAI solves all four challenges:
- Turnaround: 2 to 4 minutes for 100–500 calibrated synthetic respondents.
- Cost: over 90% reduction compared to traditional polling companies.
- Rich Qualitative Depth: every response includes an unprompted `internalMonologue` explaining the respondent's authentic internal dilemma.
- Interactive Follow-up: researchers can click any persona in the dashboard and conduct an ongoing 1-on-1 interview.

---

## 2. Demographic Modeling Engine (CBS / הלשכה המרכזית לסטטיסטיקה)

The demographic engine synthesizes individuals based on empirical CBS distribution tables:

### 2.1 Distribution Matrices
- **Gender:** 49% Male, 51% Female.
- **Age Groups:**
  - 18–29 (24%): Young adults, university students, early career, IDF service veterans.
  - 30–44 (31%): Young families, mid-career professionals, housing mortgage holders.
  - 45–59 (26%): Established families, senior professionals, homeowners.
  - 60–75 (19%): Pre-retirees and retirees, grandparents, pensioners.
- **Districts & Cities:**
  - Center & Gush Dan (Tel Aviv, Rishon LeZion, Holon, Petah Tikva, Ramat Gan, Herzliya, Kfar Saba).
  - Jerusalem (Jerusalem, Beit Shemesh, Mevaseret Zion).
  - North (Nazareth, Afula, Tiberias, Karmiel, Nahariya, Kiryat Shmona).
  - Haifa (Haifa, Krayot, Hadera).
  - South (Beer Sheva, Ashdod, Ashkelon, Sderot, Eilat).
  - Judea & Samaria (Ariel, Modi'in Illit, Ma'ale Adumim, Efrat).
- **Sectors & Religiosity:**
  - Jewish Secular (חילוני): ~43%
  - Jewish Traditional (מסורתי): ~24%
  - Jewish Religious / National Religious (דתי / דתי לאומי): ~12%
  - Jewish Ultra-Orthodox (חרדי): ~11%
  - Arab & Druze (ערבי מוסלמי, ערבי נוצרי, דרוזי): ~10%
- **Income Brackets:**
  - Below Average (מתחת לממוצע): ~33%
  - Average (ממוצע, ~12,000–14,000 ILS net household): ~37%
  - Above Average (מעל הממוצע): ~30%

### 2.2 Persona Skeleton Generation (`persona-generator.ts`)
Each persona skeleton contains:
- `fullName`: Authentic Hebrew or Arabic names matching sector and generation.
- `age`, `gender`, `district`, `city`
- `sector`, `religiosity`, `incomeLevel`
- `education`: Academic, High School, Vocational, Yeshiva / Rabbinical.
- `maritalStatus`: Married, Single, Divorced, Widowed.
- `childrenCount`: Statistically correlated with religiosity and age.
- `occupation` & `employmentType`: Salaried, Self-Employed, Civil Servant, Hi-Tech, Student, Retired.
- `housingStatus`: Homeowner with mortgage, Homeowner without mortgage, Renter, Living with parents.
- `personalityTraits`: Openness, Conscientiousness, Extraversion, Agreeableness, Neuroticism, Price Sensitivity, Brand Skepticism.

---

## 3. Gemini LLM Reasoning & Prompt Architecture

### 3.1 Prompt Orchestration (`gemini-engine.ts`)
- Model selection: Google Gemini Flash (`gemini-2.5-flash` or `gemini-3.5-flash`) via `@google/genai` SDK.
- Batch Chunking: Personas are chunked into groups of 8 per single API invocation to maximize throughput and minimize latency.
- Structured Outputs: Responses are strictly enforced using JSON schemas via `responseSchema` and `Type.OBJECT`.

### 3.2 Response Schema:
```typescript
interface GeneratedPersonaAnswer {
  questionId: string;
  selectedOption: string | null;     // Single choice selection
  selectedOptions: string[] | null;  // Multiple choice selection
  numericValue: number | null;       // 1-5 or 1-10 rating scale
  openAnswerText: string | null;     // Free-text qualitative answer
  internalMonologue: string;         // First-person Hebrew stream of consciousness
}
```

### 3.3 Prompt Construction Guidelines:
1. Strict Persona Adherence: The model is instructed to adopt the exact economic, familial, and cultural mindset of the individual.
2. Hebrew Slang & Everyday Reality: Recognizes Israeli consumer terms (סופר, יוקר המחיה, מילואים, שוק העבודה, ביטוח לאומי, שכירות, משכנתה, מבצעים, וולט).
3. No Artificial Consensus: Personas exhibit sharp, realistic Israeli disagreements, skepticism towards marketing claims, and realistic trade-offs between price and quality.

---

## 4. Analytics Engine: 0ms Cross-Tabs & Segment Comparisons

The client-side engine calculates instantaneous statistical cross-tabulations without server roundtrips:
- **Pre-defined Demographic Comparison Pairs:**
  - Center vs Periphery (`מרכז וגוש דן` vs Other districts).
  - Secular vs Religious / Haredi (`חילוני` vs `דתי` / `חרדי`).
  - Below Average vs Average+ Income.
  - Women vs Men.
  - Jewish vs Arab / Druze sector.
- **Drilldown Modal (`OptionDrilldownModal.tsx`):**
  Clicking any percentage bar in a chart exposes every individual persona who voted for that choice, their demographics, and their `internalMonologue`.
- **Exporting Capabilities:**
  - Full dataset export to Microsoft Excel (`.xlsx`) via SheetJS.
  - Comma-Separated Values (`.csv`) with UTF-8 BOM encoding for seamless Excel import.
  - Executive PDF summary report via print-optimized CSS stylesheets.

---

## 5. Depth Interview Protocol (1-on-1 Persona Chat)

Endpoint: `POST /api/surveys/[id]/personas/[personaId]/chat`
- The persona's chat history is retrieved alongside its original survey responses and monologues.
- Dynamic prompt injection ensures the persona never breaks character.
- Real-time conversation allows researchers to test pricing objections, probe feature requests, and understand emotional drivers.

---

## 6. Public Research Sharing (`/share/[id]`)

SekerAI provides zero-friction public research dashboards:
- Open URL: `https://seker.kesher.me/share/{surveyId}`
- Requires no authentication or sign-up for viewers.
- Read-only protection: viewers cannot delete surveys, modify questions, or reset data batches.
- Full analytical interactivity: viewers retain 100% access to cross-tabs, monologues, option drilldowns, and 1-on-1 persona chats.

---

## 7. Kesher Ecosystem Linkage

- Parent Network: Kesher (`https://kesher.me`)
- Domain: `https://seker.kesher.me`
- Structured Knowledge Graph: Linked via `@id: https://seker.kesher.me/#app` to `isPartOf: https://kesher.me/#website` and `author: https://kesher.me/#dor-posner`.