{"id":48089761,"url":"https://github.com/chintakjoshi/name_verification_app","last_synced_at":"2026-04-04T15:29:10.249Z","repository":{"id":329648669,"uuid":"1120232211","full_name":"chintakjoshi/name_verification_app","owner":"chintakjoshi","description":"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.","archived":false,"fork":false,"pushed_at":"2025-12-21T03:31:12.000Z","size":209,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-22T21:36:54.590Z","etag":null,"topics":["fuzzymatching","levenshteindistance","stringsimilarity"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chintakjoshi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-20T19:02:56.000Z","updated_at":"2025-12-21T03:31:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/chintakjoshi/name_verification_app","commit_stats":null,"previous_names":["chintakjoshi/name_verification_app"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/chintakjoshi/name_verification_app","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chintakjoshi%2Fname_verification_app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chintakjoshi%2Fname_verification_app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chintakjoshi%2Fname_verification_app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chintakjoshi%2Fname_verification_app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chintakjoshi","download_url":"https://codeload.github.com/chintakjoshi/name_verification_app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chintakjoshi%2Fname_verification_app/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31403958,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fuzzymatching","levenshteindistance","stringsimilarity"],"created_at":"2026-04-04T15:29:08.712Z","updated_at":"2026-04-04T15:29:10.167Z","avatar_url":"https://github.com/chintakjoshi.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Name Verification Application\n\n## Overview\n\nThe 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.\n\n## Key Features\n\n- **Target Name Generation**: Generate unique human names from natural language prompts using LLM integration\n- **Name Verification**: Verify candidate names against the latest generated target with fuzzy matching\n- **Black Box Architecture**: Strict isolation between generator and verifier components\n- **Comprehensive Test Suite**: 30 test cases covering various name matching scenarios\n- **Mock Mode**: Fallback to mock data when LLM API keys are unavailable\n- **Production-Ready**: Full test coverage and robust error handling\n\n## Architecture and Design\n\n### Core Principles\n\n- **Black Box Constraint**: The verifier cannot access generator internals, chat history, or call back into the generator\n- **Deterministic Verification**: Matching algorithm produces stable, consistent results\n- **Isolated State**: Only the latest generated name string is shared between components\n\n### Component Architecture\n\n```\n┌─────────────────┐\n│    Client UI    │\n│   (React/TS)    │\n└─────────────────┘\n        │\n        │\n        │\n        ▼\n┌───────────────┐               ┌────────────────┐\n│  API server   │   generates   │                │\n│ (Express/TS)  │──────────────►│ Name Generator │\n│               │               │   (LLM/Mock)   │\n└───────────────┘               └────────────────┘\n        │\n        │ exposes only\n        │ targetName:string\n        ▼\n┌─────────────────┐\n│  Name Verifier  │\n│ (Fuzzy Matcher) │\n└─────────────────┘\n```\n\n## Technology Stack\n\n### Frontend\n\n- **Framework**: React 19 with TypeScript\n- **Styling**: Tailwind CSS 4\n- **Build Tool**: Vite\n- **HTTP Client**: Native Fetch API with typed wrappers\n\n### Backend\n\n- **Runtime**: Node.js (\u003e=18.0.0)\n- **Framework**: Express.js with TypeScript\n- **LLM Integration**: NVIDIA NIM API (with mock fallback)\n- **Testing**: Jest with comprehensive test suite\n- **Code Quality**: TypeScript, ESLint, Prettier\n\n## Prerequisites\n\n- Node.js \u003e= 18.0.0\n- npm \u003e= 9.0.0\n- (Optional) NVIDIA NIM API key for live name generation\n\n## Installation\n\n### 1. Clone and Setup\n\n```bash\n# Clone the repository\ngit clone \u003crepository-url\u003e\ncd name_verification_app\n\n# Install root dependencies\nnpm install\n\n# Install client and server dependencies\nnpm run install:all\n```\n\n### 2. Environment Configuration\n\nCreate a `.env` file in the server directory:\n\n```bash\n# server/.env\nLLM_PROVIDER=nvidia_nim\nLLM_MODEL=meta/llama-3.3-70b-instruct\nLLM_TEMPERATURE=0.2\nLLM_TOP_P=0.9\nLLM_MAX_TOKENS=256\n\n# Optional: Add your NVIDIA NIM API key for live generation\n# NIM_API_KEY=your_nim_api_key_here\nNIM_BASE_URL=https://integrate.api.nvidia.com/v1\n\nPORT=3001\nNODE_ENV=development\n```\n\n## Running the Application\n\n### Development Mode\n\nStart both client and server concurrently:\n\n```bash\nnpm run dev\n```\n\nThis will launch:\n- **Client**: http://localhost:3000\n- **Server**: http://localhost:3001\n- **API Proxy**: Client automatically proxies `/api` requests to the server\n\n### Production Build\n\n```bash\n# Build both client and server\nnpm run build\n\n# Start production server\nnpm start\n```\n\n## Testing\n\n### Run Test Suite\n\n```bash\n# Run all tests\nnpm test\n\n# Run tests with coverage\nnpm run test:coverage\n\n# Run tests in watch mode\nnpm run test:watch\n```\n\n### Test Coverage\n\nThe application includes 63 comprehensive tests covering:\n- Name matching algorithms (30 test cases)\n- Edge cases and error handling\n- Performance benchmarks\n- Configuration validation\n\n## Usage Guide\n\n### 1. Generating Target Names\n\n1. Navigate to the \"Target Name Generator\" panel\n2. Enter a prompt (e.g., \"Generate a random Arabic sounding name with Al and ibn\")\n3. Click \"Generate\"\n4. The system will produce a target name and store it as the latest\n\n### 2. Verifying Candidate Names\n\n1. Navigate to the \"Name Verifier\" panel\n2. Enter a candidate name to check\n3. Click \"Verify\"\n4. View results including match status, confidence score, and explanation\n\n### Example Workflow\n\n```\nPrompt: \"Generate a Spanish name with two last names\"\nGenerated Target: \"Maria Garcia Lopez\"\n\nCandidate: \"Mario Garcia Lopez\"\nResult: No Match (51% confidence)\nReason: Gendered name difference\n\nCandidate: \"Maria Garcia-Lopez\"\nResult: Match (92% confidence)\nReason: Names match with minor variations\n```\n\n## API Documentation\n\n### Generate Endpoint\n\n**POST** `/api/generate`\n\nRequest:\n```json\n{\n  \"prompt\": \"Generate a random Arabic sounding name\"\n}\n```\n\nResponse:\n```json\n{\n  \"targetName\": \"Ahmed Al Fayed\"\n}\n```\n\n### Verify Endpoint\n\n**POST** `/api/verify`\n\nRequest:\n```json\n{\n  \"candidateName\": \"Ahmad Alfayed\"\n}\n```\n\nResponse:\n```json\n{\n  \"match\": true,\n  \"confidence\": 0.85,\n  \"reason\": \"Names match with minor variations (spelling, nickname, or transliteration)\",\n  \"targetName\": \"Ahmed Al Fayed\"\n}\n```\n\n## Name Matching Algorithm\n\nThe verifier implements a sophisticated multi-layered matching strategy:\n\n### 1. Normalization\n\n- Convert to lowercase\n- Remove diacritics and punctuation\n- Standardize spacing and hyphens\n- Special handling for Arabic names (Al, ibn, Abdul)\n\n### 2. Token Matching\n\n- Greedy token alignment algorithm\n- Nickname equivalence mapping (Bob ↔ Robert, Liz ↔ Elizabeth)\n- Transliteration variations (Mohammed ↔ Muhammad)\n- Phonetic suffix handling (v ↔ ff, ov ↔ off)\n\n### 3. Similarity Scoring\n\n- Levenshtein distance for typos\n- String similarity thresholds\n- Cultural-specific rule sets\n- Order swap detection and penalization\n\n### 4. Confidence Calculation\n\n- Weighted average of token matches\n- Penalties for structural differences\n- Adaptive thresholds based on name complexity\n\n## Test Cases\n\nThe application passes 30 specified test cases including:\n\n### Expected Matches (18 cases)\n\n- Transposition typos: \"Tyler Bliha\" ↔ \"Tlyer Bilha\"\n- Cultural variations: \"Mohammed Al Fayed\" ↔ \"Muhammad Alfayed\"\n- Nickname equivalence: \"Bob Ellensworth\" ↔ \"Robert Ellensworth\"\n- Punctuation differences: \"Sarah O'Connor\" ↔ \"Sara Oconnor\"\n\n### Expected Non-Matches (12 cases)\n\n- Different first names: \"John Smith\" ↔ \"James Smith\"\n- Order swaps: \"Ali Hassan\" ↔ \"Hassan Ali\"\n- Gendered differences: \"Maria Gonzalez\" ↔ \"Mario Gonzalez\"\n- Different surname roots: \"Ahmed Al Rashid\" ↔ \"Ahmed Al Rashidi\"\n\n## Configuration Options\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| LLM_PROVIDER | nvidia_nim | LLM provider (nvidia_nim, openai_compatible, other) |\n| LLM_MODEL | meta/llama-3.3-70b-instruct | Model identifier |\n| LLM_TEMPERATURE | 0.2 | Generation creativity (0-2) |\n| LLM_TOP_P | 0.9 | Nucleus sampling parameter |\n| LLM_MAX_TOKENS | 256 | Maximum tokens per generation |\n| NIM_API_KEY | - | NVIDIA NIM API key (optional) |\n| NIM_BASE_URL | https://integrate.api.nvidia.com/v1 | API endpoint |\n| PORT | 3001 | Server port |\n| NODE_ENV | development | Runtime environment |\n\n### Mock Mode\n\nWhen no API key is provided, the system automatically uses a mock name generator that:\n- Returns consistent names based on prompt hash\n- Includes all test case names in rotation\n- Provides deterministic behavior for testing\n\n## Project Structure\n\n```\nname_verification_app/\n├── client/                    # React frontend\n│   ├── src/\n│   │   ├── api/              # HTTP client and types\n│   │   ├── components/       # React components\n│   │   └── App.tsx          # Main application\n│   └── vite.config.ts       # Build configuration\n├── server/                   # Express backend\n│   ├── src/\n│   │   ├── config/          # Configuration management\n│   │   ├── generator/       # Name generation logic\n│   │   ├── verifier/        # Name matching algorithm\n│   │   ├── storage/         # Latest target persistence\n│   │   ├── routes/          # API endpoints\n│   │   └── index.ts         # Server entry point\n│   └── test/               # Comprehensive test suite\n├── package.json            # Root build and run scripts\n└── README.md              # This documentation\n```\n\n## Development Guidelines\n\n### Code Style\n\n- TypeScript strict mode enabled\n- ESLint with React/TypeScript rules\n- Prettier for code formatting\n- Consistent import ordering\n\n### Error Handling\n\n- Structured error responses from API\n- Graceful degradation when services unavailable\n- Comprehensive logging in development mode\n- User-friendly error messages in UI\n\n## Limitations and Future Improvements\n\n### Current Limitations\n\n- English-centric nickname mappings\n- Limited support for non-Latin scripts\n- Basic phonetic matching (no Soundex/Metaphone)\n- In-memory state persistence (restart clears state)\n\n## Troubleshooting\n\n### Common Issues\n\n**Server fails to start:**\n- Check Node.js version (\u003e=18 required)\n- Verify all dependencies are installed (`npm run install:all`)\n- Ensure PORT 3001 is available\n\n**Name generation fails:**\n- Check `NIM_API_KEY` in `server/.env`\n- Verify network connectivity to NVIDIA NIM\n- Review server logs for API errors\n\n**Tests failing:**\n- Ensure all dependencies are installed\n- Check test environment configuration\n- Verify no other process is using test ports\n\n**Client cannot connect to server:**\n- Verify both client and server are running\n- Check proxy configuration in `vite.config.ts`\n- Ensure CORS is properly configured\n\n### Debug Mode\n\nEnable detailed logging by setting in `server/.env`:\n\n```bash\nDEBUG=true\nNODE_ENV=development\n```\n\n## Security Considerations\n\n- API keys stored server-side only\n- No sensitive data in client code\n- Input validation on all endpoints\n- CORS configured for development only\n- Environment-based configuration\n\n## Acknowledgments\n\n- Test cases designed to cover realistic name matching scenarios\n- Architecture inspired by clean separation principles\n- Fuzzy matching algorithm optimized for name-specific patterns\n- Built as a demonstration of robust system design with TypeScript\n\nThis 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.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchintakjoshi%2Fname_verification_app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchintakjoshi%2Fname_verification_app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchintakjoshi%2Fname_verification_app/lists"}