indian-fakedata

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

indian-fakedata

★ 10 Open GitHub ↗

A fast tool with no extra packages that creates realistic mock Indian profile data based on Census 2011 statistics.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Indian Fake Data Generator

A library that generates culturally accurate, statistically consistent mock Indian demographic profiles backed by **Census 2011** data.

This repository provides **two native implementations**:
1. A **Node.js / TypeScript** package (`@abhay557/indian-fakedata`)
2. A **Python** package (`indian-fakedata`)

Unlike traditional mock generators that produce impossible demographic combinations (such as a *Sikh* named *Mohammed Sharma* from *Mizoram*), this library correctly links variables together so that every generated person makes logical sense based on real-world statistical correlations.

[![NPM Version](https://img.shields.io/npm/v/@abhay557/indian-fakedata?logo=npm&color=brightgreen)](https://www.npmjs.com/package/@abhay557/indian-fakedata)
[![PyPI Version](https://img.shields.io/pypi/v/indian-fakedata?logo=pypi&color=blue)](https://pypi.org/project/indian-fakedata/)
[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/) 
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/) 
[![License](https://img.shields.io/badge/License-MIT-green.svg)](https://raw.githubusercontent.com/Abhay557/indian-fakedata/main/LICENSE)
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1VWYsjM0f6CxEi7pZ6uOa1i9Hfh7tsH8s?usp=sharing)

---

## Output Sample (one profile, `seed = 7`)

> Sample generated by the **Python implementation**. The TypeScript implementation
> is independently deterministic: the same seed is reproducible within one
> implementation, but the two runtimes draw RNG streams differently.

```json
{
  "id": "33553413-2014-4616-9361-511204427271",
  "firstName": "Pushpa",
  "lastName": "Sharma",
  "fatherName": "Santosh Sharma",
  "motherName": "Geeta Sharma",
  "spouseName": "Sanjay Sharma",
  "gender": "female",
  "age": 34,
  "dateOfBirth": "1992-06-11",
  "bloodGroup": "O+",
  "heightCm": 152.9,
  "weightKg": 65.9,
  "bmi": 28.2,
  "aadhaarNumber": "500233102039",
  "panNumber": "EKIPS1361D",
  "voterIdNumber": "MHR0314014",
  "phoneNumber": "7501311043",
  "email": "pushpasharma352@gmail.com",
  "state": "Maharashtra",
  "stateCode": "MH",
  "district": "Solapur",
  "areaType": "urban",
  "addressLine": "245/D, MG Road, Solapur",
  "locality": "MG Road",
  "pinCode": "412519",
  "religion": "Hindu",
  "caste": "Deshastha Brahmin",
  "socialCategory": "General",
  "motherTongue": "Marathi",
  "secondLanguage": "Hindi",
  "education": "secondary",
  "occupation": "agricultural_labourer",
  "employmentSector": "self_employed",
  "maritalStatus": "married",
  "annualIncomeINR": 194000,
  "monthlyExpenditureINR": 15600,
  "numberOfChildren": 1,
  "dietaryPreference": "vegetarian",
  "disability": "none",
  "isMigrant": true,
  "migrationOriginState": "Andhra Pradesh",
  "bankIFSC": "SBIN0331430",
  "bankName": "State Bank of India",
  "bankAccountNumber": "00313113041",
  "rationCardType": "APL",
  "healthInsurance": "none",
  "landOwnershipAcres": 0,
  "vehicleRegistration": "MH 02 BB 2481",
  "vehicleType": "four_wheeler",
  "hasInternetAccess": true,
  "hasSmartphone": true,
  "usesSocialMedia": true,
  "upiId": "pushpa@okicici",
  "personality": {
    "openness": 54,
    "conscientiousness": 62,
    "extraversion": 60,
    "agreeableness": 70,
    "neuroticism": 58
  },
  "personalityTraits": {
    "summary": "An outgoing, people-oriented person who is practical, disciplined and kind-hearted. They feel things deeply and care about those around them.",
    "strengths": [
      "prefers familiar routines",
      "organized and punctual",
      "compassionate and helpful"
    ],
    "weaknesses": [
      "worries about small things",
      "needs company to feel energised",
      "perfectionist, can be rigid"
    ],
    "traitLabels": [
      "practical",
      "disciplined",
      "outgoing",
      "kind-hearted",
      "sensitive"
    ],
    "communicationStyle": "polite_indirect",
    "decisionStyle": "analytical",
    "socialBehavior": "outgoing"
  },
  "politicalLeaning": "nationalist_right",
  "religiosity": "very_religious",
  "cognitiveProfile": {
    "aptitudeScore": 74,
    "numeracyScore": 68,
    "literacyScore": 75,
    "digitalLiteracyScore": 53,
    "financialLiteracyScore": 71
  },
  "interests": {
    "primarySport": "cricket",
    "petPreference": "birds",
    "entertainment": [
      "Bollywood",
      "TV Serials",
      "Cricket Matches",
      "News",
      "YouTube",
      "OTT/Netflix"
    ],
    "readingHabit": "occasional",
    "musicPreference": "Bollywood",
    "preferredSocialMedia": "WhatsApp"
  },
  "habits": {
    "tobaccoUse": "smoking",
    "alcoholUse": "none",
    "exerciseFrequency": "weekly",
    "avgSleepHours": 9.3,
    "cooksAtHome": true,
    "chronotype": "early_riser"
  },
  "educationDetails": {
    "fieldOfStudy": null,
    "institutionType": "private",
    "mediumOfInstruction": "English",
    "qualificationYear": 2008,
    "competitiveExamPercentile": null
  },
  "educationTimeline": [
    {
      "level": "primary",
      "stageName": "Primary School",
      "institutionName": "Infant Jesus, Solapur",
      "institutionType": "private",
      "boardOrUniversity": "CBSE",
      "startYear": 1997,
      "endYear": 2003,
      "status": "completed",
      "score": "69.8%"
    },
    {
      "level": "middle",
      "stageName": "Middle School",
      "institutionName": "St. Peter's, Solapur",
      "institutionType": "private",
      "boardOrUniversity": "CBSE",
      "startYear": 2003,
      "endYear": 2006,
      "status": "completed",
      "score": "86.3%"
    },
    {
      "level": "secondary",
      "stageName": "Secondary School",
      "institutionName": "St. Agnes, Solapur",
      "institutionType": "private",
      "boardOrUniversity": "CBSE",
      "startYear": 2006,
      "endYear": 2008,
      "status": "completed",
      "score": "78.3%"
    }
  ],
  "moviePreferences": {
    "genres": [
      "Comedy",
      "Romance",
      "Action"
    ],
    "favoriteLanguages": [
      "Marathi",
      "Hindi"
    ],
    "anime": true,
    "animePreferences": [
      "Shonen action"
    ],
    "favoriteAnimeTitles": [
      "Demon Slayer",
      "One Piece"
    ],
    "primaryPlatform": "ott",
    "watchFrequency": "weekly"
  },
  "culturalProfile": {
    "entrepreneurialScore": 32,
    "academicOrientation": 64,
    "artisticInclination": 41,
    "militaryTradition": 37,
    "agriculturalRootedness": 21,
    "artisanTradition": 1,
    "bureaucraticOrientation": 50,
    "socialActivism": 13,
    "communityBonding": 67,
    "migrationTendency": 24,
    "careerPreference": "business_trade",
    "familyStructure": "nuclear_family",
    "savingsOrientation": 65,
    "riskAppetite": 12
  },
  "householdSize": 1,
  "householdAssets": {
    "hasRadioTransistor": false,
    "hasTelevision": true,
    "hasComputer": true,
    "hasPhone": true,
    "hasBicycle": true,
    "hasScooter": true,
    "hasCar": true,
    "bankingService": true,
    "treatedWaterSource": true,
    "latrineFacility": true,
    "numberOfRooms": 2,
    "roofMaterial": "concrete",
    "wallMaterial": "burnt_brick",
    "cookingFuel": "lpg",
    "lightingSource": "electricity",
    "drinkingWaterSource": "tap_treated"
  },
  "probabilityMetrics": {
    "nationalReligionFreq": 0.803301791826052,
    "stateGivenReligionProb": 0.10324714506000403,
    "casteGivenContextProb": 0.04225352112676056,
    "lastNameGivenCasteProb": 0.2,
    "socialCategoryProb": 0.35211267605633797,
    "educationProb": 0.21890547263681592,
    "occupationProb": 0.18000000000000002,
    "jointProbability": 2.7617147096522784e-05
  },
  "generatedAt": "2026-08-03T21:45:13.883314",
  "seed": 7
}
```
---

## Installation

### Node.js / TypeScript
```bash
npm install @abhay557/indian-fakedata
```
*Requires **Node.js >= 18**.*

### Python
```bash
pip install indian-fakedata
```
*Requires **Python 3.8+**.*

---

## CLI Usage (Both Languages)

Both packages ship with the `indian-fakedata` CLI binary. The arguments are identical across both versions!

```bash
# Node.js
npx @abhay557/indian-fakedata [options]

# Python (or globally installed Node package)
indian-fakedata [options]
```

Run with no arguments to display the full help menu.

### Core Options

| Flag | Alias | Description | Default |
|------|-------|-------------|---------|
| `--count <n>` | `-c` | Number of profiles to generate | `100` |
| `--output <path>` | `-o` | File path to save output | stdout |
| `--format <fmt>` | `-f` | Output format: `json`, `jsonl`, `csv` | `json` |
| `--seed <value>` | `-s` | Reproducibility seed (number or string, e.g. `011`) | random |
| `--no-metrics` | | Exclude probability metrics from output | included |
| `--family` | | Generate a full family (head + spouse + parents + children + siblings) from one seed | off |
| `--help` | `-h` | Show help screen | |

### Demographic Constraints

Filter generated profiles to specific demographic slices:

| Flag | Values |
|------|--------|
| `--religion <string>` | `Hindu`, `Muslim`, `Christian`, `Sikh`, `Buddhist`, `Jain` |
| `--state <string>` | e.g. `Maharashtra`, `Tamil Nadu`, `Punjab` |
| `--gender <gender>` | `male`, `female`, `other` |
| `--caste <string>` | e.g. `Brahmin`, `Maratha`, `Jat` |
| `--socialCategory <cat>` | `SC`, `ST`, `OBC`, `General` |
| `--areaType <type>` | `urban`, `rural` |
| `--minAge <n>` | Minimum age (0–100) |
| `--maxAge <n>` | Maximum age (0–100) |
| `--education <level>` | `illiterate`, `primary`, `secondary`, `graduate`, etc. |
| `--occupation <sector>` | `cultivator`, `other_worker`, `non_worker`, etc. |
| `--maritalStatus <status>` | `never_married`, `married`, `widowed`, etc. |

### Enrichment Layers (Progressive Depth)

| Flag | Description |
|------|-------------|
| `--enrich` | Enable ALL enrichment layers (outcomes + narrative:all + persona) |
| `--outcomes` | **[Layer 2]** Add credit score, health risk, employment outcome, education attainment |
| `--bias <0-1>` | Bias dial for outcome simulation. `0.0` = pure meritocracy, `1.0` = max historical discrimination. Default: `0.3` |
| `--narrative <type>` | **[Layer 3]** Generate realistic Indian text documents. Repeat for multiple types: `loan_application`, `medical_consultation`, `school_enrollment`, `ration_card_application`, `hinglish_conversation`, `all` |
| `--persona` | **[Layer 4]** Generate LLM-ready agent persona (system prompt + full roleplay prompt, beliefs, memory seeds) |

### Quick Examples

```bash
# 1000 profiles as CSV
indian-fakedata -c 1000 -f csv -o profiles.csv

# 50K Tamil Nadu Hindus as JSONL
indian-fakedata -c 50000 -f jsonl -o tn_data.jsonl --state "Tamil Nadu" --religion Hindu

# All enrichment layers with moderate bias
indian-fakedata -c 100 --enrich --bias 0.3 -f jsonl -o enriched.jsonl

# SC community fairness audit
indian-fakedata -c 5000 --outcomes --bias 0.5 --socialCategory SC -f jsonl -o sc_bias.jsonl
```

---

## Programmatic API

### User / Family / Persona (faker-style)

Both runtimes expose ergonomic entry points built on top of `generate`:

```typescript
import { generateUser, generateUsers, generateFamily, generatePersona } from '@abhay557/indian-fakedata';

// One user — same shape as the "Output Sample" above. Seed may be a
// number (7) or string ('011'); string seeds are hashed deterministically.
const user = generateUser({ seed: 7 });

// Many users driven by a single seed
const users = generateUsers({ count: 5, seed: '011' });

// A highly educated female IT professional from Karnataka
const dev = generateUser({ highlyEducated: true, gender: 'female', constraints: { state: 'Karnataka' } });

// Full relational household from one seed — spouse, parents, children,
// siblings all share the head's state/religion/caste/surname and keep
// age-consistent relationships. Fully reproducible for the same seed.
const family = generateFamily({ seed: '011' });
family.spouse?.lastName;   // === family.head.lastName
family.children.map(c => c.age); // younger than head

// User + LLM-ready agent persona (system prompt, beliefs, memory seeds)
const { user: u, persona } = generatePersona({ seed: '011' });
persona.systemPrompt; // ready to inject into any LLM system role
persona.fullPrompt;   // complete self-contained roleplay prompt: identity,
                      // education timeline, personality traits, movie/anime
                      // preferences, habits, beliefs, behaviour rules
```

```python
from indian_fakedata import generate_user, generate_users, generate_family, generate_persona

user = generate_user(seed=7)
users = generate_users(count=5, seed="011")
dev = generate_user(highly_educated=True, gender="female", constraints={"state": "Karnataka"})
family = generate_family(seed="011")
out = generate_persona(seed="011")   # {"user": ..., "persona": ...}
out["persona"]["fullPrompt"]         # complete roleplay prompt (see above)
```

### Core Node.js / TypeScript
```typescript
import { generate, generateEnriched } from '@abhay557/indian-fakedata';

const profiles = generate({ count: 10 });
const enriched = generateEnriched({ count: 5, includeOutcomes: true });
```

### Core Python
```python
from indian_fakedata import generate, generate_enriched

profiles = generate(count=10)
enriched = generate_enriched(count=5, include_outcomes=True)
```

See **[TUTORIAL.md](./TUTORIAL.md)** for comprehensive, side-by-side code snippets including data exporting, streams, and narratives.

---

## Data Sources & Real-World Accuracy

The generator is calibrated against publicly available survey data. The
bundled distributions are **approximations derived from published reports**,
not raw census tables — actual census microdata (`team/data/*.xlsx`) is
provided for reference but is not compiled into the package at build time.

1. **Census of India 2011 (D-Series & C-Series Tables):** Reference material for religion shares, state populations, and mother tongue frequencies; distributions are hand-calibrated approximations.
2. **National Family Health Survey (NFHS-5):** Dietary preferences, BMI, blood groups, height/weight-by-age published statistics.
3. **MSME Census:** Community-level occupational sectors, vocational rates, industry divisions.
4. **UIDAI & RTO Records:** Structural syntax for Aadhaar, Voter ID, PAN, IFSC, and RTO registrations (Aadhaar uses a true Verhoeff checksum; PAN's 10th character is self-consistent but **not** the official check digit).
5. **CSDS/Lokniti Election Studies:** Political leanings and religiosity index biases.

> **Note:** All data is synthetic mock data. Names, IDs, and numbers are randomly
> generated and do not correspond to any real individuals.

---

## The 4 Data Layers

| Layer | Name | Description |
|-------|------|-------------|
| 1 | **Core Demographics** | State, gender, religion, caste, names, languages, biological markers, address |
| 2 | **Socio-Economic Outcomes** | CIBIL credit score, health risk, literacy, employment vulnerability (configurable bias) |
| 3 | **Narrative Documents** | Loan applications, OPD records, Hinglish WhatsApp chats, school admissions |
| 4 | **Agent Persona Prompts** | LLM-ready system prompts + full roleplay prompts (education timeline, personality traits, movie/anime preferences), worldview beliefs, stress responses, memory seeds |

---

## Scripts (For Contributors)

| Command | Description |
|---------|-------------|
| `npm run build` | Compile TypeScript to `dist/` |
| `npm run dev` | Run `src/index.ts` via tsx |
| `npm run cli` | Run `src/cli.ts` via tsx |
| `npm test` | Run vitest test suite |
| `npm run demo` | Run demo script |
| `npm run lint` | Type-check without emitting |

---

## For AI Agents

[`SKILL.md`](SKILL.md) teaches AI coding agents how to correctly use this
library: install commands, the full API matrix (TS/Python), CLI reference, seed
semantics, output shape, verification assertions, and common mistakes.

---

## License

indian-fakedata

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README