Resume Processing Agent

🤖 A self-improving AI agent for processing resumes and evaluating job matches using OpenAI GPT

This project implements an intelligent agent designed to parse PDF resumes, extract structured information using OpenAI GPT, and evaluate how well candidates match job descriptions. Built for integration with the handit open-source platform for self-improving AI.

🎯 Agent Overview

Goal: Parse a resume (PDF), extract structured info, and evaluate how well it matches a job description — self-improving over time.

🧩 Architecture

The agent consists of three main nodes working in sequence:

1. 🔧 PDF Reader Tool (pdf_reader_tool)

   • Type: Tool Node
   • Function: Reads PDF files and extracts raw text
   • Input: PDF file (path or buffer)
   • Output: Raw text string with metadata

2. 🧠 Resume Extractor LLM (resume_extractor_llm)

   • Type: Model Node (structured-extraction)
   • Function: Uses OpenAI GPT to extract structured data from resume text
   • Input: Raw resume text
   • Output: JSON with name, title, skills, education, experience, contact

3. 🧠 Job Match Evaluator LLM (job_match_evaluator_llm)

   • Type: Model Node (evaluation)
   • Function: Uses OpenAI GPT to evaluate resume-job description match
   • Input: Structured resume data + job description
   • Output: Match score (0-100) with detailed breakdown and recommendations

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn
• OpenAI API Key (required for LLM nodes)

Installation

1. Clone or download this project
2. Install dependencies:

npm install

3. Set up environment variables:

# Copy the example environment file
cp env.example .env

# Edit .env and add your OpenAI API key
OPENAI_KEY=your_OPENAI_KEY_here

Basic Usage

# Run the demo (uses mock data if no PDF provided)
npm start

# Start the API server
npm run server

# Run in development mode with auto-reload
npm run dev

🌐 API Endpoints

The agent now provides HTTP endpoints for easy integration:

Start the Server

npm run server
# Server runs on http://localhost:3000

Available Endpoints

1. Process Resume File (PDF/Text Upload)

POST /process-resume
Content-Type: multipart/form-data

# Upload PDF or text file
curl -X POST http://localhost:3000/process-resume \
  -F "resume=@path/to/resume.pdf" \
  -F "jobDescription=Looking for a React developer with 3+ years experience..."

2. Process Resume Text (JSON)

POST /process-resume-text
Content-Type: application/json

curl -X POST http://localhost:3000/process-resume-text \
  -H "Content-Type: application/json" \
  -d '{
    "resumeText": "John Doe\nSoftware Engineer\nSkills: React, JavaScript, Python",
    "jobDescription": "Looking for a React developer..."
  }'

3. Health Check

GET /health

curl http://localhost:3000/health

4. API Documentation

GET /

curl http://localhost:3000/

Example Response

{
  "success": true,
  "data": {
    "sessionId": "session_1699123456_abc123def",
    "processing_time_ms": 2500,
    "results": {
      "extracted_resume": {
        "name": "Sarah Chen",
        "title": "Senior Frontend Developer",
        "skills": ["React", "JavaScript", "TypeScript", "AWS"],
        "education": "Bachelor of Science in Computer Science",
        "contact": {
          "email": "sarah.chen@email.com"
        },
        "extraction_method": "openai_gpt"
      },
      "job_match_evaluation": {
        "score": 87,
        "explanation": "Strong match with excellent technical skills alignment...",
        "breakdown": {
          "skills": 92,
          "title": 85,
          "education": 80,
          "experience": 88
        },
        "strengths": ["Strong React experience", "Relevant education"],
        "gaps": ["Limited AWS experience"],
        "recommendations": ["Highlight cloud platform experience"],
        "evaluation_method": "openai_gpt"
      },
      "confidence_score": 0.94,
      "meets_threshold": true
    }
  }
}

🔧 Environment Configuration

Create a .env file with the following variables:

# Required
OPENAI_KEY=your_OPENAI_KEY_here

# Optional
PORT=3000
NODE_ENV=development
MAX_TOKENS=2000
TEMPERATURE=0.3
CONFIDENCE_THRESHOLD=0.7

📖 API Usage Examples

JavaScript/Node.js

// Process resume text
const response = await fetch('http://localhost:3000/process-resume-text', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    resumeText: resumeContent,
    jobDescription: jobDescription
  })
});

const result = await response.json();
console.log('Match Score:', result.data.results.job_match_evaluation.score);

Python

import requests

response = requests.post('http://localhost:3000/process-resume-text', 
  json={
    'resumeText': resume_content,
    'jobDescription': job_description
  }
)

result = response.json()
print(f"Match Score: {result['data']['results']['job_match_evaluation']['score']}")

Test the API

# Run the test script
node examples/api_test.js

# Or test with your own resume
node examples/test_with_text_resume.js

🤖 OpenAI Integration

Models Used

• Resume Extraction: gpt-4o-mini (cost-effective for structured extraction)
• Job Evaluation: gpt-4o-mini (efficient for evaluation tasks)

Fallback Behavior

If OpenAI API is unavailable or quota exceeded, the agent automatically falls back to rule-based processing to ensure reliability.

Cost Optimization

• Uses efficient gpt-4o-mini model
• Configurable token limits
• Structured JSON output format
• Smart fallback to avoid failures

🔧 Handit Integration

This agent is designed for seamless integration with the handit platform:

Agent Configuration

// Get agent info for handit registration
const agentInfo = agent.getAgentInfo();
console.log(agentInfo);

Node Information

Each node provides metadata for handit integration:

// Tool node info
const pdfReaderInfo = agent.pdfReader.getToolInfo();

// LLM node info  
const extractorInfo = agent.resumeExtractor.getNodeInfo();
const evaluatorInfo = agent.jobMatchEvaluator.getNodeInfo();

Performance Tracking

The agent tracks performance metrics for self-improvement:

// Get performance analytics
const analytics = agent.getPerformanceAnalytics();
console.log(analytics);
// Output: success_rate, avg_processing_time, avg_match_score, etc.

🎨 Customization

Adding New Skills Recognition

Modify the skills extraction in src/nodes/resume_extractor_llm.js:

const skillKeywords = [
  'javascript', 'python', 'java', 'react', 'node',
  // Add your custom skills here
  'your-custom-skill', 'another-skill'
];

Custom Evaluation Weights

Adjust the scoring weights in src/nodes/job_match_evaluator_llm.js:

const totalScore = Math.round(
  (scores.skills * 0.40) +      // 40% weight on skills
  (scores.title * 0.25) +       // 25% weight on title
  (scores.experience * 0.20) +  // 20% weight on experience
  (scores.education * 0.15)     // 15% weight on education
);

OpenAI Model Configuration

Change models and parameters in the node constructors:

// In resume_extractor_llm.js or job_match_evaluator_llm.js
this.model = 'gpt-4'; // Use more powerful model
this.maxTokens = 3000; // Increase token limit
this.temperature = 0.1; // Make output more deterministic

🛠️ Development

Project Structure

resume-processing-agent/
├── src/
│   ├── nodes/
│   │   ├── pdf_reader_tool.js          # PDF processing tool
│   │   ├── resume_extractor_llm.js     # OpenAI resume extraction
│   │   └── job_match_evaluator_llm.js  # OpenAI job matching
│   ├── agent.js                        # Main agent orchestrator
│   ├── index.js                        # CLI entry point
│   └── server.js                       # HTTP API server
├── examples/                            # Example files and tests
├── package.json                         # Dependencies and scripts
├── env.example                         # Environment variables template
└── README.md                           # This file

Available Scripts

npm start          # Run CLI demo
npm run server     # Start HTTP API server
npm run dev        # Start server with auto-reload
node examples/api_test.js  # Test API endpoints

Adding Dependencies

# Add new dependencies
npm install new-package

# Update package.json
npm install

🚨 Error Handling

Common Issues

1. OpenAI API Errors

   • Check your API key is correctly set in .env
   • Verify you have sufficient quota/credits
   • Agent automatically falls back to rule-based processing

2. PDF Parsing Errors

   • Ensure PDF contains extractable text (not just images)
   • Check file permissions and size limits (10MB max)
   • Verify the PDF is not password-protected

3. Missing Dependencies

   • Run npm install to install all required packages
   • Check Node.js version (requires 18+)

4. Server Issues

   • Check if port 3000 is available
   • Verify environment variables are loaded
   • Look for error messages in console output

Getting Help

1. Check the console output for detailed error messages
2. Test the /health endpoint to verify configuration
3. Review the performance analytics for insights
4. Ensure all dependencies are properly installed

📊 Performance & Self-Improvement

The agent includes built-in performance tracking:

• Success Rate: Percentage of successful processing attempts
• Processing Time: Average time to complete full pipeline
• Match Score: Average accuracy of job matching
• Session History: Detailed logs of recent processing sessions
• API Method Tracking: OpenAI vs fallback usage statistics

This data enables continuous improvement when integrated with handit's self-improvement capabilities.

🔮 Future Enhancements

• Support for multiple resume formats (DOCX, HTML, plain text)
• Advanced NLP models for better text extraction
• Real-time performance optimization based on feedback
• Integration with job boards APIs
• Batch processing capabilities
• Web UI for easier interaction
• Multi-language support
• Fine-tuned models for specific industries

📄 License

MIT License - see LICENSE file for details

---

🚀 Ready to process some resumes with AI?

1. Set up your OpenAI API key
2. Start the server: npm run server
3. Test the API: node examples/api_test.js
4. Integrate with your applications!