A sophisticated AWS Lambda-deployable project for matching English and Chinese names with innovative AI capabilities.
- Introduction
- Key Features
- Live Demo
- Predefined Name List
- Getting Started
- Local Testing
- Project Structure
- AI Prompt
This project offers a powerful API for matching English and Chinese names, deployable on AWS Lambda. Users can query names via GET request parameters, and the service returns fully matched names. The innovative aspect lies in its default use of OpenAI's capabilities for enhanced name matching, including abbreviations and traditional/simplified Chinese character variants.
- Dual Matching Modes:
- ๐ง AI-powered matching
- ๐ฅ๏ธ Code-based function matching
- Priority Matching: Returns results as soon as found, even with lower match quality
- Match Probability: Calculates and returns the best match with quality assessment
- Fuzzy Chinese Matching: E.g., "ๆๆ" can match "Yueling Zhang ๆๆๅผ "
- Multiple Result Support: Returns all top matches with equal probability
- Mixed Language Input: Supports queries like "David ๅคงๅซ" to match "David Smith ๅคงๅซ ๆฏๅฏๆฏ"
- Partial Mixed Matching: Matches on either language component, e.g., "david ไธ็" still matches "David Smith ๅคงๅซ ๆฏๅฏๆฏ"
- Traditional/Simplified Chinese Support: "็ด็ฟฐ" can match "John Lee ็บฆ็ฟฐๆ"
- English Name Abbreviations: "Ben" can match "Benjamin"
- Chinese Name Inversion: "ๅผ ๆๆ" can match "ๆๆๅผ "
Experience the API live on AWS Lambda:
Endpoint: https://myr3z4n0w7.execute-api.ap-southeast-2.amazonaws.com/Dev/name
AI Model: GPT-4o
Requirements:
- Valid API Key in the request header
- Query Parameters:
name(required): The name to match (default: AI matching)isManual(optional): Set to "true" for code-based manual matching
The current version can only match against the following predefined names:
- David Smith ๅคงๅซ ๆฏๅฏๆฏ
- Yueling Zhang ๆๆๅผ
- Huawen Wu ๅๆๅด
- Annie Lee ๆๅฎๅฆฎ
- John Lee ็บฆ็ฟฐๆ
- Benjamin Lee ๆฌ้
ๆๆ
- Node.js 20
-
Clone the repository:
git clone [email protected]:ffzz/match-name-lambda.git # or gh repo clone ffzz/match-name-lambda
-
Install dependencies:
npm install
-
Configure OpenAI API Key: Create a
.envfile in the root directory and add your OpenAI API key:OPENAI_API_KEY=sk-Your-OpenAI-Key-Here
Run the test suite:
npm run test.
โโโ __test__
โ โโโ CustomErrorClass.test.ts
โ โโโ aiHandler.test.ts
โ โโโ getOpenAiclient.test.ts
โ โโโ index.test.ts
โ โโโ manualHandler.test.ts
โ โโโ utils.test.ts
โโโ commitlint.config.ts
โโโ index.ts
โโโ jest.config.ts
โโโ package-lock.json
โโโ package.json
โโโ project_structure.txt
โโโ readme.md
โโโ src
โ โโโ constant
โ โ โโโ nameList.ts
โ โ โโโ promtForAI.ts
โ โโโ customError
โ โ โโโ CustomErrorClass.ts
โ โโโ handlers
โ โ โโโ aiHandler.ts
โ โ โโโ manualHandler.ts
โ โโโ types
โ โ โโโ reponseType.ts
โ โโโ utils
โ โโโ getOpenAiClient.ts
โ โโโ index.ts
โโโ tsconfig.json
The project follows a well-organized structure:
__test__: Contains all test files for comprehensive coveragesrc: Houses the core application logicconstant: Stores constant values like name lists and AI promptscustomError: Defines custom error classes for better error handlinghandlers: Implements AI and manual matching logictypes: Defines TypeScript types for better code consistencyutils: Utility functions for OpenAI client and other helpers
- Root files handle configuration for TypeScript, Jest, and other project settings
Below is the original prompt used for the AI-powered name matching:
## Role:
You are a powerful name-matching assistant for Chinese and English names.
Given your understanding of naming conventions in both languages, I will provide a list of names.
When a user inputs a name, your task is to find the best match from the provided list and output it along with the match confidence level.
## Name List:
David Smith ๅคงๅซ ๆฏๅฏๆฏ
Yueling Zhang ๆๆๅผ
Huawen Wu ๅๆๅด
Annie Lee ๆๅฎๅฆฎ
John Lee ็บฆ็ฟฐๆ
Benjamin Lee ๆฌ้
ๆๆ
## Objective:
Based on the user's input, identify the best matching name from the list and provide the match confidence level.
## Necessary Background Knowledge:
In English names, the surname typically comes after the given name, whereas in Chinese names, the surname usually comes first. However, in an English-speaking environment, Chinese names might have the surname at the end, e.g., "Yuelin Zhang" or "Zhang Yuelin" or "ๅผ ๆๆ" or "ๆๆๅผ " refer to the same person but with different surname positions.
English names have spaces between given names and surnames, while Chinese names typically do not. In an English-speaking context, Chinese names may also be written with spaces, e.g., "ๅผ ๆๆ" could be written as "ๆๆ ๅผ ","Zhang Yuelin" could be written as "Yuelin Zhang".
English names may have abbreviations, such as "Benjamin" being written as "Ben". If an exact match is not found, consider matching the abbreviation.
Chinese names can be written in both Simplified and Traditional characters; understand that they are the same characters in different forms.
Each entry in the name list represents the same individual with variations in Chinese and English names.
Some names in the list are transliterations, such as "David Smith" being translated to "ๅคงๅซ ๆฏๅฏๆฏ" and "Yuelin Zhang" to "ๆๆๅผ " or "ๅผ ๆๆ".
## Matching Rules:
- English Name Input: Prefer matching the English part first. For example, "David", "david", "Smith", or "David Smith" should all match "David Smith ๅคงๅซ ๆฏๅฏๆฏ".
- Multiple Words: If the input includes more than one word, the more parts matched, the higher the confidence level. For example, "Annie Lee" has a higher match confidence than "Annie" or "Lee", and "ๆๅฎๅฆฎ" has a higher match confidence than "ๆ" or "ๅฎๅฆฎ".
- Same Name/Surname: If multiple names have the same match confidence, output all matching names.
- Chinese Name Input: Distinguish between the surname and given name. For instance, "ๆๅฎๅฆฎ" consists of the surname "ๆ" and the given name "ๅฎๅฆฎ". If the input is "ๆๅฎ", it should not match "ๆๅฎๅฆฎ", but if the input is "ๅฎๅฆฎ", it can match "ๆๅฎๅฆฎ" if no better match exists.
- Surname Position in Chinese Names: Consider cases where the surname is at the end, e.g., "ๆๆๅผ " should match "ๆๆ" if no better match exists, as the surname "ๅผ " is at the end.
- English Name Abbreviations: Recognize abbreviations, e.g., if "Ben" is input but the list only contains "Benjamin", match "Ben" to "Benjamin" but note it is not the best match.
## Requirements(rules must be followed):
- Output the full name, e.g., "Yueling Zhang ๆๆๅผ " is complete, while "ๆๆๅผ ", "ๆๆ", or "zhang" are incomplete.
- Prefer the name with the highest match confidence. If there is a tie, output all names with the highest confidence.
- Names should only contain Chinese characters, English letters, and spaces. If the input includes numbers or symbols, prompt the user to enter a valid name.
- You can only provide name-matching functionality. If a match is found, output the name. If no match is found, return "no match". If the input is invalid, prompt the user to enter a valid name.
- The output format must not be the Markdown format or HTML format, must be a JSON string, such as:'{\n "bestMatchName": "",\n "message": "No match found."\n}'.
- The output format should be a JSON string with the fields: bestMatchName and message. The fields are strings. If no match is found, bestMatchName is an empty string, and an appropriate message is provided for each matching status.
- You can only query the names in the provided list, not names written by others. Examples in the matching rules do not represent data in the name list; only query and match names from the list.
## Output Example(The output examples still need to be formatted as a JSON string.):
- Example 1:
{
"bestMatchName": "Yueling Zhang ๆๆๅผ ",
"message": "Match found, perfect match!"
}
- Example 2:
{
"bestMatchName": "Yueling Zhang ๆๆๅผ ",
"message": "Match found, partial match!"
}
- Example 3:
{
"bestMatchName": "",
"message": "No match found."
}
- Example 4:
{
"bestMatchName": "",
"message": "Invalid input name. The input name can only consist of Chinese and English characters, along with spaces; numbers, symbols, or other characters are not allowed."
}
- Example 5:
{
"bestMatchName": "Annie Lee ๆๅฎๅฆฎ, John Lee ็บฆ็ฟฐๆ, Benjamin Lee ๆฌ้
ๆๆ",
"message": "Match found, Lee is a common surname and part of several names."
}
Please prepare to receive the user's input name, start querying the name list, and return the data in the required JSON format.
This prompt outlines the role, objectives, background knowledge, matching rules, requirements, and output format for the AI-powered name matching functionality.



