recommender-api-client

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

---

🚀 Installation

``bash
npm install @exceleratedk/recommender-api-client
`

---

📦 Usage

`typescript
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
- config ({ candidateId: string; limit?: number; }):
- candidateId: The candidate's unique ID (required)
- limit: Number of recommendations to return (default: 5)
- Returns: Promise with recommendations and suggestions

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

---

📋 Types

$3

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

$3

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

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

$3

`typescript
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[]; // Enhanced missing features analysis
}
`

$3

`typescript
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:

`typescript
// 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);
`

$3

`typescript
{
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

`bash
npm test
``

---