resume-anonymizer/README.md

A flexible NPM package for anonymizing resumes to reduce bias in hiring

# resume-anonymizer

A flexible NPM package for anonymizing resumes to reduce bias in hiring processes. This package helps recruiters and job applicants remove personally identifiable information (PII) from resumes while preserving their structure and useful content.

## Features

- 🔒 Remove or replace names, contact information, and other PII
- 🏢 Anonymize company names and educational institutions
- 🎯 Configurable anonymization levels (minimal, moderate, strict)
- 🤖 AI-powered text rewording for natural readability
- 🌍 Multi-language support
- ✅ Built-in verification to ensure complete anonymization
- 📝 Detailed change logs for transparency

## Installation

```bash
npm install resume-anonymizer
```

## Quick Start

```typescript
import { anonymizeCandidate } from 'resume-anonymizer';

const resume = {
  name: "John Doe",
  email: "john.doe@example.com",
  phone: "+1-234-567-8900",
  experience: [
    {
      company: "Google",
      position: "Software Engineer",
      description: "Developed scalable systems at Google"
    }
  ]
};

const anonymized = await anonymizeCandidate(resume, {
  hide: {
    name: true,
    contact: true,
    companyNames: true
  }
});

console.log(anonymized.anonymizedResume);
// Output: Name replaced with "Candidate A", contact info removed, 
// "Google" replaced with "Company A"
```

## Configuration Options

### Basic Options

```typescript
interface AnonymizationOptions {
  // Control what to hide
  hide: {
    name?: boolean;          // Hide candidate's name
    contact?: boolean;       // Hide email, phone, address
    photo?: boolean;         // Remove photos
    companyNames?: boolean;  // Hide company names
    education?: boolean;     // Hide educational institutions
    references?: boolean;    // Hide reference names
    locations?: boolean;     // Hide geographic locations
    otherPII?: boolean;     // Catch-all for other PII
  };
  
  // Pseudonym settings
  pseudonym?: {
    name?: string;           // Default: "Candidate A"
    company?: string;        // Pattern like "Company <letter>"
    person?: string;         // Pattern for other names
  };
  
  // Preset anonymization levels
  mode?: 'minimal' | 'moderate' | 'strict';
  
  // AI-powered rewording
  rewordingLevel?: 'none' | 'light' | 'medium' | 'heavy';
  
  // Verification
  verify?: boolean;          // Run post-process verification
}
```

## API Reference

### `anonymizeCandidate(candidate, options)`

Main function to anonymize a resume.

**Parameters:**
- `candidate`: Resume object (compatible with JSON Resume format)
- `options`: Configuration options (see above)

**Returns:**
```typescript
{
  anonymizedResume: object;  // The anonymized resume
  changes: {                 // Log of all changes made
    name: { original: string, replacedWith: string };
    companies: Array<{ original: string, replacedWith: string }>;
    // ... other changes
  }
}
```

## Examples

### Minimal Anonymization
```typescript
// Only hide direct PII (name, contacts, photo)
const result = await anonymizeCandidate(resume, {
  mode: 'minimal'
});
```

### Moderate Anonymization
```typescript
// Hide PII and company names, keep role descriptions
const result = await anonymizeCandidate(resume, {
  mode: 'moderate'
});
```

### Custom Configuration
```typescript
const result = await anonymizeCandidate(resume, {
  hide: {
    name: true,
    contact: true,
    companyNames: true,
    education: false  // Keep education visible
  },
  pseudonym: {
    name: "Applicant #1",
    company: "Organization <number>"
  },
  rewordingLevel: 'light',
  verify: true
});
```

## Development

```bash
# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm test

# Run linting
npm run lint

# Type checking
npm run typecheck
```

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.