README.md

---
title: Voice Assistant - Multi-language Division Matching & Contact Search
emoji: 🎙️
colorFrom: purple
colorTo: blue
sdk: gradio
sdk_version: 4.0.0
app_file: app.py
pinned: false
license: mit
---

# 🎙️ Voice Assistant Demo

A powerful multi-language voice assistant that helps users find divisions and contacts within an organization using natural language queries.

## 🌟 Features

### 🗣️ Multi-language Voice Input
- **99+ languages** supported (auto-detected)
- Automatic speech-to-text using OpenAI Whisper
- Arabic-to-English translation for seamless processing
- Works with various audio formats

### 🎯 Smart Division Matching
- Semantic search using sentence embeddings
- Confidence-based routing with intelligent thresholds
- Department-level expansion (searches all divisions in a department)
- Fast matching (~50ms) using `all-MiniLM-L6-v2`

### 👤 Name Extraction
- Extracts person names from queries using GLiNER
- Supports English and Arabic names
- Zero-shot NER for robust extraction

### 📞 Contact Search
- 500+ contacts across 23 departments and 67 divisions
- Intelligent matching combining name and division
- Confidence scoring with match reasoning
- Fuzzy name matching for typos and variations

## 🚀 How to Use

### Division Matching (Text)
Find the right division for your query:
```
"I need help from IT Security"
"Find someone in Finance"
"Connect me to Human Resources"
```

### Division Matching (Voice)
Speak your query in any language - it will be transcribed and processed automatically.

### Contact Search (Text)
Search for specific people or teams:
```
"Find Dima in Information Technology"
"Ahmed Al-Malek"
"I need to talk to someone in Legal"
```

### Contact Search (Voice)
Speak your contact search query in any language.

## 📊 Example Queries

### Department-Level Queries
These queries search across ALL divisions in a department:
- ✅ "Find someone in Information Technology" → Searches 8 IT divisions
- ✅ "I need help from Finance" → Searches all Finance divisions
- ✅ "Connect me to Human Resources" → Searches all HR divisions

### Division-Level Queries
These match specific divisions:
- ✅ "Find Ahmed in App Dev" → Applications Development & Integrations
- ✅ "I need help from IT Security" → IT Security Implementation & Operations
- ✅ "Connect me to Legal" → Legal divisions

### Name-Only Queries
- ✅ "Find Dima" → Searches all contacts named Dima
- ✅ "Ahmed Al-Malek" → Exact name match
- ✅ "I need to talk to Rashed" → Fuzzy name matching

### Combined Queries (Name + Department/Division)
Priority given to division accuracy:
- ✅ "Find Dima in Information Technology" → Perfect match (confidence: 1.00)
- ✅ "Find Ahmed in App Dev" → Shows App Dev team members

## 🔧 Technical Details

### Models Used
- **Embeddings**: `sentence-transformers/all-MiniLM-L6-v2` - Fast, lightweight semantic search
- **Name Extraction**: `urchade/gliner_small-v2.1` - Zero-shot NER for person names
- **Speech-to-Text**: `openai/whisper-base` - Optimized for CPU with good accuracy

### Confidence Scoring

| Score | Meaning | Example |
|-------|---------|---------|
| **1.00** | Perfect match (name + division) | Dima in IT |
| **0.95** | Exact name match | Ahmed Al-Malek |
| **0.66** | Strong division match | People in requested division |
| **0.59** | Good division match | Close division match |
| **< 0.30** | Low confidence | Wrong division penalty |

### Match Reasons
- `name_and_division_match` - Both name AND division match ✅
- `division_match` - Division/department matches (no name match)
- `exact_name_match` - Exact name match (100%)
- `fuzzy_name_match` - Partial name match (75%+)
- `name_match_wrong_division` - Name matches but WRONG division ⚠️

## 📦 Database Stats
- **500 contacts** across the organization
- **23 departments** (Information Technology, Finance, HR, etc.)
- **67 divisions** (specific teams and units)
- **Multi-language support** (English + Arabic names)

## 🌍 Supported Languages

The voice assistant supports **99+ languages** including:
- English
- Arabic (العربية)
- Spanish, French, German, Italian
- Chinese (中文), Japanese (日本語), Korean (한국어)
- Hindi, Urdu, Bengali
- And many more...

Language is automatically detected - just speak naturally!

## ⚡ Performance

- **Division Matching**: ~50ms per query
- **Name Extraction**: ~100-200ms per query
- **Voice Processing**: ~1-3 seconds (depends on audio length)
- **Contact Search**: ~100-300ms per query

## 🛠️ Built With

- **Gradio** - Interactive web interface
- **FastAPI** - Backend API (original implementation)
- **Sentence Transformers** - Semantic search
- **OpenAI Whisper** - Speech recognition
- **GLiNER** - Named Entity Recognition
- **PyTorch** - Deep learning framework

## 📝 License

MIT License

## 🙏 Acknowledgments

- OpenAI for Whisper
- Hugging Face for model hosting
- URCHADE for GLiNER
- Sentence Transformers team

---

**Version:** 4.0.0
**Status:** ✅ Production Ready
**Demo Type:** Interactive Gradio Demo