cv-parser 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e6b7590ababb813164420d1ef2b1d648c3cc215f6470c8d4c8d3ba00e62e51ee
+  data.tar.gz: 77f236b9d6c7fd62f7a1979b747f944cdcbd59a0329c6917fb079fd3842fc238
+SHA512:
+  metadata.gz: 565ea71844fe6be24392a19904c7690a91f017b1e5dbd6354587620b10f529a2cff4459d9cc995b737aa982d3b7987d2a686d3cc67f43600e49372e82865f375
+  data.tar.gz: 5703710f848b986b895b98561396d550ff94def445345dc5f2e9eb5fd8bac6b15943eabf16ba426d2cffaf22a446e0aa526fbb78caa98ad2b6d068300d7ce19e

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-06-01
+
+### Added
+- Initial release of cv-parser gem
+- Basic project structure and configuration 

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE. 

data/README.md

@@ -0,0 +1,380 @@
+# CV Parser
+
+A Ruby gem for parsing and extracting structured information from CVs/resumes using LLM providers.
+
+## Features
+- Convert DOCX to PDF before uploading to LLM providers
+- Extract structured data from CVs by directly uploading files to LLM providers
+- Configure different LLM providers (OpenAI, Anthropic, and Faker for testing)
+- Customizable output schema to match your data requirements (JSON Schema format)
+- Command-line interface for quick parsing and analysis
+- Robust error handling and validation
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'cv-parser'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install cv-parser
+```
+
+## Usage
+
+### Using in Rails
+
+You can use CV Parser directly in your Ruby or Rails application to extract structured data from CVs. 
+
+#### Basic Configuration
+
+You can configure the gem for different providers:
+
+```ruby
+require 'cv_parser'
+
+# OpenAI
+CvParser.configure do |config|
+  config.provider = :openai
+  config.api_key = ENV['OPENAI_API_KEY']
+  config.model = 'gpt-4.1-mini'
+  config.output_schema = schema
+end
+
+# Anthropic
+CvParser.configure do |config|
+  config.provider = :anthropic
+  config.api_key = ENV['ANTHROPIC_API_KEY']
+  config.model = 'claude-3-sonnet-20240229'
+  config.output_schema = schema
+end
+
+# Faker (for testing/development)
+CvParser.configure do |config|
+  config.provider = :faker
+  config.output_schema = schema
+end
+```
+
+#### Defining an Output Schema
+
+Define the schema for the data you want to extract using JSON Schema format:
+
+```ruby
+schema = {
+  type: "json_schema",
+  name: "cv_parsing",
+  description: "Schema for a CV or resume document",
+  properties: {
+    personal_info: {
+      type: "object",
+      description: "Personal and contact information for the candidate",
+      properties: {
+        name: {
+          type: "string",
+          description: "Full name of the individual"
+        },
+        email: {
+          type: "string",
+          description: "Email address of the individual"
+        },
+        phone: {
+          type: "string",
+          description: "Phone number of the individual"
+        },
+        location: {
+          type: "string",
+          description: "Geographic location or city of residence"
+        }
+      },
+      required: %w[name email]
+    },
+    experience: {
+      type: "array",
+      description: "List of professional experience entries",
+      items: {
+        type: "object",
+        description: "A professional experience entry",
+        properties: {
+          company: {
+            type: "string",
+            description: "Name of the company or organization"
+          },
+          position: {
+            type: "string",
+            description: "Job title or position held"
+          },
+          start_date: {
+            type: "string",
+            description: "Start date of employment (e.g. '2020-01')"
+          },
+          end_date: {
+            type: "string",
+            description: "End date of employment or 'present'"
+          },
+          description: {
+            type: "string",
+            description: "Description of responsibilities and achievements"
+          }
+        },
+        required: %w[company position start_date]
+      }
+    },
+    education: {
+      type: "array",
+      description: "List of educational qualifications",
+      items: {
+        type: "object",
+        description: "An education entry",
+        properties: {
+          institution: {
+            type: "string",
+            description: "Name of the educational institution"
+          },
+          degree: {
+            type: "string",
+            description: "Degree or certification received"
+          },
+          field: {
+            type: "string",
+            description: "Field of study"
+          },
+          graduation_date: {
+            type: "string",
+            description: "Graduation date (e.g. '2019-06')"
+          }
+        },
+        required: %w[institution degree]
+      }
+    },
+    skills: {
+      type: "array",
+      description: "List of relevant skills",
+      items: {
+        type: "string",
+        description: "A single skill"
+      }
+    }
+  },
+  required: %w[personal_info experience education skills]
+}
+```
+
+Set the output schema in the configuration block:
+
+```ruby
+CvParser.configure do |config|
+  config.output_schema = schema
+end
+```
+
+You can also set the output schema in the extractor method which will override the configuration block:
+
+```ruby
+extractor = CvParser::Extractor.new
+extractor.extract(
+  output_schema: schema
+)
+```
+
+#### Extracting Data from a CV
+
+```ruby
+extractor = CvParser::Extractor.new
+result = extractor.extract(
+  file_path: "path/to/resume.pdf"
+)
+
+puts "Name: #{result['personal_info']['name']}"
+puts "Email: #{result['personal_info']['email']}"
+result['skills'].each { |skill| puts "- #{skill}" }
+```
+
+#### Error Handling
+
+```ruby
+begin
+  result = extractor.extract(
+    file_path: "path/to/resume.pdf"
+  )
+rescue CvParser::FileNotFoundError, CvParser::FileNotReadableError => e
+  puts "File error: #{e.message}"
+rescue CvParser::ParseError => e
+  puts "Error parsing the response: #{e.message}"
+rescue CvParser::APIError => e
+  puts "LLM API error: #{e.message}"
+rescue CvParser::ConfigurationError => e
+  puts "Configuration error: #{e.message}"
+end
+```
+
+---
+
+### Command-Line Interface
+
+CV Parser also provides a CLI for quick analysis:
+
+```bash
+cv-parser path/to/resume.pdf
+cv-parser --provider anthropic path/to/resume.pdf
+cv-parser --format yaml --output result.yaml path/to/resume.pdf
+cv-parser --schema custom-schema.json path/to/resume.pdf
+cv-parser --help
+```
+
+You can use environment variables for API keys and provider selection:
+
+```bash
+export OPENAI_API_KEY=your-openai-key
+export ANTHROPIC_API_KEY=your-anthropic-key
+export CV_PARSER_PROVIDER=openai
+export CV_PARSER_API_KEY=your-api-key
+cv-parser resume.pdf
+```
+
+
+## Advanced Configuration
+
+You can further customize CV Parser by setting advanced options in the configuration block. For example:
+
+```ruby
+CvParser.configure do |config|
+  # Configure OpenAI with organization ID
+  config.provider = :openai
+  config.api_key = ENV['OPENAI_API_KEY']
+  config.model = 'gpt-4.1-mini'
+  
+  # Set timeout for file uploads (important for larger files)
+  config.timeout = 120  # TODO - not yet implemented
+  config.max_retries = 2  # TODO - not yet implemented
+  
+  # Provider-specific options
+  config.provider_options[:organization_id] = ENV['OPENAI_ORG_ID']
+
+  # You can also set custom prompts for the LLM:
+  config.prompt = "Extract the following fields from the CV..."
+  config.system_prompt = "You are a CV parsing assistant."
+
+  # Set the output schema (JSON Schema format)
+  config.output_schema = schema
+
+  # Set the max tokens and temperature
+  config.max_tokens = 4000
+  config.temperature = 0.1
+end
+```
+
+### Testing and Development
+
+#### Using the Faker Provider
+
+The Faker provider generates realistic-looking fake data based on your schema without making API calls. This is useful for:
+- Writing tests (RSpec, Rails, etc.)
+- Developing UI components
+- Demonstrating functionality without API keys
+- Avoiding API costs and rate limits
+- Tests run faster without external API calls
+- Consistent, predictable results
+- No need for API keys in CI/CD environments
+
+#### Basic Test Setup
+
+Here's how to use the faker provider in your RSpec tests:
+
+```ruby
+# spec/your_resume_processor_spec.rb
+require 'spec_helper'
+
+RSpec.describe YourResumeProcessor do
+  # Define a JSON Schema format schema for testing
+  let(:test_schema) do
+    {
+      type: "json_schema",
+      name: "cv_parsing_test",
+      description: "Test schema for CV parsing",
+      properties: {
+        personal_info: {
+          type: "object",
+          description: "Personal information",
+          properties: {
+            name: {
+              type: "string",
+              description: "Full name"
+            },
+            email: {
+              type: "string",
+              description: "Email address"
+            }
+          },
+          required: %w[name email]
+        },
+        skills: {
+          type: "array",
+          description: "List of skills",
+          items: {
+            type: "string",
+            description: "A skill"
+          }
+        }
+      },
+      required: %w[personal_info skills]
+    }
+  end
+
+  before do
+    # Configure CV Parser to use the faker provider
+    CvParser.configure do |config|
+      config.provider = :faker
+    end
+  end
+
+  after do
+    # Reset configuration after tests
+    CvParser.reset
+  end
+
+  it "processes a resume and extracts relevant fields" do
+    processor = YourResumeProcessor.new
+    result = processor.process_resume("spec/fixtures/sample_resume.pdf", test_schema)
+    
+    # The faker provider will return consistent test data
+    expect(result.personal_info.name).to eq("John Doe")
+    expect(result.personal_info.email).to eq("john.doe@example.com")
+    expect(result.skills).to be_an(Array)
+    expect(result.skills).not_to be_empty
+  end
+end
+```
+
+#### Simple Faker Example
+
+```ruby
+# Configure with Faker provider
+CvParser.configure do |config|
+  config.provider = :faker
+end
+
+# Use the extractor as normal
+extractor = CvParser::Extractor.new
+result = extractor.extract(
+  file_path: "path/to/resume.pdf",  # Path will be ignored by faker
+  output_schema: schema  # Using the JSON Schema format defined above
+)
+
+# Faker will generate structured data based on your schema
+puts result.inspect
+```
+
+#### Data Generation Behavior
+
+The faker provider generates realistic-looking data based on your schema. The data is deterministic for fields like name, email, and phone, but randomized for arrays and collections. You can write tests that check for structure without relying on specific content for variable fields.

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "cv_parser"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here 

data/exe/cv-parser

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "cv_parser"
+
+# Initialize and run the CLI
+CvParser::CLI.new.run

data/lib/cv_parser/cli.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "json"
+require_relative "../cv_parser"
+
+module CvParser
+  class CLI
+    DEFAULT_SCHEMA = {
+      type: "json_schema",
+      properties: {
+        contact_information: {
+          type: "object",
+          properties: {
+            name: { type: "string" },
+            email: { type: "string" },
+            phone: { type: "string" },
+            location: { type: "string" },
+            linkedin: { type: "string" }
+          }
+        },
+        education: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              institution: { type: "string" },
+              degree: { type: "string" },
+              field_of_study: { type: "string" },
+              dates: { type: "string" },
+              achievements: {
+                type: "array",
+                items: { type: "string" }
+              }
+            }
+          }
+        },
+        work_experience: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              company: { type: "string" },
+              position: { type: "string" },
+              dates: { type: "string" },
+              responsibilities: {
+                type: "array",
+                items: { type: "string" }
+              },
+              achievements: {
+                type: "array",
+                items: { type: "string" }
+              }
+            }
+          }
+        },
+        skills: {
+          type: "array",
+          items: { type: "string" }
+        },
+        languages: {
+          type: "array",
+          items: { type: "string" }
+        },
+        certifications: {
+          type: "array",
+          items: { type: "string" }
+        }
+      }
+    }.freeze
+
+    def initialize
+      @options = {
+        provider: nil,
+        api_key: nil,
+        output_format: "json",
+        output_file: nil,
+        schema_file: nil
+      }
+    end
+
+    def run(args = ARGV)
+      parse_options(args)
+
+      if args.empty?
+        puts "Error: No input file specified"
+        puts @parser
+        exit 1
+      end
+
+      input_file = args[0]
+
+      # Early exit for special options where we don't need a file
+      return if @options[:help] || @options[:version]
+
+      # Check if file exists
+      if !input_file || !File.exist?(input_file)
+        puts "Error: Input file '#{input_file}' not found"
+        exit 1
+      end
+
+      configure_parser
+
+      begin
+        output_schema = load_schema
+        result = extract_data(input_file, output_schema)
+        output_result(result)
+      rescue CvParser::Error => e
+        puts "Error: #{e.message}"
+        exit 1
+      end
+    end
+
+    private
+
+    def parse_options(args)
+      @parser = OptionParser.new do |opts|
+        opts.banner = "Usage: cv-parser [options] <file>"
+
+        opts.on("-p", "--provider PROVIDER", "LLM Provider (openai, anthropic, or faker)") do |provider|
+          @options[:provider] = provider.to_sym
+        end
+
+        opts.on("-k", "--api-key API_KEY", "API key for the LLM provider") do |key|
+          @options[:api_key] = key
+        end
+
+        opts.on("-f", "--format FORMAT", "Output format (json or yaml)") do |format|
+          @options[:output_format] = format
+        end
+
+        opts.on("-o", "--output FILE", "Write output to file") do |file|
+          @options[:output_file] = file
+        end
+
+        opts.on("-s", "--schema FILE", "Custom schema file (JSON)") do |file|
+          @options[:schema_file] = file
+        end
+
+        opts.on("-h", "--help", "Show this help message") do
+          puts opts
+          @options[:help] = true
+          exit
+        end
+
+        opts.on("-v", "--version", "Show version") do
+          puts "CV Parser v#{CvParser::VERSION}"
+          @options[:version] = true
+          exit
+        end
+      end
+
+      @parser.parse!(args)
+    end
+
+    def configure_parser
+      CvParser.configure do |config|
+        config.provider = @options[:provider] if @options[:provider]
+        config.api_key = @options[:api_key] if @options[:api_key]
+
+        # Try environment variables if not provided via options
+        config.provider ||= (ENV["CV_PARSER_PROVIDER"]&.to_sym if ENV["CV_PARSER_PROVIDER"])
+
+        # Configure based on provider
+        case config.provider
+        when :openai
+          config.api_key ||= ENV["CV_PARSER_API_KEY"] || ENV.fetch("OPENAI_API_KEY", nil)
+        when :anthropic
+          config.api_key ||= ENV["CV_PARSER_API_KEY"] || ENV.fetch("ANTHROPIC_API_KEY", nil)
+        when :faker
+          config.api_key ||= "fake-api-key"
+        else
+          # Default to OpenAI if nothing specified
+          config.provider = :openai
+          config.api_key ||= ENV["CV_PARSER_API_KEY"] || ENV.fetch("OPENAI_API_KEY", nil)
+        end
+      end
+    end
+
+    def load_schema
+      if @options[:schema_file]
+        unless File.exist?(@options[:schema_file])
+          puts "Error: Schema file '#{@options[:schema_file]}' not found"
+          exit 1
+        end
+
+        begin
+          JSON.parse(File.read(@options[:schema_file]))
+        rescue JSON::ParserError => e
+          puts "Error: Invalid JSON schema file: #{e.message}"
+          exit 1
+        end
+      else
+        DEFAULT_SCHEMA
+      end
+    end
+
+    def extract_data(input_file, output_schema)
+      puts "Parsing CV: #{input_file}"
+      puts "Using provider: #{CvParser.configuration.provider}"
+
+      extractor = CvParser::Extractor.new
+      extractor.extract(file_path: input_file, output_schema: output_schema)
+    end
+
+    def output_result(result)
+      formatted_output = case @options[:output_format]
+                         when "yaml"
+                           require "yaml"
+                           result.to_yaml
+                         else
+                           JSON.pretty_generate(result)
+                         end
+
+      if @options[:output_file]
+        File.write(@options[:output_file], formatted_output)
+        puts "Output written to: #{@options[:output_file]}"
+      else
+        puts "\nResults:"
+        puts formatted_output
+      end
+    end
+  end
+end

data/lib/cv_parser/configuration.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CvParser
+  class Configuration
+    attr_accessor :provider, :model, :api_key, :timeout, :max_retries, :prompt, :system_prompt,
+                  :output_schema, :max_tokens, :temperature
+    attr_reader :provider_options
+
+    def initialize
+      @provider = nil
+      @model = nil
+      @api_key = nil
+      @timeout = 60
+      @max_retries = 3
+      @provider_options = {}
+      @prompt = nil
+      @system_prompt = nil
+      @output_schema = nil
+      @max_tokens = 4000
+      @temperature = 0.1
+    end
+  end
+end