Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/chintakjoshi/name_verification_app

The Name Verification Application generates human names from natural language prompts and verifies candidate names using deterministic fuzzy matching. It enforces a strict black box design where the verifier only receives the latest name string, ensuring clean separation, reliability, and full test coverage.
https://github.com/chintakjoshi/name_verification_app

fuzzymatching levenshteindistance stringsimilarity

Last synced: 2 months ago
JSON representation

The Name Verification Application generates human names from natural language prompts and verifies candidate names using deterministic fuzzy matching. It enforces a strict black box design where the verifier only receives the latest name string, ensuring clean separation, reliability, and full test coverage.

Awesome Lists containing this project

README 

          
# Name Verification Application



## Overview



The Name Verification Application is a specialized tool designed to demonstrate intelligent name matching with strict architectural separation. The system consists of two independent components: a Target Name Generator and a Name Verifier, operating under the constraint that the verifier must treat the generator as a black box.



## Key Features



- **Target Name Generation**: Generate unique human names from natural language prompts using LLM integration

- **Name Verification**: Verify candidate names against the latest generated target with fuzzy matching

- **Black Box Architecture**: Strict isolation between generator and verifier components

- **Comprehensive Test Suite**: 30 test cases covering various name matching scenarios

- **Mock Mode**: Fallback to mock data when LLM API keys are unavailable

- **Production-Ready**: Full test coverage and robust error handling



## Architecture and Design



### Core Principles



- **Black Box Constraint**: The verifier cannot access generator internals, chat history, or call back into the generator

- **Deterministic Verification**: Matching algorithm produces stable, consistent results

- **Isolated State**: Only the latest generated name string is shared between components



### Component Architecture



```

┌─────────────────┐

│    Client UI    │

│   (React/TS)    │

└─────────────────┘

        │

        │

        │

        ▼

┌───────────────┐               ┌────────────────┐

│  API server   │   generates   │                │

│ (Express/TS)  │──────────────►│ Name Generator │

│               │               │   (LLM/Mock)   │

└───────────────┘               └────────────────┘

        │

        │ exposes only

        │ targetName:string

        ▼

┌─────────────────┐

│  Name Verifier  │

│ (Fuzzy Matcher) │

└─────────────────┘

```



## Technology Stack



### Frontend



- **Framework**: React 19 with TypeScript

- **Styling**: Tailwind CSS 4

- **Build Tool**: Vite

- **HTTP Client**: Native Fetch API with typed wrappers



### Backend



- **Runtime**: Node.js (>=18.0.0)

- **Framework**: Express.js with TypeScript

- **LLM Integration**: NVIDIA NIM API (with mock fallback)

- **Testing**: Jest with comprehensive test suite

- **Code Quality**: TypeScript, ESLint, Prettier



## Prerequisites



- Node.js >= 18.0.0

- npm >= 9.0.0

- (Optional) NVIDIA NIM API key for live name generation



## Installation



### 1. Clone and Setup



```bash

# Clone the repository

git clone 

cd name_verification_app



# Install root dependencies

npm install



# Install client and server dependencies

npm run install:all

```



### 2. Environment Configuration



Create a `.env` file in the server directory:



```bash

# server/.env

LLM_PROVIDER=nvidia_nim

LLM_MODEL=meta/llama-3.3-70b-instruct

LLM_TEMPERATURE=0.2

LLM_TOP_P=0.9

LLM_MAX_TOKENS=256



# Optional: Add your NVIDIA NIM API key for live generation

# NIM_API_KEY=your_nim_api_key_here

NIM_BASE_URL=https://integrate.api.nvidia.com/v1



PORT=3001

NODE_ENV=development

```



## Running the Application



### Development Mode



Start both client and server concurrently:



```bash

npm run dev

```



This will launch:

- **Client**: http://localhost:3000

- **Server**: http://localhost:3001

- **API Proxy**: Client automatically proxies `/api` requests to the server



### Production Build



```bash

# Build both client and server

npm run build



# Start production server

npm start

```



## Testing



### Run Test Suite



```bash

# Run all tests

npm test



# Run tests with coverage

npm run test:coverage



# Run tests in watch mode

npm run test:watch

```



### Test Coverage



The application includes 63 comprehensive tests covering:

- Name matching algorithms (30 test cases)

- Edge cases and error handling

- Performance benchmarks

- Configuration validation



## Usage Guide



### 1. Generating Target Names



1. Navigate to the "Target Name Generator" panel

2. Enter a prompt (e.g., "Generate a random Arabic sounding name with Al and ibn")

3. Click "Generate"

4. The system will produce a target name and store it as the latest



### 2. Verifying Candidate Names



1. Navigate to the "Name Verifier" panel

2. Enter a candidate name to check

3. Click "Verify"

4. View results including match status, confidence score, and explanation



### Example Workflow



```

Prompt: "Generate a Spanish name with two last names"

Generated Target: "Maria Garcia Lopez"



Candidate: "Mario Garcia Lopez"

Result: No Match (51% confidence)

Reason: Gendered name difference



Candidate: "Maria Garcia-Lopez"

Result: Match (92% confidence)

Reason: Names match with minor variations

```



## API Documentation



### Generate Endpoint



**POST** `/api/generate`



Request:

```json

{

  "prompt": "Generate a random Arabic sounding name"

}

```



Response:

```json

{

  "targetName": "Ahmed Al Fayed"

}

```



### Verify Endpoint



**POST** `/api/verify`



Request:

```json

{

  "candidateName": "Ahmad Alfayed"

}

```



Response:

```json

{

  "match": true,

  "confidence": 0.85,

  "reason": "Names match with minor variations (spelling, nickname, or transliteration)",

  "targetName": "Ahmed Al Fayed"

}

```



## Name Matching Algorithm



The verifier implements a sophisticated multi-layered matching strategy:



### 1. Normalization



- Convert to lowercase

- Remove diacritics and punctuation

- Standardize spacing and hyphens

- Special handling for Arabic names (Al, ibn, Abdul)



### 2. Token Matching



- Greedy token alignment algorithm

- Nickname equivalence mapping (Bob ↔ Robert, Liz ↔ Elizabeth)

- Transliteration variations (Mohammed ↔ Muhammad)

- Phonetic suffix handling (v ↔ ff, ov ↔ off)



### 3. Similarity Scoring



- Levenshtein distance for typos

- String similarity thresholds

- Cultural-specific rule sets

- Order swap detection and penalization



### 4. Confidence Calculation



- Weighted average of token matches

- Penalties for structural differences

- Adaptive thresholds based on name complexity



## Test Cases



The application passes 30 specified test cases including:



### Expected Matches (18 cases)



- Transposition typos: "Tyler Bliha" ↔ "Tlyer Bilha"

- Cultural variations: "Mohammed Al Fayed" ↔ "Muhammad Alfayed"

- Nickname equivalence: "Bob Ellensworth" ↔ "Robert Ellensworth"

- Punctuation differences: "Sarah O'Connor" ↔ "Sara Oconnor"



### Expected Non-Matches (12 cases)



- Different first names: "John Smith" ↔ "James Smith"

- Order swaps: "Ali Hassan" ↔ "Hassan Ali"

- Gendered differences: "Maria Gonzalez" ↔ "Mario Gonzalez"

- Different surname roots: "Ahmed Al Rashid" ↔ "Ahmed Al Rashidi"



## Configuration Options



### Environment Variables



| Variable | Default | Description |

|----------|---------|-------------|

| LLM_PROVIDER | nvidia_nim | LLM provider (nvidia_nim, openai_compatible, other) |

| LLM_MODEL | meta/llama-3.3-70b-instruct | Model identifier |

| LLM_TEMPERATURE | 0.2 | Generation creativity (0-2) |

| LLM_TOP_P | 0.9 | Nucleus sampling parameter |

| LLM_MAX_TOKENS | 256 | Maximum tokens per generation |

| NIM_API_KEY | - | NVIDIA NIM API key (optional) |

| NIM_BASE_URL | https://integrate.api.nvidia.com/v1 | API endpoint |

| PORT | 3001 | Server port |

| NODE_ENV | development | Runtime environment |



### Mock Mode



When no API key is provided, the system automatically uses a mock name generator that:

- Returns consistent names based on prompt hash

- Includes all test case names in rotation

- Provides deterministic behavior for testing



## Project Structure



```

name_verification_app/

├── client/                    # React frontend

│   ├── src/

│   │   ├── api/              # HTTP client and types

│   │   ├── components/       # React components

│   │   └── App.tsx          # Main application

│   └── vite.config.ts       # Build configuration

├── server/                   # Express backend

│   ├── src/

│   │   ├── config/          # Configuration management

│   │   ├── generator/       # Name generation logic

│   │   ├── verifier/        # Name matching algorithm

│   │   ├── storage/         # Latest target persistence

│   │   ├── routes/          # API endpoints

│   │   └── index.ts         # Server entry point

│   └── test/               # Comprehensive test suite

├── package.json            # Root build and run scripts

└── README.md              # This documentation

```



## Development Guidelines



### Code Style



- TypeScript strict mode enabled

- ESLint with React/TypeScript rules

- Prettier for code formatting

- Consistent import ordering



### Error Handling



- Structured error responses from API

- Graceful degradation when services unavailable

- Comprehensive logging in development mode

- User-friendly error messages in UI



## Limitations and Future Improvements



### Current Limitations



- English-centric nickname mappings

- Limited support for non-Latin scripts

- Basic phonetic matching (no Soundex/Metaphone)

- In-memory state persistence (restart clears state)



## Troubleshooting



### Common Issues



**Server fails to start:**

- Check Node.js version (>=18 required)

- Verify all dependencies are installed (`npm run install:all`)

- Ensure PORT 3001 is available



**Name generation fails:**

- Check `NIM_API_KEY` in `server/.env`

- Verify network connectivity to NVIDIA NIM

- Review server logs for API errors



**Tests failing:**

- Ensure all dependencies are installed

- Check test environment configuration

- Verify no other process is using test ports



**Client cannot connect to server:**

- Verify both client and server are running

- Check proxy configuration in `vite.config.ts`

- Ensure CORS is properly configured



### Debug Mode



Enable detailed logging by setting in `server/.env`:



```bash

DEBUG=true

NODE_ENV=development

```



## Security Considerations



- API keys stored server-side only

- No sensitive data in client code

- Input validation on all endpoints

- CORS configured for development only

- Environment-based configuration



## Acknowledgments



- Test cases designed to cover realistic name matching scenarios

- Architecture inspired by clean separation principles

- Fuzzy matching algorithm optimized for name-specific patterns

- Built as a demonstration of robust system design with TypeScript



This application serves as both a practical tool for name verification and a demonstration of well-architected, test-driven TypeScript application development with clear separation of concerns and comprehensive error handling.