Feature/Job-Fit-Analysis

[devkatevighnesh]

🚀 Pull Request: AI Candidate-JD Matching & Dynamic JD Parsing Pipeline

📝 Summary of Changes

This PR finalizes the core AI-driven Job Fit Analysis pipeline, normalizes the job description parsing endpoint, implements mathematical safeguards for parsing, and significantly optimizes container builds.

Key Accomplishments:

• Docker Build Optimization: Updated the Dockerfile to force the CPU-only PyTorch index (--index-url https://download.pytorch.org/whl/cpu). This eliminates an unnecessary 4GB download of CUDA/Nvidia drivers when building Docling, drastically reducing the container size and build time.
• Documentation Synchronization: Updated openapi.yaml, DB_DESIGN.md, and AI_PROCESSING.md to reflect the new changes.

---

🔌 API Specifications

1. Job Description Parsing API

Endpoint: POST /internal/v1/parse/jd

Description:
Parses an arbitrary JSON job description using LLM-based extraction and normalizes it into structured skills (with specific required years), experience requirements, qualifications, responsibilities, and employment details.

Request Body

{
  "title": "Senior Java Developer",
  "description": "We are hiring a Senior Java Developer to build and maintain REST APIs...",
  "job_type": "full_time",
  "work_type": "hybrid",
  "location": "Bangalore",
  "experience_min": 3,
  "experience_max": 6,
  "skills": "Java, Spring Boot, PostgreSQL, Docker, AWS, Kafka",
  "status": "published"
}

Response — 200 OK

{
  "status": "success",
  "parsed_jd": {
    "title": "Senior Java Developer",
    "company": null,
    "company_description": null,
    "experience_required": {
      "min_years": 3,
      "max_years": 6
    },
    "skills": {
      "must_have": [
        {"skill": "Java", "required_years": 3.0},
        {"skill": "Spring Boot", "required_years": null},
        {"skill": "PostgreSQL", "required_years": null}
      ],
      "good_to_have": [
        "Docker",
        "AWS",
        "Kafka"
      ]
    },
    "qualifications": [
      "Degree in Computer Science"
    ],
    "responsibilities": [
      "Design and implement backend services...",
      "Review PRs..."
    ],
    "location": "Bangalore",
    "employment_type": "full_time"
  }
}

---

2. Resume Parsing API

Endpoint: POST /internal/v1/parse/resume

Description:
Extracts text from a candidate's PDF resume using Docling and passes it to an LLM to generate a highly structured JSON profile. Enforces strict 1-decimal-place rounding for all experience calculations.

Request Body

{
  "application_id": "app_123",
  "job_id": "job_999",
  "org_id": "org_555",
  "resume_name": "Yash_Raut_Senior_Java_Developer_Resume_10_Years-1-.pdf"
}

Response — 200 OK

{
  "resume_name": "Yash_Raut_Senior_Java_Developer_Resume_10_Years-1-.pdf",
  "status": "success",
  "parsed_resume": {
    "personal_info": {
      "first_name": "Yash",
      "last_name": "Raut",
      "email": "yash@example.com",
      "phone_number": "+91 9876543210"
    },
    "primary_skills": [
      "Java",
      "Spring Boot",
      "PostgreSQL"
    ],
    "secondary_skills": [
      "Docker",
      "AWS"
    ],
    "domain_expertise": [
      "Fintech"
    ],
    "experience": {
      "total_years": 10.0,
      "roles": [
        {
          "title": "Senior Java Developer",
          "company": "Tech Corp",
          "start_date": "2019",
          "end_date": "present",
          "years": 5.5,
          "highlights": [
            "Developed microservices in Java and Spring Boot.",
            "Managed PostgreSQL databases."
          ]
        }
      ]
    },
    "education_certificates": [
      {
        "name": "B.Tech in Computer Science",
        "type": "degree"
      }
    ]
  }
}

---

3. Candidate-JD Matching API

Endpoint: POST /internal/v1/match/resume-jd

Description:
Performs bulk Job Fit Analysis between parsed resumes and parsed job descriptions using a strict 100-point scoring rubric. The analysis evaluates overall experience as well as experience specific to required Must-Have technologies.

Request Body

{
  "application_id": "app_123",
  "job_id": "job_999",
  "parsed_resume": {
    "...": "Detailed JSON from parse/resume"
  },
  "parsed_jd": {
    "...": "Detailed JSON from parse/jd"
  }
}

Response — 200 OK

{
  "application_id": "app_123",
  "job_id": "job_999",
  "status": "success",
  "job_fit_analysis": {
    "score_breakdown": {
      "must_have_skills_score": 40.0,
      "experience_score": 30.0,
      "good_to_have_skills_score": 20.0,
      "qualifications_score": 10.0
    },
    "match_score": 100.0,
    "reasoning": [
      "Candidate meets all must-have skills including Java and PostgreSQL.",
      "Candidate exceeds the minimum 3 years of required experience.",
      "Educational qualifications strictly match the JD requirements."
    ],
    "matched_skills": {
      "must_have": [
        "Java",
        "Spring Boot",
        "PostgreSQL"
      ],
      "good_to_have": [
        "Docker"
      ]
    },
    "missing_skills": {
      "must_have": [],
      "good_to_have": [
        "AWS",
        "Kafka"
      ]
    },
    "must_have_experience": [
      {
        "skill": "Java",
        "required_years": 3.0,
        "candidate_years": 5.0,
        "skill_experience_ratio": 1.0,
        "meets_requirement": true
      }
    ],
    "qualification_match": true,
    "experience_match": true
  }
}