zayef 0.2.0 → 0.2.0.1

data/README.md

@@ -3,7 +3,10 @@
 **🇲🇦 The first Ruby gem for generating authentic Moroccan data!** Perfect for testing, development, and localization with 300+ real Moroccan names, cities, companies, and cultural elements. From traditional dishes to medical specialties - everything Moroccan! 🔥
 
 [![Gem Version](https://badge.fury.io/rb/zayef.svg)](https://badge.fury.io/rb/zayef)
-[![Ruby](https://github.com/merouaneamqor/zayef/actions/workflows/ruby.yml/badge.svg)](https://github.com/merouaneamqor/zayef/actions/workflows/ruby.yml)
+[![CI](https://github.com/merouaneamqor/zayef/workflows/CI/badge.svg)](https://github.com/merouaneamqor/zayef/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> 🇲🇦 **Zayef (زايف)** - Generate authentic Moroccan data for testing, development, and localization
 
 ## ✨ What's New in v0.2.0
 
@@ -11,26 +14,39 @@
 - 🔧 **Generic helper methods** (`pick`, `random_number`, `random_code`, `weighted_pick`)
 - 📁 **External data files** for easy maintenance (JSON format)
 - ⚡ **Parameterized profiles** with age, gender, and city constraints
-- 🎲 **Weighted sampling** for realistic nationality distributions
+- 🎲 **Weighted sampling** for realistic nationality distributions (85% Moroccan)
 - 📊 **Streaming support** for large datasets (JSON/CSV)
 - 🔄 **Cached data loading** for optimal performance
 - 🏗️ **Modern Ruby** with keyword arguments and safe navigation
 
-## Installation
+## 📦 Installation
 
+### Option 1: Bundler (Recommended)
 Add this line to your application's Gemfile:
 
 ```ruby
 gem 'zayef'
 ```
 
-And then execute:
+Then execute:
 
-    $ bundle install
+```bash
+bundle install
+```
 
-Or install it yourself as:
+### Option 2: RubyGems
+Install it yourself as:
 
-    $ gem install zayef
+```bash
+gem install zayef
+```
+
+### Option 3: Manual Installation
+```bash
+git clone https://github.com/merouaneamqor/zayef.git
+cd zayef
+bundle install
+```
 
 ## 🚀 Quick Start
 
@@ -46,22 +62,21 @@ Zayef.name                    # => "Youssef Alaoui"
 Zayef.first_name              # => "Fatima"
 Zayef.last_name               # => "Bennani"
 
-# Generate email
-Zayef.email                   # => "ayoub.kabbaj@gmail.com"
-Zayef.email(first_name: "Ahmed", last_name: "El Fassi")  # => "ahmed.el_fassi@yahoo.fr"
+# Generate email with authentic Moroccan domains
+Zayef.email                   # => "ayoub.kabbaj@menara.ma"
+Zayef.email(first_name: "Ahmed", last_name: "El Fassi")  # => "ahmed.el_fassi@iam.ma"
 
 # Generate phone number (Moroccan format)
-Zayef.phone                   # => "0612345678"
+Zayef.phone                   # => "0612345678" or "0712345678"
 
-# Generate address
+# Generate address with real Moroccan streets and cities
 Zayef.city                    # => "Casablanca"
 Zayef.address                 # => "123, Av. Hassan II, Rabat"
 
-# Generate Moroccan-specific data
-Zayef.cni_number             # => "AB123456"
-Zayef.bank_account           # => "MA123456789012345678"
+# Generate Moroccan-specific identifiers
+Zayef.cni_number             # => "AB123456" (Carte Nationale d'Identité)
+Zayef.bank_account           # => "MA123456789012345678" (IBAN format)
 Zayef.postal_code            # => "20000"
-Zayef.company_name           # => "Groupe Maroc"
 Zayef.region                 # => "Casablanca-Settat"
 Zayef.university             # => "Université Mohammed V de Rabat"
 Zayef.neighborhood           # => "Medina"
@@ -79,30 +94,41 @@ Zayef.newspaper              # => "Le Matin"
 Zayef.festival               # => "Festival de Marrakech"
 ```
 
-### ⚡ v0.2.0 Advanced Features
+## 🎯 v0.2.0 Advanced Features
+
+### Parameterized Profile Generation
+
+Generate profiles with specific constraints for more realistic data:
 
-#### Parameterized Profile Generation
 ```ruby
-# Generate profiles with specific constraints
+# Generate profiles with age, gender, and city constraints
 profile = Zayef::Generator.profile(age_min: 25, age_max: 35, city: "Casablanca", gender: "Female")
 business = Zayef::Generator.business_profile(city: "Rabat")
 medical = Zayef::Generator.medical_profile(age_min: 30, age_max: 50)
 cultural = Zayef::Generator.cultural_profile(city: "Fès")
 ```
 
-#### Bulk Data Generation
+### Bulk Data Generation & Export
+
+Generate multiple records efficiently:
+
 ```ruby
-# Generate multiple profiles
+# Generate multiple profiles with constraints
 profiles = Zayef::Generator.bulk_data(100, 'personal', city: "Marrakech")
 
-# Export to JSON
+# Export to JSON for API testing
 json_data = Zayef::Generator.export_to_json(50, 'medical')
+puts json_data
 
-# Export to CSV
+# Export to CSV for data analysis
 csv_data = Zayef::Generator.export_to_csv(200, 'business')
+puts csv_data
 ```
 
-#### Streaming for Large Datasets
+### Streaming for Large Datasets
+
+Handle thousands of records without memory issues:
+
 ```ruby
 # Generate 10,000 records without loading all in memory
 File.open('large_dataset.json', 'w') do |file|
@@ -110,380 +136,286 @@ File.open('large_dataset.json', 'w') do |file|
     file.write(chunk)
   end
 end
+
+# Stream CSV for data processing pipelines
+Zayef::Generator.stream_csv(50000, 'business') do |line|
+  # Process each line individually
+  puts line
+end
 ```
 
-#### Generic Helper Methods
+### Generic Helper Methods
+
+Use DRY principle with powerful generic helpers:
+
 ```ruby
 # Instead of repetitive .sample calls
 Zayef::Generator.pick(['option1', 'option2', 'option3'])
 
-# Consistent number generation
+# Consistent number generation with constraints
 Zayef::Generator.random_number(min: 18, max: 80)
 
 # Pattern-based code generation
-Zayef::Generator.random_code(format: 'AA######')  # CNI format
-Zayef::Generator.random_code(format: 'MA##################')  # IBAN format
+Zayef::Generator.random_code(format: 'AA######')  # CNI format: "AB123456"
+Zayef::Generator.random_code(format: 'MA##################')  # IBAN: "MA123456789012345678"
 
 # Weighted sampling for realistic distributions
 Zayef::Generator.weighted_pick({
-  "Moroccan" => 85,
-  "French" => 5,
-  "Algerian" => 3,
-  "Other" => 7
+  "Moroccan" => 85,    # 85% probability
+  "French" => 5,       # 5% probability
+  "Algerian" => 3,     # 3% probability
+  "Other" => 7         # 7% probability
 })
 ```
 
-### 🆕 NEW: Personal Data Generation
+### Data Management & Customization
 
-```ruby
-# Personal attributes
-Zayef.age                     # => 34
-Zayef.gender                  # => "Male"
-Zayef.marital_status          # => "Marié"
-Zayef.blood_type              # => "A+"
-Zayef.height                  # => 175
-Zayef.weight                  # => 70
-Zayef.eye_color               # => "Marron"
-Zayef.hair_color              # => "Noir"
-Zayef.religion                # => "Musulman"
-Zayef.nationality             # => "Marocaine"
-Zayef.language                # => "Français"
-Zayef.education_level         # => "Licence"
-Zayef.income_range            # => "10000-15000 MAD"
-Zayef.birth_date              # => #<Date: 1989-03-15>
-```
-
-### 🆕 NEW: Business & Professional Data
+Access and manage the underlying data:
 
 ```ruby
-# Business information
-Zayef.industry                # => "Technologie"
-Zayef.job_title               # => "Développeur"
-Zayef.company_size            # => "51-200 employés"
-Zayef.work_experience         # => 8
-Zayef.salary                  # => 15000
-Zayef.work_schedule           # => "CDI"
-Zayef.business_type           # => "SARL"
-Zayef.tax_id                  # => "RC123456"
-Zayef.trade_register          # => "TR789012"
-```
+# Direct access to data sources
+cities = Zayef.data_loader.cities                    # Array of Moroccan cities
+names = Zayef.data_loader.first_names('male')       # Male first names
+banks = Zayef.data_loader.banks                      # Moroccan banks
 
-### 🆕 NEW: Cultural & Lifestyle Data
+# Reload data cache (useful after custom modifications)
+Zayef.reload_data!
 
-```ruby
-# Lifestyle and preferences
-Zayef.hobby                   # => "Football"
-Zayef.sport                   # => "Natation"
-Zayef.music_genre             # => "Chaabi"
-Zayef.movie_genre             # => "Comédie"
-Zayef.social_media            # => "Instagram"
-Zayef.transportation          # => "Voiture personnelle"
-Zayef.pet                     # => "Chat"
-Zayef.favorite_color          # => "Bleu"
+# Load custom data
+custom_data = Zayef::DataLoader.load_json('path/to/custom_data.json')
 ```
 
-### 🆕 NEW: Geographic Data
-
+## 📊 Data Coverage
+
+Zayef provides authentic Moroccan data across multiple categories:
+
+### 🇲🇦 Geographic Data
+- **91 Moroccan cities** (from Casablanca to small towns)
+- **12 administrative regions** (Casablanca-Settat, Rabat-Salé-Kénitra, etc.)
+- **Districts by city** for consistency (e.g., Casablanca-Anfa, Rabat-Agdal)
+- **Authentic street names** (Av. Hassan II, Rue Mohammed V, etc.)
+- **Real postal codes** (5-digit format)
+
+### 👥 Personal Data
+- **67 male first names** + **98 female first names** = **165 total names**
+- **67 authentic last names** (Bennani, Alaoui, El Fassi, etc.)
+- **Gender-specific name generation** with realistic distributions
+- **Age ranges** with birth date calculation
+- **Personal attributes** (height, weight, blood type, etc.)
+
+### 🏢 Business & Professional Data
+- **Major Moroccan banks** (Attijariwafa Bank, Banque Populaire, etc.)
+- **Industry categories** (Technology, Healthcare, Tourism, etc.)
+- **Company size classifications** (1-10 to 1000+ employees)
+- **Job titles and professions** (Médecin, Ingénieur, etc.)
+- **Business types** (SARL, SA, Auto-entrepreneur, etc.)
+
+### 🏥 Medical Data (Perfect for DabaDoc!)
+- **25 medical specialties** (Médecine générale, Cardiologie, etc.)
+- **Complete medical profiles** with consistent data
+- **Emergency contacts** and insurance information
+- **Realistic age distributions** for different medical contexts
+
+### 🎭 Cultural Data
+- **Traditional dishes** (Couscous, Tagine, Pastilla, etc.)
+- **Moroccan spices** (Ras-el-hanout, Safran, Cumin, etc.)
+- **Famous souks and markets** (Souk Semmarine, Souk El Attarine, etc.)
+- **Restaurants and cafés** (Café Clock, Le Jardin, etc.)
+- **Hotels and riads** (Riad Kniza, Hotel Sahrai, etc.)
+- **Mosques** (Hassan II, Koutoubia, Al Quaraouiyine, etc.)
+- **Universities** (Mohammed V, Hassan II, Cadi Ayyad, etc.)
+- **Festivals** (Mawazine, Jazzablanca, Festival de Marrakech, etc.)
+
+### 📱 Modern Data
+- **Social media platforms** popular in Morocco
+- **Transportation methods** (Taxi, Bus, Train, etc.)
+- **Hobbies and sports** (Football, Basketball, etc.)
+- **Music genres** (Chaabi, Gnawa, Rai, etc.)
+
+## 🔧 Usage Examples
+
+### Basic Usage
 ```ruby
-# Location and geography
-Zayef.province                # => "Casablanca"
-Zayef.district                # => "Casablanca-Anfa"
-Zayef.district(city: 'Rabat') # => "Rabat-Hassan"
-Zayef.landmark                # => "Mosquée Hassan II"
-Zayef.climate                 # => "Méditerranéen"
-Zayef.timezone                # => "GMT+1"
-Zayef.currency                # => "MAD (Dirham Marocain)"
-```
-
-### 🆕 NEW: Complete Profile Generation
+require 'zayef'
 
-```ruby
-# Generate complete profiles
-personal_profile = Zayef.profile
-# => {
-#   name: "Youssef Alaoui",
-#   age: 34,
-#   gender: "Male",
-#   email: "youssef.alaoui@gmail.com",
-#   phone: "0612345678",
-#   city: "Casablanca",
-#   region: "Casablanca-Settat",
-#   profession: "Ingénieur",
-#   education_level: "Licence",
-#   income_range: "10000-15000 MAD",
-#   hobby: "Football",
-#   # ... and more
-# }
-
-# Medical profile (perfect for DabaDoc)
-medical_profile = Zayef.medical_profile
-# => {
-#   patient_name: "Fatima Bennani",
-#   age: 28,
-#   gender: "Female",
-#   blood_type: "A+",
-#   height: 165,
-#   weight: 60,
-#   medical_specialty: "Pédiatrie",
-#   doctor_name: "Dr. Ahmed El Fassi",
-#   clinic_address: "123, Av. Hassan II, Rabat",
-#   # ... and more
-# }
-
-# Business profile
-business_profile = Zayef.business_profile
-# => {
-#   company_name: "Groupe Maroc",
-#   industry: "Technologie",
-#   company_size: "51-200 employés",
-#   business_type: "SARL",
-#   tax_id: "RC123456",
-#   # ... and more
-# }
-
-# Cultural profile
-cultural_profile = Zayef.cultural_profile
-# => {
-#   name: "Amina Chakir",
-#   city: "Marrakech",
-#   traditional_dish: "Couscous",
-#   music_genre: "Gnawa",
-#   festival: "Festival de Marrakech",
-#   # ... and more
-# }
-```
+# Generate a full name
+Zayef.name                    # => "Youssef Alaoui"
 
-### 🆕 NEW: Bulk Data & Export Features
+# Generate individual components
+Zayef.first_name              # => "Fatima"
+Zayef.last_name               # => "Bennani"
 
-```ruby
-# Generate multiple records
-profiles = Zayef.bulk_data(10, 'personal')
-# => Array of 10 personal profiles
+# Generate email with authentic Moroccan domains
+Zayef.email                   # => "ayoub.kabbaj@menara.ma"
+Zayef.email(first_name: "Ahmed", last_name: "El Fassi")  # => "ahmed.el_fassi@iam.ma"
 
-# Export to JSON
-json_data = Zayef.export_to_json(5, 'medical')
-# => JSON string with 5 medical profiles
+# Generate phone number (Moroccan format)
+Zayef.phone                   # => "0612345678" or "0712345678"
 
-# Export to CSV
-csv_data = Zayef.export_to_csv(20, 'business')
-# => CSV string with 20 business profiles
+# Generate address with real Moroccan streets and cities
+Zayef.city                    # => "Casablanca"
+Zayef.address                 # => "123, Av. Hassan II, Rabat"
 
-# Random data generation
-random_data = Zayef.random_data('cultural')
-# => Random cultural profile
+# Generate Moroccan-specific identifiers
+Zayef.cni_number             # => "AB123456" (Carte Nationale d'Identité)
+Zayef.bank_account           # => "MA123456789012345678" (IBAN format)
+Zayef.postal_code            # => "20000"
+Zayef.region                 # => "Casablanca-Settat"
+Zayef.university             # => "Université Mohammed V de Rabat"
+Zayef.neighborhood           # => "Medina"
+Zayef.medical_specialty      # => "Médecine générale"
+Zayef.profession             # => "Médecin"
+Zayef.traditional_dish       # => "Couscous"
+Zayef.spice                  # => "Ras-el-hanout"
+Zayef.souk                   # => "Souk Semmarine"
+Zayef.bank                   # => "Attijariwafa Bank"
+Zayef.restaurant             # => "Café Clock"
+Zayef.hotel                  # => "Riad Kniza"
+Zayef.mosque                 # => "Mosquée Hassan II"
+Zayef.school                 # => "Lycée Descartes"
+Zayef.newspaper              # => "Le Matin"
+Zayef.festival               # => "Festival de Marrakech"
 ```
 
-## Features
-
-### 🎯 **Personal Information**
-- 🏠 **Moroccan Names**: 80+ authentic first names (masculin & féminin) + 50+ family names
-- 📧 **Email Generation**: Realistic emails with Moroccan domains (menara.ma, iam.ma, orange.ma)
-- 📱 **Phone Numbers**: Moroccan mobile format (06/07 prefixes)
-- 🏙️ **Cities & Addresses**: 50+ real Moroccan cities + authentic street names
-- 🏡 **Neighborhoods**: Famous districts (Medina, Gueliz, Maarif, etc.)
-- 🆔 **CNI Numbers**: Moroccan ID format (2 letters + 6 digits)
-- 🏦 **Bank Accounts**: Moroccan format with MA prefix
-- 📮 **Postal Codes**: 5-digit Moroccan postal codes
-
-### 🆕 **Enhanced Personal Data**
-- 👤 **Demographics**: Age, gender, marital status, nationality, religion
-- 🩸 **Medical Info**: Blood type, height, weight, eye/hair color
-- 🎓 **Education**: Education levels from primary to doctorate
-- 💰 **Financial**: Income ranges in Moroccan Dirhams
-- 🌍 **Languages**: Languages spoken in Morocco
-- 📅 **Dates**: Birth dates with realistic age ranges
-
-### 🏢 **Professional & Business**
-- 👨‍⚕️ **Medical Specialties**: 25+ Moroccan medical specialties (DabaDoc integration)
-- 👔 **Professions**: Common Moroccan professions (médecin, ingénieur, etc.)
-- 🏢 **Company Names**: Authentic Moroccan business naming patterns
-- 🏦 **Banks**: All major Moroccan banks (Attijariwafa, BCP, BMCI, etc.)
-- 📰 **Newspapers**: Moroccan media outlets (Le Matin, L'Économiste, etc.)
-
-### 🆕 **Enhanced Business Data**
-- 🏭 **Industries**: 16+ Moroccan industries (Agriculture, Technology, Tourism, etc.)
-- 💼 **Job Titles**: 18+ common job titles and positions
-- 📊 **Company Info**: Company sizes, business types (SARL, SA, etc.)
-- 💼 **Work Details**: Work experience, salary ranges, work schedules
-- 🆔 **Legal IDs**: Tax IDs, trade register numbers
-- 📈 **Professional**: Career progression and employment data
-
-### 🎓 **Education & Culture**
-- 🗺️ **Regions**: All 12 Moroccan administrative regions
-- 🎓 **Universities**: 12+ major Moroccan universities with full names
-- 🏫 **Schools**: Famous Moroccan schools and lycées
-- 🎭 **Festivals**: Major Moroccan cultural festivals
-- 🕌 **Mosques**: Famous Moroccan mosques (Hassan II, Koutoubia, etc.)
-
-### 🆕 **Enhanced Cultural & Lifestyle**
-- 🍲 **Traditional Dishes**: Famous Moroccan cuisine (couscous, tagine, pastilla, etc.)
-- 🌶️ **Spices**: Moroccan spices and ingredients (ras-el-hanout, safran, etc.)
-- 🏪 **Souks**: Traditional Moroccan markets (Souk Semmarine, Bahia, etc.)
-- ☕ **Cafés/Restaurants**: Famous Moroccan cafés and restaurants
-- 🏨 **Hotels/Riads**: Moroccan hotels and traditional riads
-- ⚽ **Sports & Hobbies**: 20+ sports and recreational activities
-- 🎵 **Entertainment**: Music genres, movie preferences, social media
-- 🚗 **Transportation**: Common transportation methods in Morocco
-- 🐾 **Pets**: Popular pets and animals
-- 🎨 **Preferences**: Favorite colors and personal tastes
-
-### 🆕 **Geographic & Location Data**
-- 🗺️ **Provinces**: 40+ Moroccan provinces and administrative divisions
-- 🏘️ **Districts**: Smart district generation with city-specific districts
-- 🏛️ **Landmarks**: 25+ famous Moroccan landmarks and tourist sites
-- 🌤️ **Climate**: 7 different climate types across Morocco
-- ⏰ **Timezone**: Moroccan timezone information
-- 💱 **Currency**: Moroccan Dirham information
-
-### 🆕 **Profile Generation & Utilities**
-- 👤 **Complete Profiles**: Personal, business, medical, and cultural profiles
-- 📊 **Bulk Generation**: Generate multiple records at once
-- 📤 **Export Features**: Export to JSON and CSV formats
-- 🎲 **Random Data**: Category-based random data generation
-- 🏥 **Medical Profiles**: Specialized profiles for DabaDoc integration
-- 🏢 **Business Profiles**: Complete business information packages
-
-### 📊 **Enhanced Statistics**
-- **Total Data Points**: 500+ authentic Moroccan entries
-- **Categories**: 50+ different data types
-- **Profile Types**: 4 complete profile generators
-- **Export Formats**: JSON and CSV support
-- **100% Moroccan**: Everything is authentically Moroccan
-- **No Duplicates**: All data is unique and varied
-- **DabaDoc Ready**: Perfect for medical system integration
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-### 🧪 Testing
-
-Zayef has comprehensive test coverage with 69 RSpec tests covering all functionality.
-
-```bash
-# Run all tests
-bundle exec rspec
-
-# Run tests with coverage report
-COVERAGE=true bundle exec rspec
-
-# Run specific test file
-bundle exec rspec spec/zayef/generator_spec.rb
+### Advanced Usage
 
-# Run tests with documentation format
-bundle exec rspec --format documentation
+#### Parameterized Profile Generation
+```ruby
+# Generate profiles with specific constraints for more realistic data
+profile = Zayef::Generator.profile(age_min: 25, age_max: 35, city: "Casablanca", gender: "Female")
+business = Zayef::Generator.business_profile(city: "Rabat")
+medical = Zayef::Generator.medical_profile(age_min: 30, age_max: 50)
+cultural = Zayef::Generator.cultural_profile(city: "Fès")
 ```
 
-### Test Coverage
-
-- ✅ **Core Generators**: Names, emails, phones, addresses, IDs
-- ✅ **Moroccan Data**: Regions, universities, neighborhoods, medical specialties
-- ✅ **Cultural Elements**: Traditional dishes, spices, souks, festivals
-- ✅ **Business Data**: Banks, companies, newspapers, schools
-- ✅ **Integration Tests**: End-to-end functionality testing
-- ✅ **Error Handling**: Edge cases and validation
-
-**Current Coverage**: 90%+ with comprehensive test suite
-
-### 📝 Automated Changelog
-
-Zayef uses [git-cliff](https://github.com/orhun/git-cliff) for automated changelog generation based on conventional commits.
-
-#### Installation
-
-Install git-cliff:
-```bash
-# Using cargo (recommended)
-cargo install git-cliff
+#### Bulk Data Generation & Export
+```ruby
+# Generate multiple profiles with constraints
+profiles = Zayef::Generator.bulk_data(100, 'personal', city: "Marrakech")
 
-# Or using homebrew (macOS)
-brew install git-cliff
+# Export to JSON for API testing
+json_data = Zayef::Generator.export_to_json(50, 'medical')
+puts json_data
 
-# Or download from GitHub releases
+# Export to CSV for data analysis
+csv_data = Zayef::Generator.export_to_csv(200, 'business')
+puts csv_data
 ```
 
-#### Usage
-
-```bash
-# Generate full changelog
-./bin/generate-changelog
-
-# Generate changelog for unreleased changes only
-./bin/generate-changelog --unreleased
-
-# Generate changelog for latest version
-./bin/generate-changelog --latest
-
-# Generate changelog up to specific tag
-./bin/generate-changelog --tag v1.0.0
+#### Streaming for Large Datasets
+```ruby
+# Generate 10,000 records without loading all in memory
+File.open('large_dataset.json', 'w') do |file|
+  Zayef::Generator.stream_json(10000, 'personal') do |chunk|
+    file.write(chunk)
+  end
+end
 
-# Check if git-cliff is available
-rake changelog:check
+# Stream CSV for data processing pipelines
+Zayef::Generator.stream_csv(50000, 'business') do |line|
+  # Process each line individually
+  puts line
+end
 ```
 
-#### Conventional Commits
+#### Generic Helper Methods
+```ruby
+# Instead of repetitive .sample calls
+Zayef::Generator.pick(['option1', 'option2', 'option3'])
 
-Use conventional commit format for better changelog organization:
+# Consistent number generation with constraints
+Zayef::Generator.random_number(min: 18, max: 80)
 
-```bash
-# Features
-git commit -m "feat: add Moroccan phone number generation"
+# Pattern-based code generation
+Zayef::Generator.random_code(format: 'AA######')  # CNI format: "AB123456"
+Zayef::Generator.random_code(format: 'MA##################')  # IBAN: "MA123456789012345678"
 
-# Bug fixes
-git commit -m "fix: correct CNI number format"
+# Weighted sampling for realistic distributions
+Zayef::Generator.weighted_pick({
+  "Moroccan" => 85,    # 85% probability
+  "French" => 5,       # 5% probability
+  "Algerian" => 3,     # 3% probability
+  "Other" => 7         # 7% probability
+})
+```
 
-# Documentation
-git commit -m "docs: update README with new examples"
+## 🎯 Perfect for DabaDoc & Moroccan Apps
 
-# Breaking changes
-git commit -m "feat!: change API interface (breaking change)"
+Zayef is specifically designed for Moroccan healthcare and business applications:
 
-# With scope
-git commit -m "feat(generator): add support for traditional dishes"
+```ruby
+# Generate realistic patient profiles
+patient = Zayef::Generator.medical_profile(age_min: 25, age_max: 65)
+puts "Patient: #{patient[:patient_name]}"
+puts "Age: #{patient[:age]}"
+puts "Specialty: #{patient[:medical_specialty]}"
+puts "Emergency Contact: #{patient[:emergency_contact]}"
+
+# Generate doctor profiles
+doctor = Zayef::Generator.medical_profile(age_min: 30, age_max: 70)
+puts "Doctor: #{doctor[:doctor_name]}"
+puts "Specialty: #{doctor[:medical_specialty]}"
+puts "Clinic: #{doctor[:clinic_address]}"
+
+# Generate realistic test data for Moroccan healthcare systems
+patients = Zayef::Generator.bulk_data(1000, 'medical', city: "Casablanca")
+appointments_json = Zayef::Generator.export_to_json(500, 'medical')
 ```
 
-### 🚀 Release Process
+## 🌟 Key Features
 
-Zayef includes automated release tasks:
+- **🇲🇦 Authentic Moroccan Data**: Real names, cities, companies, and cultural elements
+- **⚡ High Performance**: Cached data loading and streaming support for large datasets
+- **🎯 Parameterized Generation**: Age, gender, city, and other constraints
+- **📊 Multiple Export Formats**: JSON, CSV, and streaming support
+- **🔧 DRY Principle**: Generic helper methods eliminate code duplication
+- **🎲 Realistic Distributions**: Weighted sampling for authentic data
+- **🏥 DabaDoc Ready**: Perfect for Moroccan healthcare applications
+- **📱 Modern Data**: Social media, transportation, hobbies, and more
+- **🛠️ Easy Customization**: External JSON files for data modification
+- **💎 Modern Ruby**: Keyword arguments, safe navigation, and best practices
 
-```bash
-# Prepare release (generate changelog, bump version)
-rake release:prepare
+## 📈 Performance & Scalability
 
-# Publish to RubyGems.org
-rake release:publish
+Zayef is optimized for both small and large-scale data generation:
 
-# Full release process
-rake release:full
-```
+- **Memory Efficient**: Streaming support for datasets with millions of records
+- **Fast Generation**: Cached data loading for optimal performance
+- **Bulk Operations**: Generate hundreds of profiles with consistent constraints
+- **Export Ready**: JSON and CSV export for integration with other systems
 
-### 📋 Development Tasks
+## 🤝 Contributing
 
-```bash
-# Run all quality checks
-rake
+We welcome contributions! Please see our [Contributing Guide](https://github.com/merouaneamqor/zayef/blob/main/CONTRIBUTING.md) for details.
 
-# Generate documentation
-rake dev:docs
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Add your data to the appropriate JSON file in `data/`
+4. Update the DataLoader if needed
+5. Add tests and update documentation
+6. Commit your changes (`git commit -m 'Add amazing feature'`)
+7. Push to the branch (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
 
-# Create conventional commit interactively
-rake git:commit
+## 📄 License
 
-# Check changelog generation
-rake changelog:check
-```
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
-## Contributing
+## 🙏 Acknowledgments
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/amqor/zayef.
+- **Moroccan Community** for providing authentic cultural data
+- **Ruby Community** for the excellent tooling and ecosystem
+- **DabaDoc** for inspiring the medical data features
+- **All contributors** who help make Zayef better
 
-### 📝 Contributing Guidelines
+## 🔗 Links
 
-1. **Use Conventional Commits**: Follow the conventional commit format for automatic changelog generation
-2. **Add Tests**: Include tests for new features
-3. **Update Documentation**: Keep README and inline documentation up to date
-4. **Follow Ruby Style**: Use consistent Ruby coding style
+- **📚 Documentation**: https://github.com/merouaneamqor/zayef
+- **💎 RubyGems**: https://rubygems.org/gems/zayef
+- **🐛 Bug Reports**: https://github.com/merouaneamqor/zayef/issues
+- **🚀 Source Code**: https://github.com/merouaneamqor/zayef
+- **📝 Changelog**: https://github.com/merouaneamqor/zayef/blob/main/CHANGELOG.md
 
-## License
+---
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+**Made with ❤️ in Morocco** 🇲🇦 | **Built for the world** 🌍