@pranavraut033/ats-checker 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -103,6 +103,112 @@ interface RuleContext {
     overusedKeywords?: string[];
 }
 
+/**
+ * LLM v2 Support Types - Optional, Backward Compatible
+ */
+
+/**
+ * JSON Schema for response validation
+ */
+interface JSONSchema {
+    type: string;
+    properties?: Record<string, unknown>;
+    required?: string[];
+    items?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * LLM Client abstraction - user provides their own implementation
+ * This allows flexibility with different LLM providers without direct dependencies
+ */
+interface LLMClient {
+    /**
+     * Create a structured completion from the LLM
+     * Must validate and return only valid JSON matching the schema
+     */
+    createCompletion(input: {
+        model: string;
+        messages: {
+            role: "system" | "user";
+            content: string;
+        }[];
+        max_tokens: number;
+        response_format: JSONSchema;
+    }): Promise<{
+        content: unknown;
+        usage?: {
+            prompt_tokens?: number;
+            completion_tokens?: number;
+            total_tokens?: number;
+        };
+    }>;
+}
+/**
+ * LLM budget configuration - prevents runaway spending
+ */
+interface LLMBudget {
+    maxCalls: number;
+    maxTokensPerCall: number;
+    maxTotalTokens: number;
+}
+/**
+ * Feature toggles for LLM capabilities
+ */
+interface LLMFeatures {
+    skillNormalization?: boolean;
+    sectionClassification?: boolean;
+    suggestions?: boolean;
+}
+/**
+ * Complete LLM configuration
+ */
+interface LLMConfig {
+    /** User-provided LLM client (e.g., OpenAI wrapper) */
+    client: LLMClient;
+    /** Model identifiers */
+    models?: {
+        /** Default model for fast, structured output (e.g., "gpt-4o-mini") */
+        default: string;
+        /** Optional thinking model for complex reasoning (e.g., "o4-mini") */
+        thinking?: string;
+    };
+    /** Budget constraints */
+    limits: LLMBudget;
+    /** Which LLM features to enable */
+    enable?: LLMFeatures;
+    /** Request timeout in milliseconds */
+    timeoutMs?: number;
+}
+/**
+ * Updated AnalyzeResumeInput with optional LLM support
+ */
+interface AnalyzeResumeInputV2 {
+    resumeText: string;
+    jobDescription: string;
+    config?: ATSConfig;
+    llm?: LLMConfig;
+}
+/**
+ * LLM usage tracking for debugging
+ */
+interface LLMUsageStats {
+    totalCalls: number;
+    totalTokensUsed: number;
+    callsRemaining: number;
+    tokensRemaining: number;
+    features: Partial<Record<keyof LLMFeatures, boolean>>;
+}
+/**
+ * Result of an LLM operation (with fallback info)
+ */
+interface LLMResult<T> {
+    success: boolean;
+    data?: T;
+    fallback: boolean;
+    error?: string;
+    tokensUsed?: number;
+}
+
 interface ATSBreakdown {
     skills: number;
     experience: number;
@@ -113,6 +219,7 @@ interface AnalyzeResumeInput {
     resumeText: string;
     jobDescription: string;
     config?: ATSConfig;
+    llm?: LLMConfig;
 }
 interface ATSAnalysisResult {
     score: number;
@@ -127,9 +234,259 @@ interface ATSAnalysisResult {
 declare const defaultSkillAliases: SkillAliases;
 declare const defaultProfiles: ATSProfile[];
 
+/**
+ * LLM Manager - Orchestrates all LLM operations with budget constraints
+ * Provides safe fallback to v1 deterministic logic on any failure
+ */
+
+interface LLMCallOptions {
+    model?: string;
+    useThinking?: boolean;
+    requestedTokens?: number;
+}
+/**
+ * Core LLM manager - handles all interactions with the LLM client
+ */
+declare class LLMManager {
+    private client;
+    private budgetManager;
+    private config;
+    private timeoutMs;
+    private warnings;
+    constructor(config: LLMConfig);
+    /**
+     * Structured call to LLM with timeout and budget protection
+     */
+    callLLM<T>(systemPrompt: string, userPrompt: string, schema: JSONSchema, options?: LLMCallOptions): Promise<LLMResult<T>>;
+    /**
+     * Get list of warnings from LLM operations
+     */
+    getWarnings(): string[];
+    /**
+     * Get budget stats
+     */
+    getBudgetStats(): {
+        callsUsed: number;
+        callsRemaining: number;
+        tokensUsed: number;
+        tokensRemaining: number;
+        totalCalls: number;
+        totalTokens: number;
+    };
+    /**
+     * Check if features are enabled
+     */
+    isFeatureEnabled(feature: keyof NonNullable<LLMConfig["enable"]>): boolean;
+    /**
+     * Create a timeout promise
+     */
+    private createTimeout;
+    /**
+     * Estimate tokens for a call (rough approximation)
+     * 1 token ≈ 4 characters average
+     */
+    private estimateTokens;
+    /**
+     * Validate that schema looks like valid JSON schema
+     */
+    private isValidJsonSchema;
+    /**
+     * Simple schema validation - check required fields exist
+     */
+    private validateAgainstSchema;
+}
+
+/**
+ * LLM Budget Manager
+ * Enforces call and token limits to prevent runaway costs
+ */
+
+declare class LLMBudgetManager {
+    private callCount;
+    private totalTokensUsed;
+    private readonly limits;
+    constructor(limits: LLMBudget);
+    /**
+     * Check if we can make a call with the given token estimate
+     * Throws if budget would be exceeded
+     */
+    assertCanCall(requestedTokens: number): void;
+    /**
+     * Record actual token usage from a completed call
+     */
+    recordUsage(tokensUsed: number): void;
+    /**
+     * Get current budget state
+     */
+    getStats(): {
+        callsUsed: number;
+        callsRemaining: number;
+        tokensUsed: number;
+        tokensRemaining: number;
+        totalCalls: number;
+        totalTokens: number;
+    };
+    /**
+     * Check if budget is exhausted
+     */
+    isExhausted(): boolean;
+    /**
+     * Reset budget (for testing)
+     */
+    reset(): void;
+}
+
+/**
+ * JSON Schemas for LLM responses
+ * These enforce structured output from the LLM
+ */
+
+/**
+ * Type-safe schema accessor
+ */
+declare const LLMSchemas: {
+    readonly skillNormalization: JSONSchema;
+    readonly sectionClassification: JSONSchema;
+    readonly suggestionEnhancement: JSONSchema;
+    readonly jdClarification: JSONSchema;
+    readonly validation: JSONSchema;
+};
+
+/**
+ * LLM Prompt Templates
+ * Strict prompts that enforce JSON output and role clarity
+ */
+/**
+ * System prompts for different LLM tasks
+ */
+declare const LLMPrompts: {
+    /**
+     * System prompt for skill normalization
+     */
+    skillNormalizationSystem: string;
+    /**
+     * User prompt for skill normalization
+     */
+    skillNormalizationUser: (skills: string[]) => string;
+    /**
+     * System prompt for section classification
+     */
+    sectionClassificationSystem: string;
+    /**
+     * User prompt for section classification
+     */
+    sectionClassificationUser: (headers: string[]) => string;
+    /**
+     * System prompt for suggestion enhancement
+     */
+    suggestionEnhancementSystem: string;
+    /**
+     * User prompt for suggestion enhancement
+     */
+    suggestionEnhancementUser: (suggestions: string[]) => string;
+    /**
+     * System prompt for JD clarification
+     */
+    jdClarificationSystem: string;
+    /**
+     * User prompt for JD clarification
+     */
+    jdClarificationUser: (jd: string) => string;
+};
+/**
+ * Create a structured prompt for a task
+ */
+declare function createPrompt(systemBase: string, userBuilder: (input: string) => string, input: string): {
+    system: string;
+    user: string;
+};
+
+/**
+ * LLM Adapters - Transform LLM responses into usable data
+ * Safely extract and validate results from LLM calls
+ */
+/**
+ * Adapter for skill normalization response
+ */
+declare function adaptSkillNormalizationResponse(data: unknown): {
+    input: string;
+    normalized: string;
+    confidence?: number;
+}[];
+/**
+ * Adapter for section classification response
+ */
+declare function adaptSectionClassificationResponse(data: unknown): {
+    header: string;
+    classification: string;
+    confidence?: number;
+}[];
+/**
+ * Adapter for suggestion enhancement response
+ */
+declare function adaptSuggestionEnhancementResponse(data: unknown): {
+    original: string;
+    enhanced: string;
+    actionable?: boolean;
+}[];
+/**
+ * Adapter for JD clarification response
+ */
+declare function adaptJdClarificationResponse(data: unknown): {
+    implicitSkills: string[];
+    implicitExperience?: {
+        minYears?: number;
+        domains?: string[];
+    };
+    clarityScore?: number;
+};
+/**
+ * Safe value extraction with type coercion
+ */
+declare function safeExtractString(obj: unknown, key: string): string | undefined;
+/**
+ * Safe array extraction
+ */
+declare function safeExtractArray(obj: unknown, key: string): unknown[];
+/**
+ * Safe number extraction
+ */
+declare function safeExtractNumber(obj: unknown, key: string): number | undefined;
+
 /**
  * Analyze a resume against a job description using deterministic, explainable rules.
+ * Optional LLM config enables v2 features while maintaining full backward compatibility.
+ *
+ * @param input Resume, job description, and optional LLM config
+ * @returns ATS analysis result with score, breakdown, and suggestions
+ *
+ * @example
+ * // v1 behavior - deterministic only
+ * const result = analyzeResume({ resumeText, jobDescription });
+ *
+ * @example
+ * // v2 with LLM - enhanced suggestions
+ * const result = analyzeResume({
+ *   resumeText,
+ *   jobDescription,
+ *   llm: { client, limits: { maxCalls: 3, maxTokensPerCall: 2000, maxTotalTokens: 5000 } }
+ * });
  */
 declare function analyzeResume(input: AnalyzeResumeInput): ATSAnalysisResult;
+/**
+ * Async version: Analyze a resume with full LLM support
+ * This version properly handles async LLM calls
+ *
+ * @param input Resume, job description, and optional LLM config
+ * @returns Promise<ATSAnalysisResult>
+ *
+ * @example
+ * const result = await analyzeResumeAsync({
+ *   resumeText,
+ *   jobDescription,
+ *   llm: { client, limits: {...}, enable: { suggestions: true } }
+ * });
+ */
+declare function analyzeResumeAsync(input: AnalyzeResumeInput): Promise<ATSAnalysisResult>;
 
-export { type ATSAnalysisResult, type ATSBreakdown, type ATSConfig, type ATSProfile, type ATSRule, type ATSWeights, type AnalyzeResumeInput, type KeywordDensityConfig, type NormalizedWeights, type ParsedDateRange, type ParsedExperienceEntry, type ParsedJobDescription, type ParsedResume, type ResolvedATSConfig, type ResumeSection, type RuleContext, type SectionPenaltyConfig, type SkillAliases, analyzeResume, defaultProfiles, defaultSkillAliases };
+export { type ATSAnalysisResult, type ATSBreakdown, type ATSConfig, type ATSProfile, type ATSRule, type ATSWeights, type AnalyzeResumeInput, type AnalyzeResumeInputV2, type JSONSchema, type KeywordDensityConfig, type LLMBudget, LLMBudgetManager, type LLMClient, type LLMConfig, type LLMFeatures, LLMManager, LLMPrompts, type LLMResult, LLMSchemas, type LLMUsageStats, type NormalizedWeights, type ParsedDateRange, type ParsedExperienceEntry, type ParsedJobDescription, type ParsedResume, type ResolvedATSConfig, type ResumeSection, type RuleContext, type SectionPenaltyConfig, type SkillAliases, adaptJdClarificationResponse, adaptSectionClassificationResponse, adaptSkillNormalizationResponse, adaptSuggestionEnhancementResponse, analyzeResume, analyzeResumeAsync, createPrompt, defaultProfiles, defaultSkillAliases, safeExtractArray, safeExtractNumber, safeExtractString };