@odda-ai/matching-core 1.0.0

package/src/features/ai-cv-resume.service.ts

@@ -0,0 +1,104 @@
+import { AIProvider } from "../ai/index.js";
+import {
+  pdfParser,
+  type PDFExtractionOptions,
+} from "../cv-parser/index.js";
+import { prompts } from "./prompts.js";
+import { systemMessages } from "./system-messages.js";
+import { Seniority, type CvAnalysisResponse } from "./types.js";
+
+export type AnalyzeResumeOptions = { pdfoptions?: PDFExtractionOptions };
+
+export class AiCvResumeService {
+  private pdfParser = pdfParser;
+  private ai: AIProvider;
+
+  constructor(ai: AIProvider) {
+    this.ai = ai;
+  }
+
+  async analyzeResume(pdfBuffer: Buffer, options?: AnalyzeResumeOptions) {
+    const pdftext = await this.pdfParser.extractText(
+      pdfBuffer,
+      options?.pdfoptions,
+    );
+    const result = await this.ai.prompt(
+      prompts.cvAnalysis(pdftext.text),
+      systemMessages.analyzeResume(),
+    );
+    return this.parseAiResponse(result.content);
+  }
+
+  private parseAiResponse(aiResponse: string): CvAnalysisResponse {
+    try {
+      // Remove markdown code blocks if present
+      let jsonStr = aiResponse.trim();
+
+      // Try to extract JSON from markdown
+      const jsonMatch = jsonStr.match(/```json\s*([\s\S]*?)```/);
+      if (jsonMatch && jsonMatch[1]) {
+        jsonStr = jsonMatch[1];
+      }
+
+      // Remove any leading/trailing non-JSON content
+      const jsonStart = jsonStr.indexOf("{");
+      const jsonEnd = jsonStr.lastIndexOf("}");
+
+      if (jsonStart === -1 || jsonEnd === -1) {
+        throw new Error("No valid JSON object found in AI response");
+      }
+
+      jsonStr = jsonStr.substring(jsonStart, jsonEnd + 1);
+
+      // Parse JSON
+      const parsed = JSON.parse(jsonStr);
+
+      // Map to DTO structure
+      const analysis: CvAnalysisResponse = {
+        personalInfo: {
+          firstName: parsed.personalInfo?.firstName || "N/A",
+          lastName: parsed.personalInfo?.lastName || "N/A",
+          email: parsed.personalInfo?.email || undefined,
+          phone: parsed.personalInfo?.phone || undefined,
+          address: parsed.personalInfo?.address || undefined,
+          dateOfBirth: parsed.personalInfo?.dateOfBirth || undefined,
+          nationality: parsed.personalInfo?.nationality || undefined,
+          linkedIn: parsed.personalInfo?.linkedIn || undefined,
+          github: parsed.personalInfo?.github || undefined,
+          website: parsed.personalInfo?.website || undefined,
+        },
+        description: parsed.description || "",
+        technicalSkills: (parsed.technicalSkills || []).map((skill: any) => ({
+          name: skill.name,
+          proficiency: Number(skill.proficiency),
+          isInferred: Boolean(skill.isInferred),
+          seniority: this.validateSeniority(skill.seniority),
+        })),
+        workExperienceSummary: parsed.workExperienceSummary || "",
+        certifications: (parsed.certifications || []).map((cert: any) => ({
+          name: cert.name,
+          issuer: cert.issuer || undefined,
+          year: cert.year ? Number(cert.year) : undefined,
+        })),
+        overallSeniority: this.validateSeniority(parsed.overallSeniority),
+        yearsOfExperience: Number(parsed.yearsOfExperience) || 0,
+      };
+
+      return analysis;
+    } catch (error: any) {
+      throw new Error(
+        `Failed to parse AI response into structured format: ${error.message}`,
+      );
+    }
+  }
+
+  private validateSeniority(value: string): Seniority {
+    const upperValue = value?.toUpperCase();
+
+    if (Object.values(Seniority).includes(upperValue as Seniority)) {
+      return upperValue as Seniority;
+    }
+
+    return Seniority.MID;
+  }
+}

package/src/features/ai-talent.service.ts

@@ -0,0 +1,49 @@
+import { AIProvider } from "../ai/index.js";
+import {
+  AiCvResumeService,
+  type AnalyzeResumeOptions,
+} from "./ai-cv-resume.service.js";
+import {
+  type ChunkingOptions,
+  CvChunkingService,
+} from "./cv-chunking.service.js";
+import { JobMatcherService } from "./job-matcher.service.js";
+import type { CvAnalysisResponse } from "./types.js";
+
+export class AiTalentService {
+  private ai: AIProvider;
+  private aiCvResumeService: AiCvResumeService;
+  private cvChunkingService: CvChunkingService;
+  private jobMatcherService: JobMatcherService;
+
+  constructor(ai: AIProvider) {
+    this.ai = ai;
+    this.aiCvResumeService = new AiCvResumeService(this.ai);
+    this.cvChunkingService = new CvChunkingService();
+    this.jobMatcherService = new JobMatcherService(this.ai);
+  }
+
+  public cv = {
+    analyzeCvResume: async (pdf: Buffer, options?: AnalyzeResumeOptions) => {
+      return this.aiCvResumeService.analyzeResume(pdf, options);
+    },
+    chunkCvAnalysis: async (
+      cvAnalysis: CvAnalysisResponse,
+      options?: ChunkingOptions,
+    ) => {
+      return this.cvChunkingService.chunkCvAnalysis(cvAnalysis, options);
+    },
+  };
+
+  public jobs = {
+    getSkillsFromJobDescription: async (
+      jobDescription: string,
+      skillsList: string[],
+    ) => {
+      return this.jobMatcherService.getJobSkillsFromDescription(
+        jobDescription,
+        skillsList,
+      );
+    },
+  };
+}

package/src/features/cv-chunking.service.ts

@@ -0,0 +1,510 @@
+import type { CvAnalysisResponse } from './types.js';
+
+/**
+ * Opzioni per il chunking del CV
+ */
+export interface ChunkingOptions {
+  /**
+   * Dimensione massima di ciascun chunk in caratteri
+   * Default: 500
+   */
+  maxChunkSize?: number;
+
+  /**
+   * Sovrapposizione tra chunk in caratteri per mantenere il contesto
+   * Default: 50
+   */
+  overlap?: number;
+
+  /**
+   * Se true, include metadati nel chunk
+   * Default: true
+   */
+  includeMetadata?: boolean;
+
+  /**
+   * Formato del chunk
+   * Default: 'text'
+   */
+  format?: 'text' | 'json' | 'markdown';
+}
+
+/**
+ * Rappresenta un singolo chunk di testo con metadati
+ */
+export interface CvChunk {
+  /**
+   * ID univoco del chunk
+   */
+  id: string;
+
+  /**
+   * Contenuto testuale del chunk
+   */
+  content: string;
+
+  /**
+   * Tipo di sezione del CV
+   */
+  section: 'personal' | 'description' | 'skills' | 'experience' | 'certifications' | 'summary';
+
+  /**
+   * Metadati del chunk per facilitare il retrieval
+   */
+  metadata: {
+    /**
+     * Indice del chunk nella sequenza
+     */
+    index: number;
+
+    /**
+     * Numero totale di chunk
+     */
+    totalChunks: number;
+
+    /**
+     * Parole chiave estratte dal chunk
+     */
+    keywords: string[];
+
+    /**
+     * Seniority associata (se applicabile)
+     */
+    seniority?: string;
+
+    /**
+     * Anni di esperienza (se applicabile)
+     */
+    yearsOfExperience?: number;
+  };
+}
+
+/**
+ * Risultato del processo di chunking
+ */
+export interface ChunkingResult {
+  /**
+   * Array di chunk generati
+   */
+  chunks: CvChunk[];
+
+  /**
+   * Statistiche sul chunking
+   */
+  stats: {
+    totalChunks: number;
+    averageChunkSize: number;
+    totalCharacters: number;
+  };
+}
+
+/**
+ * Servizio per convertire CvAnalysisResponse in chunk di testo
+ * ottimizzati per embedding e retrieval
+ */
+export class CvChunkingService {
+  private defaultOptions: Required<ChunkingOptions> = {
+    maxChunkSize: 500,
+    overlap: 50,
+    includeMetadata: true,
+    format: 'text'
+  };
+
+  /**
+   * Converte un CvAnalysisResponse in chunk ottimizzati per embedding
+   */
+  async chunkCvAnalysis(
+    cvAnalysis: CvAnalysisResponse,
+    options?: ChunkingOptions
+  ): Promise<ChunkingResult> {
+    const opts = { ...this.defaultOptions, ...options };
+    const chunks: CvChunk[] = [];
+    let chunkIndex = 0;
+
+    // 1. Chunk delle informazioni personali
+    const personalChunk = this.createPersonalInfoChunk(cvAnalysis, chunkIndex++);
+    if (personalChunk) chunks.push(personalChunk);
+
+    // 2. Chunk della descrizione
+    const descriptionChunks = this.chunkText(
+      cvAnalysis.description,
+      'description',
+      chunkIndex,
+      opts,
+      { seniority: cvAnalysis.overallSeniority }
+    );
+    chunks.push(...descriptionChunks);
+    chunkIndex += descriptionChunks.length;
+
+    // 3. Chunk delle skill tecniche (raggruppate per seniority)
+    const skillChunks = this.chunkSkills(cvAnalysis, chunkIndex, opts);
+    chunks.push(...skillChunks);
+    chunkIndex += skillChunks.length;
+
+    // 4. Chunk dell'esperienza lavorativa
+    const experienceChunks = this.chunkText(
+      cvAnalysis.workExperienceSummary,
+      'experience',
+      chunkIndex,
+      opts,
+      {
+        seniority: cvAnalysis.overallSeniority,
+        yearsOfExperience: cvAnalysis.yearsOfExperience
+      }
+    );
+    chunks.push(...experienceChunks);
+    chunkIndex += experienceChunks.length;
+
+    // 5. Chunk delle certificazioni
+    const certificationChunks = this.chunkCertifications(cvAnalysis, chunkIndex, opts);
+    chunks.push(...certificationChunks);
+    chunkIndex += certificationChunks.length;
+
+    // 6. Chunk di summary generale
+    const summaryChunk = this.createSummaryChunk(cvAnalysis, chunkIndex++);
+    chunks.push(summaryChunk);
+
+    // Aggiorna il totalChunks in tutti i chunk
+    const totalChunks = chunks.length;
+    chunks.forEach(chunk => {
+      chunk.metadata.totalChunks = totalChunks;
+    });
+
+    return {
+      chunks,
+      stats: this.calculateStats(chunks)
+    };
+  }
+
+  /**
+   * Crea un chunk con le informazioni personali
+   */
+  private createPersonalInfoChunk(
+    cvAnalysis: CvAnalysisResponse,
+    index: number
+  ): CvChunk | null {
+    const info = cvAnalysis.personalInfo;
+    const parts: string[] = [];
+
+    if (info.firstName || info.lastName) {
+      parts.push(`Nome: ${[info.firstName, info.lastName].filter(Boolean).join(' ')}`);
+    }
+    if (info.email) parts.push(`Email: ${info.email}`);
+    if (info.phone) parts.push(`Telefono: ${info.phone}`);
+    if (info.address) parts.push(`Indirizzo: ${info.address}`);
+    if (info.linkedIn) parts.push(`LinkedIn: ${info.linkedIn}`);
+    if (info.github) parts.push(`GitHub: ${info.github}`);
+    if (info.website) parts.push(`Sito web: ${info.website}`);
+    if (info.nationality) parts.push(`Nazionalità: ${info.nationality}`);
+
+    if (parts.length === 0) return null;
+
+    const content = parts.join('\n');
+    const keywords = this.extractKeywords(content);
+
+    return {
+      id: `chunk-${index}`,
+      content,
+      section: 'personal',
+      metadata: {
+        index,
+        totalChunks: 0, // Verrà aggiornato dopo
+        keywords
+      }
+    };
+  }
+
+  /**
+   * Crea chunk per le skill tecniche
+   */
+  private chunkSkills(
+    cvAnalysis: CvAnalysisResponse,
+    startIndex: number,
+    options: Required<ChunkingOptions>
+  ): CvChunk[] {
+    const chunks: CvChunk[] = [];
+    const skillsBySeniority = new Map<string, typeof cvAnalysis.technicalSkills>();
+
+    // Raggruppa skill per seniority
+    cvAnalysis.technicalSkills.forEach(skill => {
+      const key = skill.seniority;
+      if (!skillsBySeniority.has(key)) {
+        skillsBySeniority.set(key, []);
+      }
+      skillsBySeniority.get(key)!.push(skill);
+    });
+
+    let index = startIndex;
+    for (const [seniority, skills] of skillsBySeniority) {
+      const skillTexts = skills.map(s => 
+        `${s.name} (proficiency: ${s.proficiency}/10${s.isInferred ? ', inferred' : ''})`
+      );
+
+      const content = `Skills ${seniority}:\n${skillTexts.join('\n')}`;
+      const keywords = skills.map(s => s.name.toLowerCase());
+
+      chunks.push({
+        id: `chunk-${index}`,
+        content,
+        section: 'skills',
+        metadata: {
+          index,
+          totalChunks: 0,
+          keywords,
+          seniority
+        }
+      });
+      index++;
+    }
+
+    return chunks;
+  }
+
+  /**
+   * Crea chunk per le certificazioni
+   */
+  private chunkCertifications(
+    cvAnalysis: CvAnalysisResponse,
+    startIndex: number,
+    options: Required<ChunkingOptions>
+  ): CvChunk[] {
+    if (cvAnalysis.certifications.length === 0) return [];
+
+    const chunks: CvChunk[] = [];
+    let currentChunk: string[] = [];
+    let currentSize = 0;
+    let index = startIndex;
+
+    cvAnalysis.certifications.forEach(cert => {
+      const certText = `${cert.name}${cert.issuer ? ` - ${cert.issuer}` : ''}${cert.year ? ` (${cert.year})` : ''}`;
+      
+      if (currentSize + certText.length > options.maxChunkSize && currentChunk.length > 0) {
+        // Crea il chunk corrente
+        const content = `Certificazioni:\n${currentChunk.join('\n')}`;
+        chunks.push({
+          id: `chunk-${index}`,
+          content,
+          section: 'certifications',
+          metadata: {
+            index,
+            totalChunks: 0,
+            keywords: this.extractKeywords(content)
+          }
+        });
+        index++;
+        currentChunk = [];
+        currentSize = 0;
+      }
+
+      currentChunk.push(certText);
+      currentSize += certText.length;
+    });
+
+    // Aggiungi l'ultimo chunk
+    if (currentChunk.length > 0) {
+      const content = `Certificazioni:\n${currentChunk.join('\n')}`;
+      chunks.push({
+        id: `chunk-${index}`,
+        content,
+        section: 'certifications',
+        metadata: {
+          index,
+          totalChunks: 0,
+          keywords: this.extractKeywords(content)
+        }
+      });
+    }
+
+    return chunks;
+  }
+
+  /**
+   * Crea un chunk di summary generale
+   */
+  private createSummaryChunk(
+    cvAnalysis: CvAnalysisResponse,
+    index: number
+  ): CvChunk {
+    const topSkills = cvAnalysis.technicalSkills
+      .sort((a, b) => b.proficiency - a.proficiency)
+      .slice(0, 5)
+      .map(s => s.name)
+      .join(', ');
+
+    const content = [
+      `PROFILO PROFESSIONALE`,
+      `Seniority: ${cvAnalysis.overallSeniority}`,
+      `Anni di esperienza: ${cvAnalysis.yearsOfExperience}`,
+      `Top skills: ${topSkills}`,
+      `Numero certificazioni: ${cvAnalysis.certifications.length}`
+    ].join('\n');
+
+    return {
+      id: `chunk-${index}`,
+      content,
+      section: 'summary',
+      metadata: {
+        index,
+        totalChunks: 0,
+        keywords: [...topSkills.toLowerCase().split(', '), cvAnalysis.overallSeniority.toLowerCase()],
+        seniority: cvAnalysis.overallSeniority,
+        yearsOfExperience: cvAnalysis.yearsOfExperience
+      }
+    };
+  }
+
+  /**
+   * Suddivide un testo lungo in chunk con overlap
+   */
+  private chunkText(
+    text: string,
+    section: CvChunk['section'],
+    startIndex: number,
+    options: Required<ChunkingOptions>,
+    additionalMetadata?: { seniority?: string; yearsOfExperience?: number }
+  ): CvChunk[] {
+    if (!text || text.trim().length === 0) return [];
+
+    const chunks: CvChunk[] = [];
+    const words = text.split(/\s+/);
+    let currentChunk: string[] = [];
+    let currentSize = 0;
+    let index = startIndex;
+
+    for (let i = 0; i < words.length; i++) {
+      const word = words[i]!;
+      const wordSize = word.length + 1; // +1 per lo spazio
+
+      if (currentSize + wordSize > options.maxChunkSize && currentChunk.length > 0) {
+        // Salva il chunk corrente
+        const content = currentChunk.join(' ');
+        chunks.push({
+          id: `chunk-${index}`,
+          content,
+          section,
+          metadata: {
+            index,
+            totalChunks: 0,
+            keywords: this.extractKeywords(content),
+            ...additionalMetadata
+          }
+        });
+        index++;
+
+        // Crea overlap prendendo le ultime parole
+        const overlapWords = Math.floor(options.overlap / 10); // Approssimazione
+        currentChunk = currentChunk.slice(-overlapWords);
+        currentSize = currentChunk.join(' ').length;
+      }
+
+      currentChunk.push(word);
+      currentSize += wordSize;
+    }
+
+    // Aggiungi l'ultimo chunk
+    if (currentChunk.length > 0) {
+      const content = currentChunk.join(' ');
+      chunks.push({
+        id: `chunk-${index}`,
+        content,
+        section,
+        metadata: {
+          index,
+          totalChunks: 0,
+          keywords: this.extractKeywords(content),
+          ...additionalMetadata
+        }
+      });
+    }
+
+    return chunks;
+  }
+
+  /**
+   * Estrae parole chiave da un testo
+   */
+  private extractKeywords(text: string): string[] {
+    // Rimuovi parole comuni e estrai parole significative
+    const stopWords = new Set([
+      'il', 'la', 'di', 'da', 'in', 'con', 'per', 'a', 'e', 'o',
+      'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for'
+    ]);
+
+    const words = text.toLowerCase()
+      .replace(/[^\w\s]/g, ' ')
+      .split(/\s+/)
+      .filter(word => word.length > 3 && !stopWords.has(word));
+
+    // Conta frequenza e prendi le top 5
+    const frequency = new Map<string, number>();
+    words.forEach(word => {
+      frequency.set(word, (frequency.get(word) || 0) + 1);
+    });
+
+    return Array.from(frequency.entries())
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 5)
+      .map(([word]) => word);
+  }
+
+  /**
+   * Calcola statistiche sui chunk generati
+   */
+  private calculateStats(chunks: CvChunk[]): ChunkingResult['stats'] {
+    const totalChunks = chunks.length;
+    const totalCharacters = chunks.reduce((sum, chunk) => sum + chunk.content.length, 0);
+    const averageChunkSize = totalChunks > 0 ? Math.round(totalCharacters / totalChunks) : 0;
+
+    return {
+      totalChunks,
+      averageChunkSize,
+      totalCharacters
+    };
+  }
+
+  /**
+   * Converte i chunk in formato JSON per embedding
+   */
+  toEmbeddingFormat(chunks: CvChunk[]): Array<{ id: string; text: string; metadata: any }> {
+    return chunks.map(chunk => ({
+      id: chunk.id,
+      text: chunk.content,
+      metadata: {
+        section: chunk.section,
+        ...chunk.metadata
+      }
+    }));
+  }
+
+  /**
+   * Cerca chunk rilevanti per una query
+   */
+  searchChunks(chunks: CvChunk[], query: string, limit: number = 5): CvChunk[] {
+    const queryKeywords = this.extractKeywords(query.toLowerCase());
+    
+    // Score basato su keyword match
+    const scored = chunks.map(chunk => {
+      const matchScore = queryKeywords.reduce((score, keyword) => {
+        if (chunk.content.toLowerCase().includes(keyword)) {
+          return score + 1;
+        }
+        if (chunk.metadata.keywords.some(k => k.includes(keyword))) {
+          return score + 0.5;
+        }
+        return score;
+      }, 0);
+
+      return { chunk, score: matchScore };
+    });
+
+    return scored
+      .sort((a, b) => b.score - a.score)
+      .slice(0, limit)
+      .map(({ chunk }) => chunk);
+  }
+}
+
+/**
+ * Istanza singleton del servizio
+ */
+export const cvChunkingService = new CvChunkingService();

package/src/features/index.ts

@@ -0,0 +1,5 @@
+export { AiTalentService } from "./ai-talent.service.js";
+export type { AnalyzeResumeOptions } from "./ai-cv-resume.service.js";
+export { CvChunkingService, cvChunkingService } from "./cv-chunking.service.js";
+export type { ChunkingOptions, CvChunk, ChunkingResult } from "./cv-chunking.service.js";
+export * from "./types.js";

package/src/features/job-matcher.service.ts

@@ -0,0 +1,41 @@
+import { AIProvider } from "../ai/index.js";
+import { prompts } from "./prompts.js";
+import { systemMessages } from "./system-messages.js";
+import { JobSkillType } from "./types.js";
+
+export type SkillMatch = {
+  skill: string;
+  multiplier: number; // valore compreso tra 0.00 e 1.00
+  jobSkillType: JobSkillType;
+};
+
+export class JobMatcherService {
+  private ai: AIProvider;
+
+  constructor(ai: AIProvider) {
+    this.ai = ai;
+  }
+
+  async getJobSkillsFromDescription(
+    jobDescription: string,
+    skillsList: string[],
+  ) {
+    const result = await this.ai.prompt(
+      prompts.jobMatching(jobDescription, skillsList),
+      systemMessages.jobMatching(),
+    );
+    return this.convertAiResponseToSkills(result.content);
+  }
+
+  private convertAiResponseToSkills(aiResponse: string): SkillMatch[] {
+    return JSON.parse(aiResponse) as SkillMatch[];
+  }
+
+
+  async rateCandidateToJob(
+    candidateSkills: SkillMatch[],
+    jobSkills: SkillMatch[],
+  ) {
+    
+  }
+}