recommender-api-client

A modern TypeScript/JavaScript client for the internal Recommender System API.

🚀 Installation

npm install @exceleratedk/recommender-api-client

📦 Usage

import { RecommenderAPI } from 'recommender-api-client';

const api = new RecommenderAPI({
  baseURL: 'http://localhost:8000',
  token: 'YOUR_API_TOKEN',
});

// Get job recommendations for a candidate
const jobResponse = await api.getJobRecommendations({ candidateId: 'candidate123' });
console.log('Job recommendations:', jobResponse.recommendations);
console.log('Suggestions:', jobResponse.suggestions);

// Get candidate recommendations for a job
const candidateResponse = await api.getCandidateRecommendations({ jobId: 'job456', limit: 10 });
console.log('Candidate recommendations:', candidateResponse.recommendations);
console.log('Suggestions:', candidateResponse.suggestions);

🛠️ API Reference

new RecommenderAPI(config)

• config ({ baseURL: string; token: string; }):
  • baseURL: The base URL of the API (e.g., 'http://localhost:8000')
  • token: Bearer token for authentication

getJobRecommendations(config): Promise<RecommenderResponse>

• config ({ candidateId: string; limit?: number; }):
  • candidateId: The candidate's unique ID (required)
  • limit: Number of recommendations to return (default: 5)
• Returns: Promise<RecommenderResponse> with recommendations and suggestions

getCandidateRecommendations(config): Promise<RecommenderResponse>

• config ({ jobId: string; limit?: number; }):
  • jobId: The job's unique ID (required)
  • limit: Number of recommendations to return (default: 5)
• Returns: Promise<RecommenderResponse> with recommendations and suggestions

📋 Types

Response Structure

export interface RecommenderResponse {
  recommendations: JobRecommendation[] | CandidateRecommendation[];
  suggestions: string[];
}

Core Recommendation Types

export interface JobRecommendation {
  jobId: string;
  score?: number;
  explanation?: RecommendationExplanation;
}

export interface CandidateRecommendation {
  candidateId: string;
  score?: number;
  explanation?: RecommendationExplanation;
}

Explanation Types

export interface ExplanationFactor {
  factor_type: string;        // e.g., "skill_match", "industry_match", "interest_match"
  factor_name: string;        // e.g., "Python", "Technology", "Machine Learning"
  factor_value: number;       // Contribution score
  factor_description: string; // Human-readable description
  factor_weight: number;      // Weight of the factor
}

export interface RecommendationExplanation {
  recommendation_id: string;           // ID of the recommended item
  explanation_type: string;            // Type of explanation
  factors: ExplanationFactor[];        // Contributing factors
  total_score: number;                 // Overall recommendation score
  explanation_summary: string;         // Human-readable summary
  missing_features: Record<string, any>[]; // Enhanced missing features analysis
}

Configuration Types

export interface RecommenderAPIConfig {
  baseURL: string;
  token: string;
}

export interface JobRecommendationConfig {
  candidateId: string;
  limit?: number;
}

export interface CandidateRecommendationConfig {
  jobId: string;
  limit?: number;
}

🔍 Working with Responses

The API now returns complete responses with both recommendations and suggestions. Here's how to work with them:

// Get job recommendations with explanations and suggestions
const jobResponse = await api.getJobRecommendations({ 
  candidateId: 'candidate123',
  limit: 3 
});

// Access recommendations
jobResponse.recommendations.forEach(recommendation => {
  console.log(`Job: ${recommendation.jobId}, Score: ${recommendation.score}`);
  
  if (recommendation.explanation) {
    console.log(`Summary: ${recommendation.explanation.explanation_summary}`);
    console.log(`Total Score: ${recommendation.explanation.total_score}`);
    
    // List contributing factors
    recommendation.explanation.factors.forEach(factor => {
      console.log(`- ${factor.factor_name}: ${factor.factor_description} (${factor.factor_value})`);
    });
  }
});

// Access suggestions for improvement
console.log('Suggestions:', jobResponse.suggestions);

Example Response Output

{
  recommendations: [
    {
      jobId: "job_123",
      score: 6.03,
      explanation: {
        recommendation_id: "job_123",
        explanation_type: "path_based",
        total_score: 6.03,
        explanation_summary: "Strong match based on: Core Interest Match (1.0), Core Skill Match (1.0), Content Similarity (0.2)",
        factors: [
          {
            factor_type: "interests_core_positive",
            factor_name: "Core Interest Match",
            factor_value: 1,
            factor_description: "Essential interest requirements that align (strength: 1.0, impact: 37.10)",
            factor_weight: 37.1
          },
          {
            factor_type: "skills_core_positive",
            factor_name: "Core Skill Match",
            factor_value: 1,
            factor_description: "Essential skill requirements that align (strength: 1.0, impact: 6.31)",
            factor_weight: 6.31
          }
        ],
        missing_features: []
      }
    }
  ],
  suggestions: [
    "Add more interests to your profile to improve job matching. Include both professional and personal interests."
  ]
}

🧪 Running Tests

npm test