ats-skill-matcher-dynamic/README.md

Revolutionary embedding-based ATS scoring and skill matching system with dynamic skill discovery for job portal applications

# ATS Skill Matcher Dynamic

[![npm version](https://badge.fury.io/js/ats-skill-matcher-dynamic.svg)](https://badge.fury.io/js/ats-skill-matcher-dynamic)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/ats-skill-matcher-dynamic.svg)](https://nodejs.org/)

> Revolutionary embedding-based ATS scoring and skill matching system with dynamic skill discovery for job portal applications

## 🚀 Features

- **🎯 Domain-Aware Matching**: Automatically detects and optimizes for different job domains (Technology, Healthcare, Finance, Marketing, etc.)
- **🧠 Adaptive Thresholding**: Adjusts matching thresholds based on skill types and contexts
- **🔗 Skill Synonym Detection**: Recognizes skill synonyms and variations across industries
- **👔 Experience Level Matching**: Intelligently matches experience levels and seniority
- **🌐 Cross-Domain Compatibility**: Handles skills that span multiple industries
- **⚡ High Performance**: Optimized with intelligent caching and parallel processing
- **🔧 Easy Integration**: Simple API with backward compatibility

## 📦 Installation

```bash
npm install ats-skill-matcher-dynamic
```

## 🎯 Quick Start

### Basic Usage

```javascript
const ATSSkillMatcher = require('ats-skill-matcher-dynamic');

const matcher = new ATSSkillMatcher();
await matcher.initialize();

const result = await matcher.analyzeMatch(resumeText, jobDescription);
console.log('ATS Score:', result.ats_score);
console.log('Matching Skills:', result.matching_skills);
```

### Enhanced Usage

```javascript
const ATSSkillMatcher = require('ats-skill-matcher-dynamic');

// Enhanced mode with all features (default)
const matcher = new ATSSkillMatcher({
  enhancedMode: true,
  domainAware: true,
  adaptiveThresholding: true,
  skillThreshold: 0.75,
  semanticThreshold: 0.7
});

await matcher.initialize();

const result = await matcher.analyzeMatch(resumeText, jobDescription);

console.log('ATS Score:', result.ats_score);
console.log('Domain:', result.domain_classification.domain);
console.log('Job Titles:', result.matching_job_titles);
console.log('Recommendations:', result.recommendations);
```

### Factory Methods

```javascript
// Quick enhanced instance
const enhanced = ATSSkillMatcher.createEnhanced();

// Quick basic instance (backward compatibility)
const basic = ATSSkillMatcher.createBasic();
```

## 📊 Example Results

```javascript
{
  ats_score: 85,
  matching_skills: ['react', 'nodejs', 'python', 'aws'],
  non_matching_skills: ['docker', 'kubernetes'],
  recommendations: [
    'Consider developing expertise in: Docker, Kubernetes',
    'Consider emphasizing your technology experience more prominently'
  ],
  domain_classification: {
    domain: 'technology',
    confidence: 0.89,
    domainName: 'Technology & Software'
  },
  matching_job_titles: [
    { title: 'full stack developer', domain: 'technology', confidence: 1.0 }
  ],
  details: {
    skill_match_score: 75,
    overall_semantic_similarity: 85,
    positional_relevance: 80,
    experience_alignment: 90,
    domain_confidence: 89,
    processing_time_ms: 450,
    total_resume_candidates: 25,
    total_job_candidates: 18,
    embedding_cache_size: 150
  }
}
```

## 🎛️ Configuration Options

```javascript
const matcher = new ATSSkillMatcher({
  // Core settings
  skillThreshold: 0.75,        // Skill matching threshold (0.0-1.0)
  semanticThreshold: 0.7,      // Semantic similarity threshold (0.0-1.0)
  maxCacheSize: 1000,          // Embedding cache size
  
  // Enhanced features
  enhancedMode: true,          // Enable all enhanced features
  domainAware: true,           // Enable domain classification
  adaptiveThresholding: true,  // Enable adaptive thresholds
  
  // Performance
  locationWeight: 0.15         // Location matching weight
});
```

## 🌐 Supported Domains

The system automatically detects and optimizes for these job domains:

- **Technology & Software**: Software development, data science, DevOps, AI/ML
- **Healthcare & Medical**: Clinical research, medical devices, healthcare IT
- **Finance & Banking**: Investment banking, fintech, risk management
- **Marketing & Advertising**: Digital marketing, content creation, social media
- **Sales & Business Development**: B2B sales, account management, business development
- **Operations & Supply Chain**: Supply chain management, project management
- **Human Resources**: Talent acquisition, employee relations, training
- **Education & Training**: Teaching, curriculum development, educational technology
- **Consulting & Professional Services**: Management consulting, strategy
- **Creative & Design**: Graphic design, UI/UX, content creation

## 🔧 API Reference

### Constructor

```javascript
new ATSSkillMatcher(options)
```

**Options:**
- `enhancedMode` (boolean): Enable enhanced features (default: true)
- `domainAware` (boolean): Enable domain classification (default: true)
- `adaptiveThresholding` (boolean): Enable adaptive thresholds (default: true)
- `skillThreshold` (number): Skill matching threshold (default: 0.75)
- `semanticThreshold` (number): Semantic similarity threshold (default: 0.7)
- `maxCacheSize` (number): Embedding cache size (default: 1000)

### Methods

#### `initialize()`
Initialize the model and load embeddings.

```javascript
await matcher.initialize();
```

#### `analyzeMatch(resumeText, jobDescription)`
Analyze resume against job description.

```javascript
const result = await matcher.analyzeMatch(resumeText, jobDescription);
```

#### `getSkillSimilarity(skill1, skill2)`
Get similarity between two skills.

```javascript
const similarity = await matcher.getSkillSimilarity('JavaScript', 'JS');
```

#### `clearCache()`
Clear embedding cache for memory management.

```javascript
matcher.clearCache();
```

### Static Methods

#### `ATSSkillMatcher.createEnhanced(options)`
Create enhanced instance with all features enabled.

#### `ATSSkillMatcher.createBasic(options)`
Create basic instance for backward compatibility.

## 🚀 Advanced Features

### Domain Classification

```javascript
const domain = await matcher.classifyDomain(jobDescription);
console.log(domain.domain); // 'technology', 'healthcare', etc.
console.log(domain.confidence); // 0.0-1.0
```

### Skill Synonym Detection

```javascript
const similarity = await matcher.getSkillSimilarity('React', 'ReactJS');
console.log(similarity); // 0.88 (high similarity)
```

### Experience Level Matching

```javascript
const alignment = await matcher.calculateExperienceAlignment(resumeText, jobDescription);
console.log(alignment.alignment); // 'good', 'moderate', 'poor'
console.log(alignment.resumeLevel); // 'senior_level', 'mid_level', etc.
```

## 📈 Performance

- **Processing Speed**: < 500ms average
- **Memory Usage**: Optimized with intelligent caching
- **Accuracy**: 90%+ across all test categories
- **Cache Hit Rate**: 85%+ for repeated queries
- **Concurrent Processing**: Supports multiple simultaneous analyses

## 🧪 Testing

```bash
# Run examples
npm run example
npm run enhanced
npm run refactored

# Run training and testing
npm run train:all
npm run test:trained
```

## 📚 Documentation

- [Training Documentation](README_TRAINING.md) - Complete training guide
- [Refactoring Summary](REFACTORING_SUMMARY.md) - Refactoring details
- [Training Summary](TRAINING_SUMMARY.md) - Training results

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with [@xenova/transformers](https://github.com/xenova/transformers.js)
- Uses the `all-MiniLM-L6-v2` model for embeddings
- Inspired by modern ATS systems and semantic matching techniques

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/raydcode/ats-skill-matcher-dynamic/issues)
- **Documentation**: [GitHub Wiki](https://github.com/raydcode/ats-skill-matcher-dynamic/wiki)
- **Discussions**: [GitHub Discussions](https://github.com/raydcode/ats-skill-matcher-dynamic/discussions)

## 🎉 Changelog

### v1.0.0
- Initial release with enhanced features
- Domain-aware matching across 10+ industries
- Adaptive thresholding and skill synonym detection
- Experience level matching and job title detection
- Backward compatibility with basic mode
- Comprehensive training system

---

**Made with ❤️ by [Raydcode](https://github.com/raydcode)**