lara-sdk 1.9.2 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51ee605bbd73a183adcb0692120063624117745a88d47f04c60c8f937dfdeafd
-  data.tar.gz: 8b9bb03c7cf3316a0fa7bb92f95a56630a404aa22956fb5c1dbb10e923a16bc4
+  metadata.gz: d794b96f2ef4b205bf0b46706b9346af3659ee923870116341e87a3688220ee7
+  data.tar.gz: e460f4a73a7a25c94c2d57a99a8d6998c06625b9e27723594b9789b86d601061
 SHA512:
-  metadata.gz: 5ead2e652fdf3c398a87062a229c125eeef41e51f1f222db805d97af36bf7b66723931f9f28a1e4b032fdc0750fdde0314d6e0f84e40b3a351543e7c266c8964
-  data.tar.gz: 3deda3e7fd1175f5d9c3c9afa3e8211b34a530be5c7e73f65bf13c63380b43e7e62abdc410755fdd263d2f74f2655602e3a0f513ab552cdffb62412650cfe025
+  metadata.gz: 722e1746da8b4735ee5b072b8168cef5996a1aeb7cc059b3ca651da46a0144808c93c7cde7583d300ea0adf02a1b812f24803072e399e35642560b82b10b272f
+  data.tar.gz: c3dec84e4e56eec0bbfa2f46ec05a688bbecf2ee76f17bd80c6f78273f33458595b33c42baa39d2cb2d76057c04c9ac16f8c03937847ab1e994aacd976bfdf94

data/lib/lara/client.rb

@@ -56,6 +56,22 @@ module Lara
       request(:get, path, body: nil, headers: headers, params: params)
     end
 
+    # Retrieves a collection using pagination metadata from the response headers.
+    # @yield [Hash] Converts each resource to its SDK model
+    # @return [Lara::Models::CollectionResult]
+    def get_collection(path, params: nil)
+      items, headers = request(:get, path, params: params, with_metadata: true)
+      total = integer_header(headers, "x-total-count", minimum: 0)
+      raise LaraError, "Missing or invalid X-Total-Count response header" if total.nil?
+
+      Lara::Models::CollectionResult.new(
+        items: block_given? ? items.map { |item| yield item } : items,
+        total: total,
+        page: integer_header(headers, "x-page", minimum: 1),
+        size: integer_header(headers, "x-page-size", minimum: 1)
+      )
+    end
+
     # Sends a POST request to the Lara API.
     # @param path [String] The path to send the request to.
     # @param body [Hash,nil] The parameters to send with the request.
@@ -90,8 +106,19 @@ module Lara
 
     private
 
+    def integer_header(headers, name, minimum:)
+      value = headers.find { |key, _| key.downcase == name }&.last
+      return nil unless value.is_a?(String)
+
+      value = value.gsub(/\A[ \t]+|[ \t]+\z/, "")
+      return nil unless value.match?(/\A[0-9]+\z/)
+
+      number = value.to_i
+      number if number >= minimum
+    end
+
     def request(method, path, body: nil, files: nil, headers: nil, params: nil,
-                raw_response: false, &callback)
+                raw_response: false, with_metadata: false, &callback)
       file_positions = (files || {}).each_with_object({}) do |(name, file), positions|
         next unless file.respond_to?(:pos) && file.respond_to?(:seek)
 
@@ -104,7 +131,8 @@ module Lara
       ensure_valid_token
 
       make_request(method, path, body: body, files: files, headers: headers, params: params,
-                                 raw_response: raw_response, &callback)
+                                 raw_response: raw_response, with_metadata: with_metadata,
+                                 &callback)
     rescue LaraApiError => e
       raise unless e.status_code == 401
 
@@ -112,7 +140,8 @@ module Lara
       # Multipart encoding consumed the files; replay their original bytes.
       file_positions.each { |name, position| files[name].seek(position) }
       make_request(method, path, body: body, files: files, headers: headers, params: params,
-                                 raw_response: raw_response, &callback)
+                                 raw_response: raw_response, with_metadata: with_metadata,
+                                 &callback)
     end
 
     def ensure_valid_token
@@ -204,7 +233,7 @@ module Lara
     end
 
     def make_request(method, path, body: nil, files: nil, headers: nil, params: nil,
-                     raw_response: false, &callback)
+                     raw_response: false, with_metadata: false, &callback)
       path = "/#{path}" unless path.start_with?("/")
       request_headers = build_request_headers(body, files, headers)
 
@@ -226,6 +255,8 @@ module Lara
 
       raise LaraApiError.from_response(response) unless response.success?
 
+      return [parse_json(response.body), response.headers] if with_metadata
+
       return response.body if raw_response
 
       content_type = response.headers["content-type"] || response.headers["Content-Type"]

data/lib/lara/glossaries.rb

@@ -25,13 +25,27 @@ module Lara
       @polling_interval = 2
     end
 
+    # @deprecated Use #list_paginated instead.
     # @return [Array<Lara::Models::Glossary>]
     def list
+      warn "[DEPRECATION] list is deprecated; use list_paginated instead.", uplevel: 1
       (@client.get("/v2/glossaries") || []).map do |_h|
         Lara::Models::Glossary.new(**_h.transform_keys(&:to_sym))
       end
     end
 
+    # Lists resources with optional name filtering and pagination.
+    # Without options, returns the complete collection without pagination.
+    # Any supplied option enables pagination; page and size default to 1 and 20.
+    # @param options [Lara::Models::ResourceQueryOptions,nil] Name filter and pagination
+    # @return [Lara::Models::CollectionResult] Collection containing Glossary objects
+    def list_paginated(options = nil)
+      params = options&.to_params || {}
+      @client.get_collection("/v2/glossaries", params: params) do |item|
+        Lara::Models::Glossary.new(**item.transform_keys(&:to_sym))
+      end
+    end
+
     # @return [Lara::Models::Glossary]
     def create(name:)
       Lara::Models::Glossary.new(**@client.post("/v2/glossaries",

data/lib/lara/memories.rb

@@ -24,13 +24,27 @@ module Lara
       @polling_interval = 2
     end
 
+    # @deprecated Use #list_paginated instead.
     # @return [Array<Lara::Models::Memory>]
     def list
+      warn "[DEPRECATION] list is deprecated; use list_paginated instead.", uplevel: 1
       (@client.get("/v2/memories") || []).map do |_h|
         Lara::Models::Memory.new(**_h.transform_keys(&:to_sym))
       end
     end
 
+    # Lists resources with optional name filtering and pagination.
+    # Without options, returns the complete collection without pagination.
+    # Any supplied option enables pagination; page and size default to 1 and 20.
+    # @param options [Lara::Models::ResourceQueryOptions,nil] Name filter and pagination
+    # @return [Lara::Models::CollectionResult] Collection containing Memory objects
+    def list_paginated(options = nil)
+      params = options&.to_params || {}
+      @client.get_collection("/v2/memories", params: params) do |item|
+        Lara::Models::Memory.new(**item.transform_keys(&:to_sym))
+      end
+    end
+
     # @return [Lara::Models::Memory]
     def create(name:, external_id: nil)
       payload = { name: name, external_id: external_id }.compact

data/lib/lara/models/collection_result.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Lara
+  module Models
+    # A resource collection and its server-provided pagination metadata.
+    class CollectionResult < Base
+      # @return [Array<Lara::Models::Memory,Lara::Models::Glossary,Lara::Models::Styleguide>]
+      attr_reader :items
+      # @return [Integer] Total number of matching resources
+      attr_reader :total
+      # @return [Integer,nil] Current page (1-based), or nil for an unbounded collection
+      attr_reader :page
+      # @return [Integer,nil] Page size, or nil for an unbounded collection
+      attr_reader :size
+
+      def initialize(items:, total:, page: nil, size: nil)
+        super()
+        @items = items
+        @total = total
+        @page = page
+        @size = size
+      end
+    end
+  end
+end

data/lib/lara/models/resource_query_options.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Lara
+  module Models
+    # Optional name filtering and pagination for resource collections.
+    class ResourceQueryOptions < Base
+      # @return [String,nil] Filter by visible name (1-255 characters)
+      attr_reader :search
+      # @return [Integer,nil] Page number (1-based); enables pagination when supplied
+      attr_reader :page
+      # @return [Integer,nil] Page size (1-200); enables pagination when supplied
+      attr_reader :size
+
+      def initialize(search: nil, page: nil, size: nil)
+        super()
+        @search = search
+        @page = page
+        @size = size
+      end
+
+      # @return [Hash] Supplied options; validation and defaults are handled by the API
+      def to_params
+        { search: search, page: page, size: size }.compact
+      end
+    end
+  end
+end

data/lib/lara/models/text.rb

@@ -167,11 +167,73 @@ module Lara
       end
     end
 
+    class IntelligenceError < Base
+      attr_reader :status_code, :message
+
+      def initialize(status_code:, message:)
+        super()
+        @status_code = status_code
+        @message = message
+      end
+
+      def self.from_hash(hash)
+        return nil if hash.nil?
+
+        new(status_code: hash["statusCode"] || hash["status_code"], message: hash["message"])
+      end
+    end
+
+    class IntelligenceFailure < Base
+      attr_reader :applied, :error
+
+      def initialize(applied:, error:)
+        super()
+        @applied = applied
+        @error = IntelligenceError.from_hash(error)
+      end
+    end
+
+    # Applied is false or "partial" for reference retrieval failures.
+    class ReferenceRetrievalFailure < IntelligenceFailure
+    end
+
+    class ReasoningWarning < Base
+      attr_reader :code, :message
+
+      def initialize(code:, message:)
+        super()
+        @code = code
+        @message = message
+      end
+    end
+
+    class ReasoningFeedback < Base
+      attr_reader :applied, :error, :warnings
+
+      def initialize(applied:, error: nil, warnings: [])
+        super()
+        @applied = applied
+        @error = IntelligenceError.from_hash(error)
+        @warnings = warnings.map { |warning| ReasoningWarning.new(**warning.transform_keys(&:to_sym)) }
+      end
+    end
+
+    class TextWarnings < Base
+      attr_reader :reasoning, :references, :prosa
+
+      def initialize(reasoning: nil, references: nil, prosa: nil)
+        super()
+        @reasoning = ReasoningFeedback.new(**reasoning.transform_keys(&:to_sym)) if reasoning
+        @references = ReferenceRetrievalFailure.new(**references.transform_keys(&:to_sym)) if references
+        @prosa = IntelligenceFailure.new(**prosa.transform_keys(&:to_sym)) if prosa
+      end
+    end
+
     class TextResult < Base
       attr_reader :content_type, :source_language, :translation,
                   :adapted_to, :glossaries,
                   :adapted_to_matches, :glossaries_matches,
-                  :profanities, :styleguide_results
+                  :profanities, :styleguide_results, :warnings
 
       def self.from_hash(hash)
         return nil unless hash.is_a?(Hash)
@@ -198,13 +260,14 @@ module Lara
           adapted_to_matches: adapted_to_matches,
           glossaries_matches: glossaries_matches,
           profanities: profanities,
-          styleguide_results: styleguide_results
+          styleguide_results: styleguide_results,
+          warnings: hash["warnings"] && TextWarnings.new(**hash["warnings"].transform_keys(&:to_sym))
         )
       end
 
       def initialize(content_type:, source_language:, translation:, adapted_to: nil, glossaries: nil,
                      adapted_to_matches: nil, glossaries_matches: nil, profanities: nil,
-                     styleguide_results: nil)
+                     styleguide_results: nil, warnings: nil)
         super()
         @content_type = content_type
         @source_language = source_language
@@ -215,6 +278,7 @@ module Lara
         @glossaries_matches = glossaries_matches
         @profanities = profanities
         @styleguide_results = styleguide_results
+        @warnings = warnings
       end
 
       class << self

data/lib/lara/styleguides.rb

@@ -6,13 +6,27 @@ module Lara
       @client = client
     end
 
+    # @deprecated Use #list_paginated instead.
     # @return [Array<Lara::Models::Styleguide>]
     def list
+      warn "[DEPRECATION] list is deprecated; use list_paginated instead.", uplevel: 1
       (@client.get("/v2/styleguides") || []).map do |h|
         Lara::Models::Styleguide.new(**h.transform_keys(&:to_sym))
       end
     end
 
+    # Lists resources with optional name filtering and pagination.
+    # Without options, returns the complete collection without pagination.
+    # Any supplied option enables pagination; page and size default to 1 and 20.
+    # @param options [Lara::Models::ResourceQueryOptions,nil] Name filter and pagination
+    # @return [Lara::Models::CollectionResult] Collection containing Styleguide objects
+    def list_paginated(options = nil)
+      params = options&.to_params || {}
+      @client.get_collection("/v2/styleguides", params: params) do |item|
+        Lara::Models::Styleguide.new(**item.transform_keys(&:to_sym))
+      end
+    end
+
     # @return [Lara::Models::Styleguide]
     def create(name:, content:)
       Lara::Models::Styleguide.new(**@client.post("/v2/styleguides",

data/lib/lara/translator.rb

@@ -56,6 +56,8 @@ module Lara
     # @param verbose [Boolean]
     # @param style [String,nil]
     # @param reasoning [Boolean] When true with a block, yields partial results during reasoning
+    # @param image_context [Hash,Array<Hash>,nil] One HTTPS or base64 PNG/JPEG/WebP image; requires reasoning when non-empty.
+    #   Image validation is performed by the API. An empty array preserves text-only translation.
     # @param headers [Hash,nil]
     # @param metadata [String, Hash, nil]
     # @param profanities_detect [String,nil] One of "target", "source_target"
@@ -65,7 +67,7 @@ module Lara
     def translate(text, target:, source: nil, source_hint: nil, adapt_to: nil, glossaries: nil,
                   instructions: nil, content_type: nil, multiline: true, timeout_ms: nil,
                   priority: nil, use_cache: nil, cache_ttl_s: nil, no_trace: false, verbose: false,
-                  style: nil, reasoning: false, headers: nil, metadata: nil,
+                  style: nil, reasoning: false, image_context: nil, headers: nil, metadata: nil,
                   profanities_detect: nil, profanities_handling: nil,
                   styleguide_id: nil, styleguide_reasoning: nil,
                   styleguide_explanation_language: nil, &callback)
@@ -94,6 +96,7 @@ module Lara
         verbose: verbose,
         style: style,
         reasoning: reasoning,
+        image_context: image_context,
         metadata: metadata,
         profanities_detect: profanities_detect,
         profanities_handling: profanities_handling,

data/lib/lara/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Lara
-  VERSION = "1.9.2"
+  VERSION = "1.11.0"
 end

data/lib/lara.rb

@@ -16,6 +16,8 @@ require_relative "lara/audio"
 
 # Models
 require_relative "lara/models/base"
+require_relative "lara/models/collection_result"
+require_relative "lara/models/resource_query_options"
 require_relative "lara/models/text"
 require_relative "lara/models/memories"
 require_relative "lara/models/glossaries"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lara-sdk
 version: !ruby/object:Gem::Version
-  version: 1.9.2
+  version: 1.11.0
 platform: ruby
 authors:
 - Translated
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-15 00:00:00.000000000 Z
+date: 2026-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -161,10 +161,12 @@ files:
 - lib/lara/memories.rb
 - lib/lara/models/audio.rb
 - lib/lara/models/base.rb
+- lib/lara/models/collection_result.rb
 - lib/lara/models/documents.rb
 - lib/lara/models/glossaries.rb
 - lib/lara/models/images.rb
 - lib/lara/models/memories.rb
+- lib/lara/models/resource_query_options.rb
 - lib/lara/models/shares.rb
 - lib/lara/models/text.rb
 - lib/lara/s3_client.rb