mindee-lite 5.0.0.beta1

data/CONTRIBUTING.md

@@ -0,0 +1,107 @@
+# Contributing to mindee-api-ruby
+
+:+1::tada: First off, thanks for taking the time to contribute! :tada::+1:
+
+The following is a set of guidelines for contributing to mindee-api-ruby which are hosted on GitHub.
+These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
+
+## Code of Conduct
+
+This project and everyone participating in it is governed by the following [Code of Conduct](CODE_OF_CONDUCT.md).
+By participating, you are expected to uphold this code.
+Please report unacceptable behavior to [contact@mindee.com](mailto:contact@mindee.com).
+
+## How Can I Contribute
+
+### Reporting Bugs
+
+Bugs are tracked as [GitHub issues](https://guides.github.com/features/issues/).
+
+To help maintainers and the community to be efficient, follow these guidelines:
+
+* **Use a clear and descriptive title** for the issue to identify the problem.
+* **Describe the exact steps which reproduce the problem** in as many details as possible.
+    When listing steps, **don't just say what you did, but explain how you did it**.
+    For example, with canvas related problem, explain if you used the mouse or a keyboard shortcut, what kind of image input it is etc...
+* **Provide specific examples to demonstrate the steps**.
+    Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples.
+    If you're providing snippets in the issue, use [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines).
+* **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior.
+* **Explain which behavior you expected to see instead and why.**
+* **If the problem wasn't triggered by a specific action**, describe what you were doing before the problem happened and share more information using the guidelines below.
+* **Can you reliably reproduce the issue?** If not, provide details about how often the problem happens and under which conditions it normally happens.
+
+> **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.
+
+Include details about your configuration and environment:
+
+* **Which version of  mindee-api-ruby are you using?**
+* **What's the name and version of the browser you're using, on which OS**?
+
+### Suggesting Enhancements
+
+Enhancement suggestions are tracked as [GitHub issues](https://guides.github.com/features/issues/).
+
+Make sure to provide the following information:
+
+* **Use a clear and descriptive title** for the issue to identify the suggestion.
+* **Provide a step-by-step description of the suggested enhancement** in as many details as possible.
+* **Provide specific examples to demonstrate the steps**. Include copy/pasteable snippets which you use in those examples, as [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines).
+* **Describe the current behavior** and **explain which behavior you expected to see instead** and why.
+* **Include screenshots and animated GIFs** which help you demonstrate the steps or point out the part of the sdk which the suggestion is related to. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) or [this tool](https://github.com/GNOME/byzanz) on Linux.
+* **Specify which version of  mindee-api-ruby you're using.**
+* **Specify the name and version of the browser and OS you're using.**
+
+### Pull Requests
+
+The process described here has several goals:
+
+- Maintain mindee SDK quality
+- Fix problems that are important to users
+- Engage the community in working toward the best possible SDK
+- Enable a sustainable system for mindee's maintainers to review contributions
+
+Please follow these steps to have your contribution considered by the maintainers:
+
+1. Follow all instructions in [the template](.github/PULL_REQUEST_TEMPLATE.md)
+2. Follow the [styleguides](#styleguides)
+
+While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted.
+
+## Styleguides
+
+### Git Commit Messages
+
+* Use the present tense ("Add feature" not "Added feature")
+* Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
+* Limit the first line to 72 characters or less
+* Reference issues and pull requests liberally after the first line
+* Consider starting the commit message with an applicable emoji, see [gitmoji](https://gitmoji.carloscuesta.me/) as a reference.
+
+Examples:
+
+* :memo: Add usage section in README
+* :sparkles: Add CONTRIBUTING file in repository
+* :bug: MyComponent - Prevent MouseEvent from firing unexpectedly
+
+### Code Styleguide
+
+We keep our code base consistent and expect Ruby code to adhere to our Rubocop styleguide,
+see the `.rubocop` file.
+
+### Local Quality Checks
+
+We use [`pre-commit`](https://pre-commit.com/) hooks to run quality and security checks before
+changes are pushed:
+
+1. Install `pre-commit`, either using `pip` or `brew`:
+   - `pip install pre-commit`
+   - `brew install pre-commit`
+2. Install project hooks:
+   - `pre-commit install`
+   - `pre-commit install --hook-type pre-push`
+
+Run hooks manually:
+
+* `pre-commit run --all-files`
+* `pre-commit run --all-files --hook-stage pre-push`

data/Gemfile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in mindee.gemspec
+
+gemspec name: ENV.fetch('MINDEE_GEM_NAME', 'mindee')
+
+group :development, :test do
+  gem 'openssl', '~> 4.0'
+  gem 'prism', '~> 1.3'
+  gem 'rake', '~> 13.3'
+  gem 'rspec', '~> 3.13'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-Present Mindee
+
+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,42 @@
+[![License: MIT](https://img.shields.io/github/license/mindee/mindee-api-ruby)](https://opensource.org/licenses/MIT) [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/mindee/mindee-api-ruby/push-main-branch.yml)](https://github.com/mindee/mindee-api-ruby) [![Gem Version](https://img.shields.io/gem/v/mindee)](https://rubygems.org/gems/mindee) [![Downloads](https://img.shields.io/gem/dt/mindee.svg)](https://rubygems.org/gems/mindee)
+
+# Mindee API Helper Library for Ruby
+
+Quickly and easily connect to Mindee's API services using Ruby.
+
+## Mindee API Versions
+This client library has support for both Mindee platform versions.
+
+### V2 - Latest
+This is the latest platform located here:
+
+https://app.mindee.com
+
+It uses **API version 2**.
+
+Consult the
+**<a href="https://docs.mindee.com/integrations/client-libraries-sdk">V2 Documentation</a>**
+
+
+### V1
+This is the platform located here:
+
+https://platform.mindee.com/
+
+It uses **API version 1**.
+
+Consult the
+<a href="https://docs.mindee.com/v1/libraries/ruby-sdk">V1 Documentation</a>
+
+## Additional Information
+
+**<a href="https://github.com/mindee/mindee-api-ruby">Source Code</a>**
+
+**<a href="https://mindee.github.io/mindee-api-ruby/">Reference Documentation</a>**
+
+**<a href="https://feedback.mindee.com/">Feedback</a>**
+
+### License
+Copyright © Mindee
+
+Available as open source under the terms of the <a href="https://opensource.org/licenses/MIT">MIT License</a>.

data/Rakefile

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'rake'
+require 'rspec/core/rake_task'
+
+is_lite_mode = ENV.fetch('MINDEE_GEM_NAME', 'mindee') == 'mindee-lite'
+
+begin
+  require 'bundler/setup'
+  require 'bundler/gem_helper'
+  Bundler::GemHelper.install_tasks(name: ENV.fetch('MINDEE_GEM_NAME', 'mindee'))
+rescue LoadError
+  puts 'although not required, bundler is recommended for running the tests'
+end
+
+task default: :spec
+exclusion_opts = is_lite_mode ? ['--tag', '~all_deps'] : []
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = exclusion_opts
+end
+unless is_lite_mode
+  require 'yard'
+  desc 'Generate documentation'
+  YARD::Rake::YardocTask.new(:doc) do |task|
+    task.files = ['lib/**/*.rb']
+  end
+
+  Rake::Task[:doc].enhance do
+    FileUtils.cp_r(
+      File.join('docs', 'code_samples'),
+      File.join('docs', '_build')
+    )
+  end
+end
+
+desc 'Run integration tests'
+RSpec::Core::RakeTask.new(:integration) do |t|
+  t.pattern = 'spec/**/*_integration.rb'
+  t.rspec_opts = ['--require', 'integration_helper'] + exclusion_opts
+end

data/Steepfile

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+D = Steep::Diagnostic
+
+target :lib do
+  signature 'sig/custom/*.rbs'
+  signature 'sig/mindee/**/*.rbs'
+
+  check 'lib/mindee/**/*.rb'
+  # check 'bin' # CLI files are ignored
+
+  # NOTE: Steep does not support some libraries:
+  # - net/http.
+  # - marcel
+  # - mini_magick
+  # - origami (my bad)
+  # Do NOT enable them.
+  # Use the stubs located at sig/custom/<library_name>.rbs instead.
+  library 'date'
+  library 'fileutils'
+  library 'logger'
+  library 'json'
+  library 'openssl'
+  library 'pathname'
+  library 'tempfile'
+  library 'time'
+  library 'uri'
+
+  configure_code_diagnostics(D::Ruby.default) # `default` diagnostics setting (applies by default)
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'mindee'
+
+# 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.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/mindee.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'optparse'
+require_relative 'v1/parser'
+require_relative 'v2/parser'
+
+def setup_main_parser
+  v1_parser = MindeeCLI::V1Parser.new(ARGV)
+  v2_parser = MindeeCLI::V2Parser.new(ARGV)
+  main_parser = OptionParser.new do |opts|
+    opts.banner = "Usage: mindee [command]"
+    opts.separator "Commands:"
+    opts.separator "  v1    Use Version 1 of the Mindee API"
+    opts.separator "  v2    Use Version 2 of the Mindee API"
+  end
+  main_command = ARGV.shift
+
+  case main_command
+  when 'v1'
+    v1_parser.execute
+  when 'v2'
+    v2_parser.execute
+  else
+    abort(main_parser.help)
+  end
+end
+
+setup_main_parser

data/bin/v1/parser.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'mindee'
+require_relative 'products'
+
+module MindeeCLI
+  # Mindee Command Line Interface
+  # V1 CLI class.
+  class V1Parser
+    # @return [Array<String>]
+    attr_reader :arguments
+
+    # @return [OptionParser]
+    attr_reader :options_parser
+
+    # @return [Parser]
+    attr_reader :product_parser
+
+    def initialize(arguments)
+      @arguments = arguments
+      @options_parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: mindee v1 product [options] file'
+        opts.separator 'Available products:'
+        opts.separator "  #{V1_PRODUCTS.keys.join("\n  ")}"
+      end
+      @product_parser = init_product_parser
+    end
+
+    # @param cli_parser [OptionParser]
+    def custom_subcommand(cli_parser)
+      cli_parser.on('-v [VERSION]', '--version [VERSION]', 'Model version for the API') do |v|
+        @options[:endpoint_version] = v
+      end
+      cli_parser.on('-a ACCOUNT_NAME', '--account ACCOUNT_NAME', 'API account name for the endpoint') do |v|
+        @options[:account_name] = v
+      end
+    end
+
+    # @return [Hash]
+    def init_product_parser
+      v1_product_parser = {}
+      V1_PRODUCTS.each do |doc_key, doc_value|
+        v1_product_parser[doc_key] = OptionParser.new do |options_parser|
+          options_parser.on('-w', '--all-words', 'Include words in response') { |v| @options[:all_words] = v }
+          options_parser.on('-k [KEY]', '--key [KEY]', 'API key for the endpoint') { |v| @options[:api_key] = v }
+          options_parser.on('-o FORMAT', '--output-format FORMAT', ['raw', 'full', 'summary'],
+                            'Format of the output (raw, full, summary). Default: summary') do |format|
+            @options[:output_format] = format
+          end
+          options_parser.on('-F', '--fix-pdf', 'Repair PDF') { @options[:repair_pdf] = true }
+
+          if doc_key != 'universal'
+            options_parser.banner = "Usage: mindee v1 #{doc_key} [options] file"
+            custom_subcommand(options_parser)
+          end
+
+          if doc_value[:async] && doc_value[:sync]
+            options_parser.on('-A', '--async', 'Call asynchronously') { |v| @options[:parse_async] = v }
+          end
+        end
+      end
+      v1_product_parser
+    end
+
+    # @param product_command [String]
+    # @param endpoint_name [String, nil]
+    # @param options [Hash]
+    # @return [Mindee::V1::Parsing::Common::ApiResponse]
+    def send(product_command, endpoint_name, options)
+      mindee_client = Mindee::V1::Client.new(api_key: options[:api_key])
+      doc_class = V1_PRODUCTS[product_command][:doc_class]
+      input_source = setup_input_source(mindee_client, options)
+      custom_endpoint = setup_endpoint(mindee_client, product_command, endpoint_name, options)
+      options[:parse_async] = !V1_PRODUCTS[product_command][:sync] if options[:parse_async].nil?
+
+      mindee_client.parse(
+        input_source,
+        doc_class,
+        options: { endpoint: custom_endpoint,
+                   enqueue: options[:parse_async] }
+      )
+    end
+
+    def print_result(result, output_format)
+      if output_format == :raw
+        puts JSON.pretty_generate(JSON.parse(result.raw_http))
+      else
+        puts output_format == :full ? result.document : result.document.inference.prediction
+      end
+    end
+
+    # @param product_command [String]
+    def execute
+      @options = { output_format: :summary }
+      product_command = @arguments.shift
+
+      abort(@options_parser.help) unless V1_PRODUCTS.include?(product_command)
+      @product_parser[product_command].parse!
+
+      if product_command == 'universal'
+        if @arguments.length < 2
+          warn "The 'universal' command requires both ENDPOINT_NAME and file arguments."
+          abort(@product_parser[product_command].help)
+        end
+        endpoint_name = @arguments[0]
+        @options[:file_path] = @arguments[1]
+      else
+        if @arguments.empty?
+          warn 'file missing'
+          abort(@product_parser[product_command].help)
+        end
+        endpoint_name = nil
+        @options[:file_path] = @arguments[0]
+      end
+
+      result = send(product_command, endpoint_name, @options)
+      print_result(result, output_format)
+    end
+
+    private
+
+    # @return [Symbol]
+    def output_format
+      @options[:output_format]&.to_sym || :summary
+    end
+
+    # @param mindee_client [Mindee::V1::Client]
+    # @param options [Hash]
+    # @return [Hash]
+    def setup_input_source(mindee_client, options)
+      if options[:file_path].start_with?('https://')
+        mindee_client.source_from_url(options[:file_path])
+      else
+        mindee_client.source_from_path(options[:file_path], repair_pdf: options[:repair_pdf])
+      end
+    end
+
+    # @param mindee_client [Mindee::V1::Client]
+    # @param product_command [String]
+    # @param endpoint_name [String, nil]
+    # @param options [Hash]
+    # @return [Mindee::HTTP::Endpoint, nil]
+    def setup_endpoint(mindee_client, product_command, endpoint_name, options)
+      return unless product_command == 'universal'
+
+      mindee_client.create_endpoint(
+        endpoint_name: endpoint_name,
+        account_name: options[:account_name],
+        version: options[:endpoint_version] || '1'
+      )
+    end
+  end
+end

data/bin/v1/products.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+V1_PRODUCTS = {
+  'universal' => {
+    description: 'Universal document type from API builder',
+    doc_class: Mindee::V1::Product::Universal::Universal,
+    sync: true,
+    async: true,
+  },
+  'barcode-reader' => {
+    description: 'Barcode Reader',
+    doc_class: Mindee::V1::Product::BarcodeReader::BarcodeReaderV1,
+    sync: true,
+    async: false,
+  },
+  'cropper' => {
+    description: 'Cropper',
+    doc_class: Mindee::V1::Product::Cropper::CropperV1,
+    sync: true,
+    async: false,
+  },
+  'financial-document' => {
+    description: 'Financial Document',
+    doc_class: Mindee::V1::Product::FinancialDocument::FinancialDocumentV1,
+    sync: true,
+    async: true,
+  },
+  'fr-bank-account-details' => {
+    description: 'Bank Account Details',
+    doc_class: Mindee::V1::Product::FR::BankAccountDetails::BankAccountDetailsV2,
+    sync: true,
+    async: false,
+  },
+  'fr-bank-statement' => {
+    description: 'Bank Statement',
+    doc_class: Mindee::V1::Product::FR::BankStatement::BankStatementV2,
+    sync: false,
+    async: true,
+  },
+  'fr-carte-nationale-d-identite' => {
+    description: "Carte Nationale d'Identité",
+    doc_class: Mindee::V1::Product::FR::IdCard::IdCardV2,
+    sync: true,
+    async: false,
+  },
+  'international-id' => {
+    description: 'International ID',
+    doc_class: Mindee::V1::Product::InternationalId::InternationalIdV2,
+    sync: false,
+    async: true,
+  },
+  'invoice' => {
+    description: 'Invoice',
+    doc_class: Mindee::V1::Product::Invoice::InvoiceV4,
+    sync: true,
+    async: true,
+  },
+  'invoice-splitter' => {
+    description: 'Invoice Splitter',
+    doc_class: Mindee::V1::Product::InvoiceSplitter::InvoiceSplitterV1,
+    sync: false,
+    async: true,
+  },
+  'multi-receipts-detector' => {
+    description: 'Multi Receipts Detector',
+    doc_class: Mindee::V1::Product::MultiReceiptsDetector::MultiReceiptsDetectorV1,
+    sync: true,
+    async: false,
+  },
+  'passport' => {
+    description: 'Passport',
+    doc_class: Mindee::V1::Product::Passport::PassportV1,
+    sync: true,
+    async: false,
+  },
+  'receipt' => {
+    description: 'Receipt',
+    doc_class: Mindee::V1::Product::Receipt::ReceiptV5,
+    sync: true,
+    async: true,
+  },
+  'resume' => {
+    description: 'Resume',
+    doc_class: Mindee::V1::Product::Resume::ResumeV1,
+    sync: false,
+    async: true,
+  },
+}.freeze