@pranavraut033/ats-checker 0.1.0 → 1.0.0

package/dist/index.js

@@ -717,6 +717,519 @@ var SuggestionEngine = class {
   }
 };
 
+// src/llm/llm.budget.ts
+var LLMBudgetManager = class {
+  constructor(limits) {
+    this.callCount = 0;
+    this.totalTokensUsed = 0;
+    this.limits = limits;
+  }
+  /**
+   * Check if we can make a call with the given token estimate
+   * Throws if budget would be exceeded
+   */
+  assertCanCall(requestedTokens) {
+    if (this.callCount >= this.limits.maxCalls) {
+      throw new Error(
+        `LLM call limit exceeded: ${this.callCount}/${this.limits.maxCalls} calls used`
+      );
+    }
+    if (requestedTokens > this.limits.maxTokensPerCall) {
+      throw new Error(
+        `Requested tokens ${requestedTokens} exceeds per-call limit ${this.limits.maxTokensPerCall}`
+      );
+    }
+    if (this.totalTokensUsed + requestedTokens > this.limits.maxTotalTokens) {
+      throw new Error(
+        `Total token budget exceeded: ${this.totalTokensUsed + requestedTokens}/${this.limits.maxTotalTokens}`
+      );
+    }
+  }
+  /**
+   * Record actual token usage from a completed call
+   */
+  recordUsage(tokensUsed) {
+    this.callCount += 1;
+    this.totalTokensUsed += tokensUsed;
+  }
+  /**
+   * Get current budget state
+   */
+  getStats() {
+    return {
+      callsUsed: this.callCount,
+      callsRemaining: Math.max(0, this.limits.maxCalls - this.callCount),
+      tokensUsed: this.totalTokensUsed,
+      tokensRemaining: Math.max(0, this.limits.maxTotalTokens - this.totalTokensUsed),
+      totalCalls: this.limits.maxCalls,
+      totalTokens: this.limits.maxTotalTokens
+    };
+  }
+  /**
+   * Check if budget is exhausted
+   */
+  isExhausted() {
+    return this.callCount >= this.limits.maxCalls || this.totalTokensUsed >= this.limits.maxTotalTokens;
+  }
+  /**
+   * Reset budget (for testing)
+   */
+  reset() {
+    this.callCount = 0;
+    this.totalTokensUsed = 0;
+  }
+};
+
+// src/llm/llm.manager.ts
+var LLMManager = class {
+  constructor(config) {
+    this.warnings = [];
+    this.config = config;
+    this.client = config.client;
+    this.budgetManager = new LLMBudgetManager(config.limits);
+    this.timeoutMs = config.timeoutMs ?? 3e4;
+  }
+  /**
+   * Structured call to LLM with timeout and budget protection
+   */
+  async callLLM(systemPrompt, userPrompt, schema, options = {}) {
+    try {
+      const estimatedTokens = this.estimateTokens(systemPrompt, userPrompt, options.requestedTokens);
+      try {
+        this.budgetManager.assertCanCall(estimatedTokens);
+      } catch (e) {
+        const msg = `LLM budget exhausted: ${e.message}`;
+        this.warnings.push(msg);
+        return { success: false, fallback: true, error: msg };
+      }
+      if (!this.isValidJsonSchema(schema)) {
+        const msg = "Invalid JSON schema provided";
+        this.warnings.push(msg);
+        return { success: false, fallback: true, error: msg };
+      }
+      const strictUserPrompt = `${userPrompt}
+
+Return ONLY valid JSON matching the schema below.
+No explanations. No markdown. No additional text.`;
+      const response = await Promise.race([
+        this.client.createCompletion({
+          model: options.useThinking ? this.config.models?.thinking || this.config.models?.default || "gpt-4o" : this.config.models?.default || "gpt-4o",
+          messages: [
+            { role: "system", content: systemPrompt },
+            { role: "user", content: strictUserPrompt }
+          ],
+          max_tokens: options.requestedTokens || 2e3,
+          response_format: schema
+        }),
+        this.createTimeout(this.timeoutMs)
+      ]);
+      if (!response || !response.content) {
+        return { success: false, fallback: true, error: "Empty response from LLM" };
+      }
+      let parsedContent;
+      try {
+        if (typeof response.content === "string") {
+          parsedContent = JSON.parse(response.content);
+        } else {
+          parsedContent = response.content;
+        }
+      } catch (e) {
+        const msg = `Invalid JSON in LLM response: ${e.message}`;
+        this.warnings.push(msg);
+        return { success: false, fallback: true, error: msg };
+      }
+      if (!this.validateAgainstSchema(parsedContent, schema)) {
+        const msg = "LLM response does not match schema";
+        this.warnings.push(msg);
+        return { success: false, fallback: true, error: msg };
+      }
+      const tokensUsed = response.usage?.total_tokens || estimatedTokens;
+      this.budgetManager.recordUsage(tokensUsed);
+      return {
+        success: true,
+        fallback: false,
+        data: parsedContent,
+        tokensUsed
+      };
+    } catch (e) {
+      const msg = `LLM call failed: ${e.message}`;
+      this.warnings.push(msg);
+      return { success: false, fallback: true, error: msg };
+    }
+  }
+  /**
+   * Get list of warnings from LLM operations
+   */
+  getWarnings() {
+    return [...this.warnings];
+  }
+  /**
+   * Get budget stats
+   */
+  getBudgetStats() {
+    return this.budgetManager.getStats();
+  }
+  /**
+   * Check if features are enabled
+   */
+  isFeatureEnabled(feature) {
+    return this.config.enable?.[feature] === true;
+  }
+  // ============ Private helpers ============
+  /**
+   * Create a timeout promise
+   */
+  createTimeout(ms) {
+    return new Promise((_, reject) => {
+      globalThis.setTimeout(() => reject(new Error(`LLM call timeout after ${ms}ms`)), ms);
+    });
+  }
+  /**
+   * Estimate tokens for a call (rough approximation)
+   * 1 token ≈ 4 characters average
+   */
+  estimateTokens(systemPrompt, userPrompt, requestedTokens) {
+    if (requestedTokens) {
+      return requestedTokens;
+    }
+    const totalChars = systemPrompt.length + userPrompt.length;
+    const estimatedInputTokens = Math.ceil(totalChars / 4);
+    return estimatedInputTokens + Math.ceil(estimatedInputTokens / 2);
+  }
+  /**
+   * Validate that schema looks like valid JSON schema
+   */
+  isValidJsonSchema(schema) {
+    return schema && schema.type === "object" && !!(schema.properties || schema.required);
+  }
+  /**
+   * Simple schema validation - check required fields exist
+   */
+  validateAgainstSchema(data, schema) {
+    if (typeof data !== "object" || data === null) {
+      return false;
+    }
+    const obj = data;
+    if (schema.required) {
+      for (const field of schema.required) {
+        if (!(field in obj)) {
+          return false;
+        }
+      }
+    }
+    return true;
+  }
+};
+
+// src/llm/llm.schemas.ts
+var skillNormalizationSchema = {
+  type: "object",
+  properties: {
+    canonicalSkills: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          input: {
+            type: "string",
+            description: "Original skill name from input"
+          },
+          normalized: {
+            type: "string",
+            description: "Canonical/normalized skill name"
+          },
+          confidence: {
+            type: "number",
+            description: "Confidence score 0-1 that this is correct"
+          }
+        },
+        required: ["input", "normalized"]
+      },
+      description: "Array of skill normalizations"
+    }
+  },
+  required: ["canonicalSkills"]
+};
+var sectionClassificationSchema = {
+  type: "object",
+  properties: {
+    sections: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          header: {
+            type: "string",
+            description: "The section header text"
+          },
+          classification: {
+            type: "string",
+            enum: ["summary", "experience", "skills", "education", "projects", "certifications", "other"],
+            description: "Classified section type"
+          },
+          confidence: {
+            type: "number",
+            description: "Confidence 0-1 in the classification"
+          }
+        },
+        required: ["header", "classification"]
+      },
+      description: "Array of section classifications"
+    }
+  },
+  required: ["sections"]
+};
+var suggestionEnhancementSchema = {
+  type: "object",
+  properties: {
+    suggestions: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          original: {
+            type: "string",
+            description: "Original suggestion from deterministic engine"
+          },
+          enhanced: {
+            type: "string",
+            description: "Improved phrasing of the suggestion"
+          },
+          actionable: {
+            type: "boolean",
+            description: "Whether the suggestion is concrete and actionable"
+          }
+        },
+        required: ["original", "enhanced"]
+      },
+      description: "Array of enhanced suggestions"
+    }
+  },
+  required: ["suggestions"]
+};
+var jdClarificationSchema = {
+  type: "object",
+  properties: {
+    implicitSkills: {
+      type: "array",
+      items: { type: "string" },
+      description: "Skills implied but not explicitly mentioned"
+    },
+    implicitExperience: {
+      type: "object",
+      properties: {
+        minYears: {
+          type: "number",
+          description: "Inferred minimum experience years"
+        },
+        domains: {
+          type: "array",
+          items: { type: "string" },
+          description: "Industry domains implied"
+        }
+      },
+      description: "Inferred experience requirements"
+    },
+    clarityScore: {
+      type: "number",
+      description: "0-1 score indicating JD clarity"
+    }
+  },
+  required: ["implicitSkills", "clarityScore"]
+};
+var validationSchema = {
+  type: "object",
+  properties: {
+    valid: {
+      type: "boolean",
+      description: "Whether the input is valid"
+    },
+    message: {
+      type: "string",
+      description: "Validation message"
+    }
+  },
+  required: ["valid"]
+};
+var LLMSchemas = {
+  skillNormalization: skillNormalizationSchema,
+  sectionClassification: sectionClassificationSchema,
+  suggestionEnhancement: suggestionEnhancementSchema,
+  jdClarification: jdClarificationSchema,
+  validation: validationSchema
+};
+
+// src/llm/llm.prompts.ts
+var LLMPrompts = {
+  /**
+   * System prompt for skill normalization
+   */
+  skillNormalizationSystem: `You are a technical skill normalization expert.
+Your task is to normalize and canonicalize technical skill names.
+Handle aliases, abbreviations, and variations.
+Be conservative - only group skills that are genuinely synonymous.
+Return ONLY valid JSON.`,
+  /**
+   * User prompt for skill normalization
+   */
+  skillNormalizationUser: (skills) => `Normalize these skills:
+${skills.map((s) => `- ${s}`).join("\n")}
+
+Return the canonical names with confidence scores.`,
+  /**
+   * System prompt for section classification
+   */
+  sectionClassificationSystem: `You are a resume section classifier.
+Classify ambiguous section headers into standard resume categories.
+Be strict - if uncertain, classify as "other".
+Provide confidence scores.
+Return ONLY valid JSON.`,
+  /**
+   * User prompt for section classification
+   */
+  sectionClassificationUser: (headers) => `Classify these resume section headers:
+${headers.map((h) => `- "${h}"`).join("\n")}
+
+Use categories: summary, experience, skills, education, projects, certifications, other.`,
+  /**
+   * System prompt for suggestion enhancement
+   */
+  suggestionEnhancementSystem: `You are a resume advice expert.
+Improve suggestions to be more actionable and specific.
+Maintain the core message but make it more concrete.
+Return ONLY valid JSON.`,
+  /**
+   * User prompt for suggestion enhancement
+   */
+  suggestionEnhancementUser: (suggestions) => `Enhance these suggestions for clarity and actionability:
+${suggestions.map((s) => `- ${s}`).join("\n")}
+
+Make them specific and measurable where possible.`,
+  /**
+   * System prompt for JD clarification
+   */
+  jdClarificationSystem: `You are a job description analyzer.
+Extract implicit requirements not explicitly stated.
+Be conservative - stick to reasonable inferences.
+Rate the clarity of the job description.
+Return ONLY valid JSON.`,
+  /**
+   * User prompt for JD clarification
+   */
+  jdClarificationUser: (jd) => `Analyze this job description for implicit requirements:
+
+${jd}
+
+What skills are implied but not explicitly mentioned?
+What experience domains are indicated?
+How clear is this job description (0-1)?`
+};
+function createPrompt(systemBase, userBuilder, input) {
+  return {
+    system: systemBase,
+    user: userBuilder(input)
+  };
+}
+
+// src/llm/llm.adapters.ts
+function adaptSkillNormalizationResponse(data) {
+  if (!data || typeof data !== "object") {
+    return [];
+  }
+  const obj = data;
+  const canonicalSkills = obj.canonicalSkills;
+  if (!Array.isArray(canonicalSkills)) {
+    return [];
+  }
+  const results = [];
+  for (const item of canonicalSkills) {
+    if (typeof item !== "object" || item === null) continue;
+    const skill = item;
+    const input = skill.input;
+    const normalized = skill.normalized;
+    const confidence = typeof skill.confidence === "number" ? skill.confidence : void 0;
+    if (input && normalized) {
+      results.push({ input, normalized, confidence });
+    }
+  }
+  return results;
+}
+function adaptSectionClassificationResponse(data) {
+  if (!data || typeof data !== "object") {
+    return [];
+  }
+  const obj = data;
+  const sections = obj.sections;
+  if (!Array.isArray(sections)) {
+    return [];
+  }
+  const results = [];
+  for (const item of sections) {
+    if (typeof item !== "object" || item === null) continue;
+    const section = item;
+    const header = section.header;
+    const classification = section.classification;
+    const confidence = typeof section.confidence === "number" ? section.confidence : void 0;
+    if (header && classification) {
+      results.push({ header, classification, confidence });
+    }
+  }
+  return results;
+}
+function adaptSuggestionEnhancementResponse(data) {
+  if (!data || typeof data !== "object") {
+    return [];
+  }
+  const obj = data;
+  const suggestions = obj.suggestions;
+  if (!Array.isArray(suggestions)) {
+    return [];
+  }
+  const results = [];
+  for (const item of suggestions) {
+    if (typeof item !== "object" || item === null) continue;
+    const suggestion = item;
+    const original = suggestion.original;
+    const enhanced = suggestion.enhanced;
+    const actionable = typeof suggestion.actionable === "boolean" ? suggestion.actionable : void 0;
+    if (original && enhanced) {
+      results.push({ original, enhanced, actionable });
+    }
+  }
+  return results;
+}
+function adaptJdClarificationResponse(data) {
+  if (!data || typeof data !== "object") {
+    return { implicitSkills: [] };
+  }
+  const obj = data;
+  const implicitSkills = Array.isArray(obj.implicitSkills) ? obj.implicitSkills.filter((s) => typeof s === "string") : [];
+  const implicitExperience = obj.implicitExperience && typeof obj.implicitExperience === "object" ? obj.implicitExperience : void 0;
+  const minYears = implicitExperience && typeof implicitExperience.minYears === "number" ? implicitExperience.minYears : void 0;
+  const domains = implicitExperience && Array.isArray(implicitExperience.domains) ? implicitExperience.domains : void 0;
+  const clarityScore = typeof obj.clarityScore === "number" ? obj.clarityScore : void 0;
+  return {
+    implicitSkills,
+    implicitExperience: minYears || domains ? { minYears, domains } : void 0,
+    clarityScore
+  };
+}
+function safeExtractString(obj, key) {
+  if (typeof obj !== "object" || obj === null) return void 0;
+  const value = obj[key];
+  return typeof value === "string" ? value : void 0;
+}
+function safeExtractArray(obj, key) {
+  if (typeof obj !== "object" || obj === null) return [];
+  const value = obj[key];
+  return Array.isArray(value) ? value : [];
+}
+function safeExtractNumber(obj, key) {
+  if (typeof obj !== "object" || obj === null) return void 0;
+  const value = obj[key];
+  return typeof value === "number" ? value : void 0;
+}
+
 // src/index.ts
 function analyzeResume(input) {
   const resolvedConfig = resolveConfig(input.config ?? {});
@@ -738,6 +1251,15 @@ function analyzeResume(input) {
     score: scoring,
     ruleWarnings: ruleResult.warnings
   });
+  let suggestions = suggestionResult.suggestions;
+  const llmWarnings = [];
+  if (input.llm && suggestionResult.suggestions.length > 0) {
+    const llmResult = enhanceSuggestionsWithLLM(input.llm, suggestionResult.suggestions);
+    if (llmResult.success) {
+      suggestions = llmResult.enhancedSuggestions || suggestions;
+    }
+    llmWarnings.push(...llmResult.warnings);
+  }
   const finalScore = clamp(scoring.score - ruleResult.totalPenalty, 0, 100);
   return {
     score: finalScore,
@@ -745,13 +1267,120 @@ function analyzeResume(input) {
     matchedKeywords: scoring.matchedKeywords,
     missingKeywords: scoring.missingKeywords,
     overusedKeywords: scoring.overusedKeywords,
-    suggestions: suggestionResult.suggestions,
-    warnings: suggestionResult.warnings
+    suggestions,
+    warnings: [...suggestionResult.warnings, ...llmWarnings]
   };
 }
+function enhanceSuggestionsWithLLM(config, suggestions) {
+  if (!config.enable?.suggestions) {
+    return { success: false, warnings: [] };
+  }
+  const warnings = [];
+  try {
+    const llmManager = new LLMManager(config);
+    warnings.push(
+      "LLM suggestion enhancement skipped - use async analyzeResumeAsync for LLM features"
+    );
+    return { success: false, warnings };
+  } catch (e) {
+    warnings.push(`Failed to enhance suggestions: ${e.message}`);
+    return { success: false, warnings };
+  }
+}
+async function analyzeResumeAsync(input) {
+  const resolvedConfig = resolveConfig(input.config ?? {});
+  const parsedResume = parseResume(input.resumeText, resolvedConfig);
+  const parsedJob = parseJobDescription(input.jobDescription, resolvedConfig);
+  const scoring = calculateScore(parsedResume, parsedJob, resolvedConfig);
+  const ruleEngine = new RuleEngine(resolvedConfig);
+  const ruleResult = ruleEngine.evaluate({
+    resume: parsedResume,
+    job: parsedJob,
+    breakdown: scoring.breakdown,
+    matchedKeywords: scoring.matchedKeywords,
+    overusedKeywords: scoring.overusedKeywords
+  });
+  const suggestionEngine = new SuggestionEngine();
+  const suggestionResult = suggestionEngine.generate({
+    resume: parsedResume,
+    job: parsedJob,
+    score: scoring,
+    ruleWarnings: ruleResult.warnings
+  });
+  let suggestions = suggestionResult.suggestions;
+  const llmWarnings = [];
+  if (input.llm && suggestionResult.suggestions.length > 0) {
+    const llmResult = await enhanceSuggestionsWithLLMAsync(
+      input.llm,
+      suggestionResult.suggestions
+    );
+    if (llmResult.success) {
+      suggestions = llmResult.enhancedSuggestions || suggestions;
+    }
+    llmWarnings.push(...llmResult.warnings);
+  }
+  const finalScore = clamp(scoring.score - ruleResult.totalPenalty, 0, 100);
+  return {
+    score: finalScore,
+    breakdown: scoring.breakdown,
+    matchedKeywords: scoring.matchedKeywords,
+    missingKeywords: scoring.missingKeywords,
+    overusedKeywords: scoring.overusedKeywords,
+    suggestions,
+    warnings: [...suggestionResult.warnings, ...llmWarnings]
+  };
+}
+async function enhanceSuggestionsWithLLMAsync(config, suggestions) {
+  if (!config.enable?.suggestions) {
+    return { success: false, warnings: [] };
+  }
+  const warnings = [];
+  try {
+    const llmManager = new LLMManager(config);
+    const result = await llmManager.callLLM(
+      LLMPrompts.suggestionEnhancementSystem,
+      LLMPrompts.suggestionEnhancementUser(suggestions),
+      LLMSchemas.suggestionEnhancement,
+      { requestedTokens: 2e3 }
+    );
+    if (!result.success || !result.data) {
+      if (result.error) {
+        warnings.push(`LLM suggestion enhancement failed: ${result.error}`);
+      }
+      return { success: false, warnings: [...warnings, ...llmManager.getWarnings()] };
+    }
+    const enhanced = adaptSuggestionEnhancementResponse(result.data);
+    const enhancedSuggestions = enhanced.filter((e) => e.actionable !== false).map((e) => e.enhanced);
+    if (enhancedSuggestions.length === 0) {
+      warnings.push("LLM returned no actionable enhanced suggestions");
+      return { success: false, warnings: [...warnings, ...llmManager.getWarnings()] };
+    }
+    return {
+      success: true,
+      enhancedSuggestions,
+      warnings: llmManager.getWarnings()
+    };
+  } catch (e) {
+    warnings.push(`Unexpected error in LLM enhancement: ${e.message}`);
+    return { success: false, warnings };
+  }
+}
 
+exports.LLMBudgetManager = LLMBudgetManager;
+exports.LLMManager = LLMManager;
+exports.LLMPrompts = LLMPrompts;
+exports.LLMSchemas = LLMSchemas;
+exports.adaptJdClarificationResponse = adaptJdClarificationResponse;
+exports.adaptSectionClassificationResponse = adaptSectionClassificationResponse;
+exports.adaptSkillNormalizationResponse = adaptSkillNormalizationResponse;
+exports.adaptSuggestionEnhancementResponse = adaptSuggestionEnhancementResponse;
 exports.analyzeResume = analyzeResume;
+exports.analyzeResumeAsync = analyzeResumeAsync;
+exports.createPrompt = createPrompt;
 exports.defaultProfiles = defaultProfiles;
 exports.defaultSkillAliases = defaultSkillAliases;
+exports.safeExtractArray = safeExtractArray;
+exports.safeExtractNumber = safeExtractNumber;
+exports.safeExtractString = safeExtractString;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map