langextract 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0aeb0a461910ee77f31dade0f57e4007a6525e8c4a8a8f8791f7a58a1b472926
-  data.tar.gz: c96a48d1f86d5257f5107a67b03a57b30e051ce877fd52b9d4b352fe54b57ed4
+  metadata.gz: 18f4df67c5283fcde932a3a75aa0d4c0a02978b90a56d68f44219dc89a8081fe
+  data.tar.gz: d0cc9f1c38f50535e365adbabfa91ee31d69713716a3ec0fd13f9f05b98cb606
 SHA512:
-  metadata.gz: 6c86ace0907fd9260cc93aad98c540aa269b5d6944d17d694775bc362d88865b6892b07fd1bc7a02794c25448ae724cd76b404c84274e427953ed6b092788565
-  data.tar.gz: af118cf15965bb7ef4d03fd8a2a5a07ba1b7631c84d346be42217e0d44bf0cafdc006dbceda56b255387eed87461c257680a197cdeb8662083fd2c2472043b85
+  metadata.gz: deb42f645fabcea65211bc2bc12348f6ba278fa3e1213c8d54c548b1006515e1d442c6aea9a09bb88431401812acaf1400a01aa97f23403af8977f9f59f370c1
+  data.tar.gz: d3d9f43beef6ace15dd65c24250bb991066d5b6f0d7dbf3a073e36f087f157e02633f1273b7476d738b8ea9ea1294b5b12718eedd3dba0d27d0d99a750ca4a06

data/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.0] - 2026-07-11
+
+### Fixed
+- Resolver: the case-insensitive alignment fallback derived offsets from a downcased copy of the source text, producing invalid intervals for characters whose lowercase form changes length (e.g. "İ") — an extraction could be marked `exact` while pointing at the wrong span. Matching now runs case-insensitively against the original text, so returned offsets are always valid.
+- Resolver: the case-insensitive fallback found only the first occurrence; repeated extractions (e.g. two `alpha` against `ALPHA ALPHA`) now align to distinct spans instead of colliding on the first one.
+- A bare `Hash` passed as `documents:` to `LangExtract.extract` (or to `LangExtract::IO.save_annotated_documents`) was silently split into key-value pairs and corrupted into multiple bogus documents. It is now treated as a single document.
+- Chunking: a whitespace boundary exactly at the buffer limit produced chunks of `max_char_buffer + 1` characters. Split chunks now never exceed `max_char_buffer`.
+- Extraction merging deduplicated by span/text/class only, discarding extractions that differed solely in `attributes` or `group_id`. Both are now part of the merge key; genuinely identical extractions still deduplicate (first wins).
+- Value objects are now deeply immutable: nested hashes in `Extraction#attributes`, `Document#metadata`, and example data are frozen recursively (previously only the outer hash and arrays were frozen, so nested data could be mutated after construction).
+
+### Changed
+- **Breaking:** `LangExtract.extract` and `Extractor#initialize` now validate configuration at construction and raise `ArgumentError` for invalid values: `extraction_passes` and `max_char_buffer` must be Integers >= 1, `context_window_chars` an Integer >= 0, `fuzzy_threshold` Numeric within 0.0..1.0, `prompt_description` a non-empty String, `examples` enumerable (nil coerces to `[]`), and `format`/`prompt_validation` must be valid modes. Previously e.g. `extraction_passes: 0` silently made zero provider calls and returned empty results.
+- **Breaking:** The minimum Ruby version is now 4.0.5 (`required_ruby_version = ">= 4.0.5"`), matching what CI actually tests. Previously the gem claimed `>= 4.0` without verifying older 4.0.x releases.
+- Gem packaging now includes only git-tracked files (`git ls-files --cached`); untracked working-directory files can no longer leak into locally built gems. A packaging test guards the manifest.
+- JSONL loading streams the file with `File.foreach` instead of reading it fully into memory.
+- README: the source-grounding feature description no longer claims every extraction carries offsets — grounded extractions include character and token offsets, while ungrounded results retain an explicit alignment status.
+
+Note: 0.2.0 was tagged but never published to RubyGems.org; 0.3.0 is the first published release containing both changelogs' changes since 0.1.0.
+
+## [0.2.0] - 2026-07-11
+
+### Added
+- Provider error taxonomy under `LangExtract::Core::ProviderError`: `ProviderAuthError`, `ProviderRateLimitError`, `ProviderTimeoutError`, `ProviderResponseError`, and `ProviderConfigError`.
+- Configured logging is now used: suppressed parse errors are logged at `warn` and per-document extraction summaries at `debug`. Set `logger` to `nil` to disable logging. `Rails.logger` is picked up only when actually present.
+
+### Changed
+- **Breaking:** The minimum Ruby version is now 4.0. CI tests Ruby 4.0.5.
+- **Breaking:** Previously all provider errors were wrapped in `ProviderConfigError`. Now only recognized RubyLLM and timeout errors are mapped into the `ProviderError` taxonomy, with the original exception preserved as `#cause`; unknown errors such as `SocketError` and `Faraday::ConnectionFailed` propagate unchanged. `rescue LangExtract::ProviderConfigError` is no longer a catch-all; rescue `LangExtract::ProviderError` plus `StandardError` as needed.
+- Improved resolver performance on large documents by reusing a resolver instance per document, pruning fuzzy-alignment candidates with similarity upper bounds, and exiting early on acceptable perfect matches. Fuzzy alignment now prefers matches inside the chunk's preferred interval before considering the rest of the document, which can select a chunk-local match over a marginally higher-scoring match elsewhere. This matches upstream LangExtract's chunk-local alignment semantics; previously all candidates were pooled and ranked globally by score.
+
+### Fixed
+- JSONL IO and fixture reads now force UTF-8 encoding, so the gem works under C/POSIX locales. Encoding failures raise `LangExtract::Core::IOFailure`.
+- Lazy initialization of `LangExtract.config` and `Factory.router` is now thread-safe.
+
 ## [0.1.0] - 2026-04-19
 
 ### Added

data/README.md

@@ -11,7 +11,7 @@ Use it when a Ruby or Rails app needs structured LLM output that can be traced b
 
 ## Features
 
-- **Source grounding** — every extraction includes character and token offsets back to the original text
+- **Source grounding** — grounded extractions include character and token offsets back to the original text, while ungrounded results retain an explicit alignment status
 - **Structured outputs** — deterministic, serializable result objects with alignment status
 - **Long-document chunking** — sentence-aware chunking with sequential multi-pass extraction
 - **Interactive visualization** — self-contained HTML highlighting of extraction spans
@@ -20,8 +20,8 @@ Use it when a Ruby or Rails app needs structured LLM output that can be traced b
 
 ## Requirements
 
-- Ruby >= 3.4.5
-- Tested on Ruby 3.4.5 and 4.0.2
+- Ruby >= 4.0.5
+- Tested on Ruby 4.0.5
 - Optional live inference adapter: `ruby_llm` >= 1.0 when using `LangExtract::Factory.create_model`
 
 ## Installation
@@ -172,12 +172,20 @@ LangExtract::Core::FormatHandler.new.parse(model_output, schema: schema)
 
 ## Error handling
 
+Rescue `LangExtract::ProviderError` for all recognized provider failures, or rescue a specific subclass:
+
+- `LangExtract::ProviderAuthError` for authentication and authorization failures
+- `LangExtract::ProviderRateLimitError` for provider throttling
+- `LangExtract::ProviderTimeoutError` for request timeouts
+- `LangExtract::ProviderResponseError` for invalid or unsuccessful provider responses
+- `LangExtract::ProviderConfigError` for invalid provider configuration
+
 ```ruby
 begin
   LangExtract.extract(...)
 rescue LangExtract::InvalidModelConfigError => e
   warn "Invalid model configuration: #{e.message}"
-rescue LangExtract::ProviderConfigError => e
+rescue LangExtract::ProviderError => e
   warn "Provider failed: #{e.message}"
 rescue LangExtract::PromptValidationError, LangExtract::FormatParsingError => e
   warn e.message
@@ -188,6 +196,20 @@ rescue LangExtract::IOFailure => e
 end
 ```
 
+Unknown errors propagate. Mapped provider errors preserve the original exception as `#cause`.
+
+## Logging
+
+```ruby
+LangExtract.configure { |config| config.logger = Logger.new($stdout) }
+```
+
+Set `logger` to `nil` to disable logging. `Rails.logger` is auto-detected when present.
+
+## Thread safety
+
+Configuration and provider router initialization are mutex-guarded.
+
 ## API reference
 
 - Upstream project: [google/langextract](https://github.com/google/langextract)

data/lib/langextract/config.rb

@@ -14,7 +14,9 @@ module LangExtract
     private
 
     def default_logger
-      defined?(Rails) ? Rails.logger : Logger.new($stderr)
+      return Rails.logger if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+
+      Logger.new($stderr, progname: "langextract").tap { |logger| logger.level = Logger::WARN }
     end
   end
 end

data/lib/langextract/core/chunking.rb

@@ -84,7 +84,7 @@ module LangExtract
 
       def split_position(text, start_pos)
         limit = [start_pos + max_char_buffer, text.length].min
-        whitespace = text.rindex(/\s/, limit)
+        whitespace = text.rindex(/\s/, limit - 1)
         return limit unless whitespace && whitespace > start_pos
 
         whitespace + 1

data/lib/langextract/core/data.rb

@@ -12,7 +12,7 @@ module LangExtract
       def stringify_keys(hash)
         (hash || {}).each_with_object({}) do |(key, value), result|
           result[key.to_s] = coerce_value(value)
-        end
+        end.freeze
       end
 
       def coerce_value(value)

data/lib/langextract/core/errors.rb

@@ -4,7 +4,12 @@ module LangExtract
   module Core
     class Error < StandardError; end
     class InvalidModelConfigError < Error; end
-    class ProviderConfigError < Error; end
+    class ProviderError < Error; end
+    class ProviderConfigError < ProviderError; end
+    class ProviderAuthError < ProviderError; end
+    class ProviderRateLimitError < ProviderError; end
+    class ProviderTimeoutError < ProviderError; end
+    class ProviderResponseError < ProviderError; end
     class FormatParsingError < Error; end
     class PromptValidationError < Error; end
     class AlignmentError < Error; end

data/lib/langextract/core/resolver.rb

@@ -5,6 +5,20 @@ require_relative "tokenizer"
 
 module LangExtract
   module Core
+    module SimilarityUpperBound
+      module_function
+
+      def passes?(target, candidate, target_counts, threshold)
+        denominator = target.length + candidate.length
+        length_matches = [target.length, candidate.length].min
+        return false if (2.0 * length_matches / denominator) < threshold
+
+        candidate_counts = candidate.each_char.tally
+        character_matches = target_counts.sum { |character, count| [count, candidate_counts[character].to_i].min }
+        (2.0 * character_matches / denominator) >= threshold
+      end
+    end
+
     class Resolver
       DEFAULT_FUZZY_THRESHOLD = 0.78
       MAX_FUZZY_CANDIDATE_STARTS = 4_000
@@ -61,40 +75,36 @@ module LangExtract
       end
 
       def find_exact(extraction_text, preferred_interval, occupied)
-        intervals = candidate_search_ranges(preferred_interval).flat_map do |range|
-          exact_intervals_in_range(extraction_text, range)
-        end
-        intervals = intervals.uniq
-        return nil if intervals.empty?
+        overlap_fallback = nil
 
-        first_non_overlap = intervals.find { |interval| allow_overlaps || !overlaps_any?(interval, occupied) }
-        return [first_non_overlap, AlignmentStatus::EXACT] if first_non_overlap
+        candidate_search_ranges(preferred_interval).each do |range|
+          intervals = exact_intervals_in_range(extraction_text, range).uniq
+          overlap_fallback ||= intervals.first
+          non_overlap = intervals.find { |interval| allow_overlaps || !overlaps_any?(interval, occupied) }
+          return [non_overlap, AlignmentStatus::EXACT] if non_overlap
+        end
 
-        [intervals.first, AlignmentStatus::OVERLAP]
+        overlap_fallback && [overlap_fallback, AlignmentStatus::OVERLAP]
       end
 
       def exact_intervals_in_range(extraction_text, range)
         intervals = []
         cursor = range.begin
-
-        while cursor < range.end
+        range_end = range.end
+        while cursor < range_end
           match_pos = text.index(extraction_text, cursor)
-          break unless match_pos && match_pos < range.end
+          break unless match_pos && match_pos < range_end
 
           end_pos = match_pos + extraction_text.length
-          intervals << CharInterval.new(start_pos: match_pos, end_pos: end_pos) if end_pos <= range.end
+          intervals << CharInterval.new(start_pos: match_pos, end_pos: end_pos) if end_pos <= range_end
           cursor = match_pos + 1
         end
-
         if intervals.empty?
-          downcase_text = text[range].downcase
-          downcase_target = extraction_text.downcase
-          local_pos = downcase_text.index(downcase_target)
-          if local_pos
-            intervals << CharInterval.new(
-              start_pos: range.begin + local_pos,
-              end_pos: range.begin + local_pos + extraction_text.length
-            )
+          pattern = Regexp.new(Regexp.escape(extraction_text), Regexp::IGNORECASE)
+          cursor = range.begin
+          while (match = pattern.match(text, cursor)) && match.begin(0) < range_end
+            intervals << CharInterval.new(start_pos: match.begin(0), end_pos: match.end(0)) if match.end(0) <= range_end
+            cursor = match.begin(0) + 1
           end
         end
 
@@ -105,19 +115,21 @@ module LangExtract
         target = normalize_for_match(extraction_text)
         return nil if target.empty?
 
-        candidates = candidate_search_ranges(preferred_interval).flat_map do |range|
-          fuzzy_candidates_in_range(extraction_text, target, range)
-        end
-        candidates = ranked_unique_candidates(candidates)
-        return nil if candidates.empty?
+        target_counts = target.each_char.tally
+        overlap_fallback = nil
 
-        non_overlap = candidates.find { |interval, _score| allow_overlaps || !overlaps_any?(interval, occupied) }
-        return [non_overlap.first, AlignmentStatus::FUZZY] if non_overlap
+        candidate_search_ranges(preferred_interval).each do |range|
+          candidates = fuzzy_candidates_in_range(extraction_text, target, target_counts, range, occupied)
+          candidates = ranked_unique_candidates(candidates)
+          overlap_fallback ||= candidates.first&.first
+          non_overlap = candidates.find { |interval, _score| allow_overlaps || !overlaps_any?(interval, occupied) }
+          return [non_overlap.first, AlignmentStatus::FUZZY] if non_overlap
+        end
 
-        [candidates.first.first, AlignmentStatus::OVERLAP]
+        overlap_fallback && [overlap_fallback, AlignmentStatus::OVERLAP]
       end
 
-      def fuzzy_candidates_in_range(extraction_text, normalized_target, range)
+      def fuzzy_candidates_in_range(extraction_text, normalized_target, target_counts, range, occupied)
         target_length = extraction_text.length
         min_length = [1, (target_length * 0.65).floor].max
         max_length = [(target_length * 1.35).ceil, min_length].max
@@ -129,13 +141,18 @@ module LangExtract
             next if end_pos > range.end
 
             candidate = text[start_pos...end_pos]
-            score = similarity(normalized_target, normalize_for_match(candidate))
+            normalized_candidate = normalize_for_match(candidate)
+            next unless SimilarityUpperBound.passes?(normalized_target, normalized_candidate, target_counts,
+                                                     fuzzy_threshold)
+
+            score = similarity(normalized_target, normalized_candidate)
             next if score < fuzzy_threshold
 
-            candidates << [
-              CharInterval.new(start_pos: start_pos, end_pos: end_pos),
-              score
-            ]
+            match = [CharInterval.new(start_pos: start_pos, end_pos: end_pos), score]
+            interval = match.first
+            return [match] if score >= 1.0 && (allow_overlaps || !overlaps_any?(interval, occupied))
+
+            candidates << match
           end
         end
 

data/lib/langextract/errors.rb

@@ -5,7 +5,12 @@ require_relative "core/errors"
 module LangExtract
   Error = Core::Error
   InvalidModelConfigError = Core::InvalidModelConfigError
+  ProviderError = Core::ProviderError
   ProviderConfigError = Core::ProviderConfigError
+  ProviderAuthError = Core::ProviderAuthError
+  ProviderRateLimitError = Core::ProviderRateLimitError
+  ProviderTimeoutError = Core::ProviderTimeoutError
+  ProviderResponseError = Core::ProviderResponseError
   FormatParsingError = Core::FormatParsingError
   PromptValidationError = Core::PromptValidationError
   AlignmentError = Core::AlignmentError

data/lib/langextract/extractor.rb

@@ -8,6 +8,7 @@ require_relative "core/prompting"
 module LangExtract
   class Extractor
     DEFAULT_MAX_CHAR_BUFFER = Core::SentenceAwareChunker::DEFAULT_MAX_CHAR_BUFFER
+    FORMATS = %i[auto json yaml].freeze
 
     def initialize(model:, prompt_description:, examples: [], additional_context: nil,
                    max_char_buffer: DEFAULT_MAX_CHAR_BUFFER, context_window_chars: 0,
@@ -18,7 +19,7 @@ module LangExtract
                    tokenizer: Core::UnicodeTokenizer.new)
       @model = model
       @prompt_description = prompt_description
-      @examples = examples
+      @examples = examples.nil? ? [] : examples
       @additional_context = additional_context
       @max_char_buffer = max_char_buffer
       @context_window_chars = context_window_chars
@@ -31,6 +32,7 @@ module LangExtract
       @allow_overlaps = allow_overlaps
       @fuzzy_threshold = fuzzy_threshold
       @tokenizer = tokenizer
+      validate_configuration!
       validate_model!
     end
 
@@ -52,26 +54,28 @@ module LangExtract
       chunker = Core::SentenceAwareChunker.new(max_char_buffer: max_char_buffer, tokenizer: tokenizer)
       prompt_builder = Core::PromptBuilder.new(validation_mode: prompt_validation)
       format_handler = Core::FormatHandler.new
+      resolver = Core::Resolver.new(
+        text: document.text,
+        tokenizer: tokenizer,
+        fuzzy_threshold: fuzzy_threshold,
+        allow_overlaps: allow_overlaps,
+        suppress_alignment_errors: suppress_alignment_errors
+      )
       extractions = []
 
       chunker.chunks(document).each do |chunk|
         extraction_passes.times do |pass_index|
           raw_output = infer(prompt_builder, document, chunk, pass_index)
-          parsed = parse(format_handler, raw_output)
-          resolver = Core::Resolver.new(
-            text: document.text,
-            tokenizer: tokenizer,
-            fuzzy_threshold: fuzzy_threshold,
-            allow_overlaps: allow_overlaps,
-            suppress_alignment_errors: suppress_alignment_errors
-          )
+          parsed = parse(format_handler, raw_output, document: document, chunk: chunk)
           extractions.concat(
             resolver.resolve(parsed, document_id: document.id, preferred_interval: chunk.char_interval)
           )
         end
       end
 
-      Core::AnnotatedDocument.new(document: document, extractions: merge_extractions(extractions))
+      annotated = Core::AnnotatedDocument.new(document: document, extractions: merge_extractions(extractions))
+      log_document_summary(annotated)
+      annotated
     end
 
     def infer(prompt_builder, document, chunk, pass_index)
@@ -94,14 +98,25 @@ module LangExtract
       result.respond_to?(:text) ? result.text.to_s : result.to_s
     end
 
-    def parse(format_handler, raw_output)
+    def parse(format_handler, raw_output, document:, chunk:)
       format_handler.parse(raw_output, format: format, strict: strict)
-    rescue Core::FormatParsingError
+    rescue Core::FormatParsingError => e
       raise unless suppress_parse_errors
 
+      LangExtract.config.logger&.warn(
+        "suppressed parse error document_id=#{document.id} chunk_index=#{chunk.index}: #{e.message}"
+      )
       []
     end
 
+    def log_document_summary(annotated)
+      counts = annotated.extractions.group_by(&:alignment_status).transform_values(&:length)
+      statuses = counts.sort.map { |status, count| "#{status}=#{count}" }.join(",")
+      LangExtract.config.logger&.debug(
+        "document_id=#{annotated.document.id} extractions=#{annotated.extractions.length} alignment_status=#{statuses}"
+      )
+    end
+
     def merge_extractions(extractions)
       occupied = []
       seen = {}
@@ -128,13 +143,17 @@ module LangExtract
         interval&.end_pos,
         extraction.text,
         extraction.description,
-        extraction.extraction_class
+        extraction.extraction_class,
+        extraction.attributes,
+        extraction.group_id
       ]
     end
 
     def coerce_documents(text, documents)
       if documents
-        Array(documents).map.with_index { |document, index| coerce_document(document, index) }
+        (documents.is_a?(Hash) ? [documents] : Array(documents)).map.with_index do |document, index|
+          coerce_document(document, index)
+        end
       elsif text
         [Core::Document.new(text: text, id: "document_0")]
       else
@@ -154,5 +173,45 @@ module LangExtract
 
       raise Core::InvalidModelConfigError, "model must respond to #infer(prompt:)"
     end
+
+    def validate_configuration!
+      validate_integer!(extraction_passes, "extraction_passes", 1)
+      validate_integer!(max_char_buffer, "max_char_buffer", 1)
+      validate_integer!(context_window_chars, "context_window_chars", 0)
+      validate_fuzzy_threshold!
+      validate_prompt_description!
+      raise ArgumentError, "examples must respond to #each" unless examples.respond_to?(:each)
+
+      validate_symbol_value!(format, FORMATS, "format must be one of: auto, json, yaml")
+      validate_symbol_value!(
+        prompt_validation,
+        Core::PromptValidation::MODES,
+        "prompt_validation must be one of: off, warning, error"
+      )
+    end
+
+    def validate_integer!(value, name, minimum)
+      return if value.is_a?(Integer) && value >= minimum
+
+      raise ArgumentError, "#{name} must be an Integer >= #{minimum}"
+    end
+
+    def validate_fuzzy_threshold!
+      return if fuzzy_threshold.is_a?(Numeric) && (0.0..1.0).cover?(fuzzy_threshold)
+
+      raise ArgumentError, "fuzzy_threshold must be Numeric within 0.0..1.0"
+    end
+
+    def validate_prompt_description!
+      return if prompt_description.is_a?(String) && !prompt_description.empty?
+
+      raise ArgumentError, "prompt_description must be a non-empty String"
+    end
+
+    def validate_symbol_value!(value, valid_values, error_message)
+      return if value.respond_to?(:to_sym) && valid_values.include?(value.to_sym)
+
+      raise ArgumentError, error_message
+    end
   end
 end

data/lib/langextract/factory.rb

@@ -38,6 +38,8 @@ module LangExtract
   end
 
   module Factory
+    ROUTER_MUTEX = Mutex.new
+
     module_function
 
     def create_model(config = ModelConfig.new)
@@ -45,11 +47,11 @@ module LangExtract
     end
 
     def router
-      @router ||= default_router
+      ROUTER_MUTEX.synchronize { @router ||= default_router }
     end
 
     def reset_router!
-      @router = default_router
+      ROUTER_MUTEX.synchronize { @router = default_router }
     end
 
     def default_router

data/lib/langextract/io.rb

@@ -10,25 +10,27 @@ module LangExtract
     module_function
 
     def save_annotated_documents(path, documents)
-      normalized = Array(documents)
-      ::File.open(path, "w") do |file|
+      normalized = documents.is_a?(Hash) ? [documents] : Array(documents)
+      ::File.open(path, "w:UTF-8") do |file|
         normalized.each do |document|
           annotated = document.is_a?(Core::AnnotatedDocument) ? document : Core::AnnotatedDocument.from_h(document)
           file.puts(JSON.generate(annotated.to_h))
         end
       end
       path
-    rescue SystemCallError, JSON::GeneratorError => e
+    rescue SystemCallError, JSON::GeneratorError, EncodingError => e
       raise Core::IOFailure, "failed to save annotated documents: #{e.message}"
     end
 
     def load_annotated_documents_jsonl(path)
-      ::File.readlines(path, chomp: true).filter_map do |line|
+      documents = []
+      ::File.foreach(path, encoding: "UTF-8") do |line|
         next if line.strip.empty?
 
-        Core::AnnotatedDocument.from_h(JSON.parse(line))
+        documents << Core::AnnotatedDocument.from_h(JSON.parse(line))
       end
-    rescue SystemCallError, JSON::ParserError => e
+      documents
+    rescue SystemCallError, JSON::ParserError, EncodingError => e
       raise Core::IOFailure, "failed to load annotated documents: #{e.message}"
     end
   end

data/lib/langextract/providers/ruby_llm.rb

@@ -2,6 +2,7 @@
 
 require_relative "base"
 require_relative "../core/types"
+require "timeout"
 
 module LangExtract
   module Providers
@@ -14,11 +15,40 @@ module LangExtract
       rescue LoadError => e
         raise Core::ProviderConfigError, "ruby_llm is required for live provider inference: #{e.message}"
       rescue StandardError => e
-        raise Core::ProviderConfigError, "provider inference failed: #{e.message}"
+        error_class = provider_error_class(e)
+        raise unless error_class
+
+        raise error_class, "provider inference failed: #{e.message}"
       end
 
       private
 
+      def provider_error_class(error)
+        return Core::ProviderTimeoutError if timeout_error?(error)
+        return Core::ProviderAuthError if ruby_llm_error?(error, :UnauthorizedError, :ForbiddenError,
+                                                          :PaymentRequiredError)
+        return Core::ProviderConfigError if ruby_llm_error?(error, :ConfigurationError)
+        return Core::ProviderRateLimitError if ruby_llm_error?(error, :RateLimitError, :OverloadedError,
+                                                               :ServiceUnavailableError)
+        return Core::ProviderResponseError if defined?(RubyLLM::Error) && error.is_a?(RubyLLM::Error)
+
+        nil
+      end
+
+      def timeout_error?(error)
+        error.is_a?(Timeout::Error) || error.is_a?(Errno::ETIMEDOUT) ||
+          (defined?(Faraday::TimeoutError) && error.is_a?(Faraday::TimeoutError)) ||
+          error.class.name.to_s.match?(/timeout/i)
+      end
+
+      def ruby_llm_error?(error, *constant_names)
+        return false unless defined?(RubyLLM)
+
+        constant_names.any? do |constant_name|
+          RubyLLM.const_defined?(constant_name, false) && error.is_a?(RubyLLM.const_get(constant_name))
+        end
+      end
+
       def chat_options
         options = config.options.dup
         options[:model] = config.model if config.model

data/lib/langextract/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LangExtract
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/langextract.rb

@@ -18,6 +18,8 @@ require_relative "langextract/visualization"
 require_relative "langextract/factory"
 
 module LangExtract
+  CONFIG_MUTEX = Mutex.new
+
   CharInterval = Core::CharInterval
   TokenInterval = Core::TokenInterval
   Extraction = Core::Extraction
@@ -28,7 +30,7 @@ module LangExtract
 
   class << self
     def config
-      @config ||= Config.new
+      CONFIG_MUTEX.synchronize { @config ||= Config.new }
     end
 
     def configure
@@ -36,7 +38,7 @@ module LangExtract
     end
 
     def reset_configuration!
-      @config = nil
+      CONFIG_MUTEX.synchronize { @config = nil }
       Factory.reset_router!
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: langextract
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - David Paluy
@@ -51,7 +51,7 @@ metadata:
   homepage_uri: https://github.com/dpaluy/langextract
   documentation_uri: https://rubydoc.info/gems/langextract
   source_code_uri: https://github.com/dpaluy/langextract
-  changelog_uri: https://github.com/dpaluy/langextract/blob/main/CHANGELOG.md
+  changelog_uri: https://github.com/dpaluy/langextract/blob/master/CHANGELOG.md
   bug_tracker_uri: https://github.com/dpaluy/langextract/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []
@@ -61,14 +61,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.4.5
+      version: 4.0.5
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Ruby port of LangExtract for source-grounded structured extraction.
 test_files: []