reducto_ai 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 00ad6f946c48de4c4638894e5cce87f594601c85b47ab09714289a21111f83e5
+  data.tar.gz: 4ffffbf8a965b92f7e3395604e6be7736764d37a741e7ca589cec36adf2f5dc9
+SHA512:
+  metadata.gz: 5a3a7fd5765ef62bd9e9ea56c137c8d84b75741c9dce2c152ecb19b6d95c08f489a64994d71ca4ceb513c3e1144d45cc057232f18f81c546529a5fe1ec0c999c
+  data.tar.gz: 205ba689712f16f646eba2e00f29b93e579adc68aa2966c5985dd55b5802afd0ede7b441f7eaaf1b4d3578e273d48dfe7f6f15f9667bf7c1e8af3acb0ebeb947

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-10-17
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 dpaluy
+
+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,451 @@
+# ReductoAi
+
+Ruby wrapper on [ReductoAI API](https://docs.reducto.ai/api-reference)
+
+## Installation
+
+```
+bundle add reducto_ai
+```
+
+## Usage
+
+Configure once:
+
+```ruby
+ReductoAI.configure do |config|
+  config.api_key = ENV.fetch("REDUCTO_API_KEY")
+end
+```
+
+### Choosing an action
+
+- **Parse**: Start here for any document. Converts uploads or URLs into structured chunks and OCR text so later steps can reuse the returned `job_id`.
+- **Split**: Use after parsing when you need logical sections. Provide `split_description` names/rules to segment the parsed document into labeled ranges.
+- **Extract**: Run when you need structured answers (fields, JSON). Supply instructions or schema to pull values from raw input or an existing parse `job_id`.
+- **Edit**: Generate marked-up PDFs using `document_url` plus `edit_instructions` (PDF forms supported via `form_schema`).
+- **Pipeline**: Trigger a saved Studio pipeline with `input` + `pipeline_id` to orchestrate Parse/Split/Extract/Edit in one call.
+
+### Async Operations
+
+All resources support async variants that return a `job_id` for polling:
+
+```ruby
+client = ReductoAI::Client.new
+
+# Start async parse
+# API Reference: https://docs.reducto.ai/api-reference/parse-async
+job = client.parse.async(input: "https://example.com/large-doc.pdf")
+job_id = job["job_id"]
+
+# Response:
+# {
+#   "job_id" => "async-123",
+#   "status" => "processing"
+# }
+
+# Poll for completion
+# API Reference: https://docs.reducto.ai/api-reference/get-job
+result = client.jobs.retrieve(job_id: job_id)
+
+# Response:
+# {
+#   "job_id" => "async-123",
+#   "status" => "complete",
+#   "result" => {...},
+#   "usage" => {"credits" => 1.0}
+# }
+
+# Or configure webhooks for notifications
+# API Reference: https://docs.reducto.ai/api-reference/webhook-portal
+client.jobs.configure_webhook
+```
+
+Available async methods:
+- `client.parse.async(input:, **options)` - [Parse Async API](https://docs.reducto.ai/api-reference/parse-async)
+- `client.extract.async(input:, instructions:, **options)` - [Extract Async API](https://docs.reducto.ai/api-reference/extract-async)
+- `client.split.async(input:, **options)` - [Split Async API](https://docs.reducto.ai/api-reference/split-async)
+- `client.edit.async(input:, instructions:, **options)` - [Edit Async API](https://docs.reducto.ai/api-reference/edit-async)
+- `client.pipeline.async(input:, steps:, **options)` - [Pipeline Async API](https://docs.reducto.ai/api-reference/pipeline-async)
+
+### Rails
+
+Create `config/initializers/reducto_ai.rb`:
+
+```ruby
+ReductoAI.configure do |c|
+  c.api_key = Rails.application.credentials.dig(:reducto, :api_key)
+  # c.base_url = "https://platform.reducto.ai"
+  # c.open_timeout = 5; c.read_timeout = 30
+end
+
+# Optional: override shared client (multi-tenant or custom timeouts)
+# ReductoAI.client = ReductoAI::Client.new(api_key: ..., read_timeout: 10)
+```
+
+### Quick Start
+
+```ruby
+client = ReductoAI::Client.new
+
+# Parse a document
+# API Reference: https://docs.reducto.ai/api-reference/parse
+parse = client.parse.sync(input: "https://example.com/invoice.pdf")
+job_id = parse["job_id"]
+
+# Response:
+# {
+#   "job_id" => "abc-123",
+#   "status" => "complete",
+#   "result" => {...}
+# }
+
+# Extract structured data
+# API Reference: https://docs.reducto.ai/api-reference/extract
+extraction = client.extract.sync(
+  input: job_id,
+  instructions: {
+    schema: {
+      type: "object",
+      properties: {
+        invoice_number: { type: "string" },
+        total_due: { type: "string" }
+      },
+      required: ["invoice_number", "total_due"]
+    }
+  }
+)
+
+# Response:
+# {
+#   "job_id" => "820dca1b-3215-4d24-be09-6494d4c3cd88",
+#   "usage" => {"num_pages" => 1, "num_fields" => 2, "credits" => 2.0},
+#   "studio_link" => "https://studio.reducto.ai/job/820dca1b-3115-4d24-be09-6494d4c3cd88",
+#   "result" => [{"invoice_number" => "INV-2024-001", "total_due" => "$1,234.56"}],
+#   "citations" => nil
+# }
+```
+
+### Complete Example: Multi-invoice Processing
+
+```ruby
+client = ReductoAI::Client.new
+
+# 1. Parse the document
+# API Reference: https://docs.reducto.ai/api-reference/parse
+parse = client.parse.sync(input: "https://example.com/invoices.pdf")
+
+# Response:
+# {
+#   "job_id" => "parse-123",
+#   "status" => "complete",
+#   "result" => {...}
+# }
+
+# 2. Split into individual invoices
+# API Reference: https://docs.reducto.ai/api-reference/split
+split = client.split.sync(
+  input: parse["job_id"],
+  split_description: [
+    {
+      name: "Invoice",
+      description: "All pages that belong to a single invoice",
+      partition_key: "invoice_number"
+    }
+  ],
+  split_rules: <<~PROMPT
+    The document contains multiple invoices one after another. Each invoice has a unique invoice number formatted like "Invoice #12345" near the top of the first page.
+    Segment the document into one partition per invoice. Keep pages contiguous per invoice and include any following appendices until the next invoice number.
+    Name each partition using the exact invoice number you detect (e.g., "Invoice #12345").
+  PROMPT
+)
+
+# Response:
+# {
+#   "job_id" => "split-456",
+#   "result" => {
+#     "splits" => [{
+#       "name" => "Invoice",
+#       "partitions" => [
+#         {"name" => "Invoice #12345", "pages" => [0, 1, 2]},
+#         {"name" => "Invoice #12346", "pages" => [3, 4]}
+#       ]
+#     }]
+#   }
+# }
+
+# 3. Extract data from each invoice
+# API Reference: https://docs.reducto.ai/api-reference/extract
+invoice_partitions = split.dig("result", "splits").first.fetch("partitions")
+invoice_details = invoice_partitions.map do |partition|
+  client.extract.sync(
+    input: parse["job_id"],
+    instructions: {
+      schema: {
+        type: "object",
+        properties: {
+          invoice_number: { type: "string" },
+          total_due: { type: "string" }
+        },
+        required: ["invoice_number", "total_due"]
+      }
+    },
+    settings: { page_range: partition["pages"] }
+  )
+end
+
+# Response per invoice:
+# {
+#   "job_id" => "extract-789",
+#   "result" => [{"invoice_number" => "INV-12345", "total_due" => "$2,500.00"}],
+#   "usage" => {"credits" => 2.0}
+# }
+```
+
+### Direct Split Example
+
+Split a multi-invoice PDF directly without pre-parsing:
+
+```ruby
+client = ReductoAI::Client.new
+
+# Split document directly from URL
+# API Reference: https://docs.reducto.ai/api-reference/split
+response = client.split.sync(
+  input: { url: "https://example.com/invoices.pdf" },
+  split_description: [
+    {
+      name: "Invoice",
+      description: "Individual invoices within the document",
+      partition_key: "invoice_number"
+    }
+  ]
+)
+
+# Response:
+# {
+#   "usage" => {"num_pages" => 2, "credits" => nil},
+#   "result" => {
+#     "section_mapping" => nil,
+#     "splits" => [{
+#       "name" => "Invoice",
+#       "pages" => [1, 2],
+#       "conf" => "high",
+#       "partitions" => [
+#         {"name" => "0000569050-001", "pages" => [1], "conf" => "high"},
+#         {"name" => "0000569050-002", "pages" => [2], "conf" => "high"}
+#       ]
+#     }]
+#   }
+# }
+
+# Access partitions
+partitions = response.dig("result", "splits").first["partitions"]
+# => [{"name"=>"0000569050-001", "pages"=>[1], "conf"=>"high"}, ...]
+```
+
+### Document Classification Example
+
+```ruby
+client = ReductoAI::Client.new
+
+# Parse document
+# API Reference: https://docs.reducto.ai/api-reference/parse
+parse = client.parse.sync(input: "https://example.com/document.pdf")
+
+# Extract with classification
+# API Reference: https://docs.reducto.ai/api-reference/extract
+extraction = client.extract.sync(
+  input: parse["job_id"],
+  instructions: {
+    schema: {
+      type: "object",
+      properties: {
+        document_type: {
+          type: "string",
+          enum: ["invoice", "credit", "debit"],
+          description: "Document category"
+        },
+        document_number: {
+          type: "string",
+          description: "Invoice number or equivalent identifier"
+        }
+      },
+      required: ["document_type", "document_number"]
+    }
+  },
+  settings: { citations: { enabled: false } }
+)
+
+# Response:
+# {
+#   "job_id" => "class-123",
+#   "result" => [{"document_type" => "invoice", "document_number" => "INV-2024-001"}],
+#   "usage" => {"credits" => 2.0}
+# }
+
+document_type = extraction.dig("result", 0, "document_type")
+document_number = extraction.dig("result", 0, "document_number")
+```
+
+### API Reference
+
+Full endpoint details live in the [Reducto API documentation](https://docs.reducto.ai/).
+
+### Best Practices: Cost-Efficient Document Processing
+
+Follow these patterns to minimize credit usage when processing documents:
+
+#### 1. Parse Once, Reuse Everywhere
+
+**❌ Expensive:** Calling extract/split with URLs directly
+
+```ruby
+# DON'T: Each operation parses the document again
+extract1 = client.extract.sync(input: url, instructions: schema_a)  # Parse + Extract = 2 credits
+extract2 = client.extract.sync(input: url, instructions: schema_b)  # Parse + Extract = 2 credits
+split = client.split.sync(input: url, split_description: [...])     # Parse + Split = 3 credits
+# Total: 7 credits for a 1-page document
+```
+
+**✅ Cost-efficient:** Parse once, reuse `job_id`
+
+```ruby
+# DO: Parse once, reuse the job_id
+parse = client.parse.sync(input: url)                              # 1 credit
+job_id = parse["job_id"]
+
+extract1 = client.extract.sync(input: job_id, instructions: schema_a)  # 1 credit
+extract2 = client.extract.sync(input: job_id, instructions: schema_b)  # 1 credit
+split = client.split.sync(input: job_id, split_description: [...])     # 2 credits
+# Total: 5 credits for a 1-page document (saved 2 credits)
+```
+
+#### 2. Split Before Extract for Multi-Document Files
+
+**✅ Best practice:** Split first, then extract per partition
+
+```ruby
+# 1. Parse the document once
+parse = client.parse.sync(input: "multi-invoice.pdf")  # 1 credit × 10 pages = 10 credits
+job_id = parse["job_id"]
+
+# 2. Split into partitions
+split = client.split.sync(
+  input: job_id,
+  split_description: [{ name: "Invoice", description: "..." }]
+)  # 2 credits × 10 pages = 20 credits
+
+# 3. Extract only from specific partitions
+partitions = split.dig("result", "splits").first["partitions"]
+invoices = partitions.map do |partition|
+  client.extract.sync(
+    input: job_id,
+    instructions: { schema: invoice_schema },
+    settings: { page_range: partition["pages"] }  # Extract only relevant pages
+  )
+end  # 1 credit × 10 pages = 10 credits
+
+# Total: 40 credits for 10-page document with 5 invoices
+```
+
+#### 3. Use Async for Large Documents
+
+**✅ For documents > 10 pages:** Use async to avoid timeouts
+
+```ruby
+# Parse async for large files
+job = client.parse.async(input: large_pdf_url)
+job_id = job["job_id"]
+
+# Poll or use webhooks
+loop do
+  result = client.jobs.retrieve(job_id: job_id)
+  break if result["status"] == "complete"
+  sleep 2
+end
+
+# Then reuse the job_id for split/extract
+split = client.split.sync(input: job_id, split_description: [...])
+```
+
+#### 4. Store and Reuse Parse Results
+
+**✅ For repeated processing:** Store `job_id` to avoid re-parsing
+
+```ruby
+# Store the job_id with your document record
+document.update(reducto_job_id: parse["job_id"])
+
+# Later: Extract different schemas without re-parsing
+schema_v1 = client.extract.sync(input: document.reducto_job_id, instructions: schema_v1)
+schema_v2 = client.extract.sync(input: document.reducto_job_id, instructions: schema_v2)
+# Only 2 credits instead of 4
+```
+
+#### Credit Math Summary
+
+| Operation | Direct URL | With job_id | Savings |
+|-----------|-----------|-------------|---------|
+| Parse | 1 credit/page | N/A | - |
+| Extract | 2 credits/page | 1 credit/page | 50% |
+| Split | 3 credits/page | 2 credits/page | 33% |
+| Multiple extracts (3×) | 6 credits/page | 3 credits/page | 50% |
+
+**Golden rule:** Always parse once and reuse `job_id` for all subsequent operations.
+
+### Credits & pricing overview
+
+Reducto bills every API call in credits. Current public rates are:
+
+- **Parse**: 1 credit per standard page (2 for complex VLM-enhanced pages).
+- **Extract**: 2 credits per page (4 if agent-in-loop mode is enabled). Parsing credits are also charged if you **don't** reuse a previous `job_id`.
+- **Split**: 2 credits per page when run standalone; free if you supply a prior parse job.
+- **Edit**: 4 credits per page (beta pricing).
+
+You can process ~15k credits/month before overages; additional credits are billed at **$0.015 USD** each according to [Reducto's pricing page](https://reducto.ai/pricing).
+
+#### Why Extract costs 2 credits for 1 page
+
+When you call `extract.sync(input: url, instructions: schema)` with a URL instead of a `job_id`, Reducto automatically performs two operations:
+
+1. **Parse** (1 credit): Converts PDF → structured text
+2. **Extract** (1 credit): Applies schema → structured JSON
+3. **Total: 2 credits**
+
+**Cost optimization:** Parse once, extract multiple times:
+
+```ruby
+# Parse once (1 credit)
+parse = client.parse.sync(input: "https://example.com/doc.pdf")
+job_id = parse["job_id"]
+
+# Extract multiple schemas (1 credit each)
+schema_a = client.extract.sync(input: job_id, instructions: schema_a)
+schema_b = client.extract.sync(input: job_id, instructions: schema_b)
+# Total: 3 credits instead of 4
+```
+
+#### Credit math for the examples above
+
+- **Parse → Split → Extract**: when you start with `ReductoAI.parse` and pass the resulting `job_id` to `split` and `extract`, you pay **1 + 2** = **3 credits per page** (parse + extract). Split reuses the parsed content so it doesn't add extra parse credits.
+- **Document type + number extraction**: the JSON-schema `extract` call uses an existing parse job, so it consumes **parse (1) + extract (2) = 3 credits per page**. Enabling agentic or citations may raise the per-page cost per the [credit usage guide](https://docs.reducto.ai/faq/credit-usage-overview).
+
+## Development
+
+```
+bundle exec rake test
+bundle exec rubocop
+```
+
+## TODO
+
+- [ ] Document webhook workflow and retry semantics
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/dpaluy/reducto_ai.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/reducto_ai/client.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "faraday/multipart"
+require_relative "resources/parse"
+require_relative "resources/extract"
+require_relative "resources/split"
+require_relative "resources/edit"
+require_relative "resources/pipeline"
+require_relative "resources/jobs"
+
+module ReductoAI
+  class Client
+    attr_reader :api_key, :base_url, :logger, :open_timeout, :read_timeout
+
+    def initialize(api_key: nil, base_url: nil, logger: nil, open_timeout: nil, read_timeout: nil)
+      configuration = ReductoAI.config
+
+      @api_key = api_key || configuration.api_key
+      @base_url = base_url || configuration.base_url
+      @logger = logger || configuration.logger
+      @open_timeout = open_timeout || configuration.open_timeout
+      @read_timeout = read_timeout || configuration.read_timeout
+
+      raise ArgumentError, "Missing API key for ReductoAI" if @api_key.to_s.empty?
+    end
+
+    def parse
+      @parse ||= Resources::Parse.new(self)
+    end
+
+    def extract
+      @extract ||= Resources::Extract.new(self)
+    end
+
+    def split
+      @split ||= Resources::Split.new(self)
+    end
+
+    def edit
+      @edit ||= Resources::Edit.new(self)
+    end
+
+    def pipeline
+      @pipeline ||= Resources::Pipeline.new(self)
+    end
+
+    def jobs
+      @jobs ||= Resources::Jobs.new(self)
+    end
+
+    def request(method, path, body: nil, params: nil)
+      response = execute_request(method, path, body: body, params: params)
+      log_response(method, path, response)
+      handle_response(response)
+    rescue Faraday::TimeoutError, Faraday::ConnectionFailed => e
+      raise NetworkError, "Network error: #{e.message}"
+    end
+
+    def post(path, body)
+      request(:post, path, body: body)
+    end
+
+    private
+
+    def connection
+      @connection ||= Faraday.new(url: base_url) do |faraday|
+        faraday.options.timeout = read_timeout
+        faraday.options.open_timeout = open_timeout
+        faraday.request :multipart
+        faraday.adapter Faraday.default_adapter
+      end
+    end
+
+    def handle_response(response)
+      status = response.status
+      body = response.body
+      return coerce_body(body) if success?(status)
+
+      parsed_body = parse_error_body(body)
+      return handle_auth_error(parsed_body, status) if status == 401
+      return handle_client_error(parsed_body, status) if client_error?(status)
+      return handle_server_error(parsed_body, status) if server_error?(status)
+
+      raise Error.new(error_message(status, parsed_body), status: status, body: parsed_body)
+    end
+
+    def coerce_body(body)
+      return {} if body.nil? || body.empty?
+      return body unless body.is_a?(String)
+
+      JSON.parse(body)
+    end
+
+    def parse_error_body(body)
+      return body if body.is_a?(Hash)
+      return body if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      body
+    end
+
+    def error_message(status, body)
+      detail = body.is_a?(Hash) ? (body["error"] || body["message"] || body.to_json) : body.to_s
+      "HTTP #{status}: #{detail}"
+    end
+
+    def log_response(method, path, response)
+      return unless logger
+
+      logger.debug("ReductoAI #{method.to_s.upcase} #{path} -> #{response.status}")
+    end
+
+    def success?(status)
+      (200..299).cover?(status)
+    end
+
+    def client_error?(status)
+      [400, 404, 422].include?(status)
+    end
+
+    def server_error?(status)
+      (500..599).cover?(status)
+    end
+
+    def handle_auth_error(body, status)
+      raise AuthenticationError.new("Unauthorized (401): check API key", status: status, body: body)
+    end
+
+    def handle_client_error(body, status)
+      raise ClientError.new(error_message(status, body), status: status, body: body)
+    end
+
+    def handle_server_error(body, status)
+      raise ServerError.new(error_message(status, body), status: status, body: body)
+    end
+
+    def execute_request(method, path, body:, params:)
+      connection.public_send(method, path) do |req|
+        apply_headers(req)
+        apply_body(req, body) if body
+        req.params.update(params) if params
+      end
+    end
+
+    def apply_headers(request)
+      request.headers["Authorization"] = "Bearer #{api_key}"
+      request.headers["Accept"] = "application/json"
+    end
+
+    def apply_body(request, body)
+      if multipart_body?(body)
+        request.body = body
+      else
+        request.headers["Content-Type"] = "application/json"
+        request.body = JSON.generate(body)
+      end
+    end
+
+    def multipart_body?(body)
+      return false unless body
+      return true if file_part?(body)
+
+      body.is_a?(Hash) && body.values.any? { |v| file_part?(v) }
+    end
+
+    def file_part?(value)
+      (defined?(Faraday::UploadIO) && value.is_a?(Faraday::UploadIO)) ||
+        (defined?(Faraday::Multipart::FilePart) && value.is_a?(Faraday::Multipart::FilePart))
+    end
+  end
+end

data/lib/reducto_ai/config.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module ReductoAI
+  class Config
+    attr_accessor :api_key, :base_url, :open_timeout, :read_timeout, :raise_exceptions
+    attr_writer :logger
+
+    def initialize
+      @api_key = ENV.fetch("REDUCTO_API_KEY", nil)
+      @base_url = ENV.fetch("REDUCTO_BASE_URL", "https://platform.reducto.ai")
+      @open_timeout = integer_or_default("REDUCTO_OPEN_TIMEOUT", 5)
+      @read_timeout = integer_or_default("REDUCTO_READ_TIMEOUT", 30)
+      @raise_exceptions = true
+    end
+
+    def logger
+      @logger ||= (defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger) || Logger.new($stderr)
+    end
+
+    private
+
+    def integer_or_default(key, default)
+      Integer(ENV.fetch(key, default))
+    rescue StandardError
+      default
+    end
+  end
+end

data/lib/reducto_ai/engine.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ReductoAI
+  if defined?(Rails)
+    class Engine < ::Rails::Engine
+      isolate_namespace ReductoAI
+    end
+  end
+end

data/lib/reducto_ai/errors.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ReductoAI
+  class Error < StandardError
+    attr_reader :status, :body
+
+    def initialize(message = nil, status: nil, body: nil)
+      super(message)
+      @status = status
+      @body = body
+    end
+  end
+
+  class AuthenticationError < Error; end
+  class ClientError < Error; end
+  class ServerError < Error; end
+  class NetworkError < Error; end
+end

data/lib/reducto_ai/resources/edit.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module ReductoAI
+  module Resources
+    class Edit
+      def initialize(client)
+        @client = client
+      end
+
+      def sync(input:, instructions:, **options)
+        raise ArgumentError, "input is required" if input.nil?
+        if instructions.nil? || (instructions.respond_to?(:empty?) && instructions.empty?)
+          raise ArgumentError, "instructions are required"
+        end
+
+        payload = build_payload(input, instructions, options)
+        @client.post("/edit", payload)
+      end
+
+      def async(input:, instructions:, async: nil, **options)
+        raise ArgumentError, "input is required" if input.nil?
+        if instructions.nil? || (instructions.respond_to?(:empty?) && instructions.empty?)
+          raise ArgumentError, "instructions are required"
+        end
+
+        payload = build_payload(input, instructions, options)
+        payload[:async] = async unless async.nil?
+
+        @client.post("/edit_async", payload)
+      end
+
+      private
+
+      def build_payload(input, instructions, options)
+        document_url = normalize_input(input)
+        { document_url: document_url, edit_instructions: instructions, **options }.compact
+      end
+
+      def normalize_input(input)
+        return input unless input.is_a?(Hash)
+
+        input[:url] || input["url"] || input
+      end
+    end
+  end
+end

data/lib/reducto_ai/resources/extract.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module ReductoAI
+  module Resources
+    class Extract
+      def initialize(client)
+        @client = client
+      end
+
+      def sync(input:, instructions:, **options)
+        raise ArgumentError, "input is required" if input.nil?
+        if instructions.nil? || (instructions.respond_to?(:empty?) && instructions.empty?)
+          raise ArgumentError, "instructions are required"
+        end
+
+        payload = build_payload(input, instructions, options)
+        @client.post("/extract", payload)
+      end
+
+      def async(input:, instructions:, async: nil, **options)
+        raise ArgumentError, "input is required" if input.nil?
+        if instructions.nil? || (instructions.respond_to?(:empty?) && instructions.empty?)
+          raise ArgumentError, "instructions are required"
+        end
+
+        payload = build_payload(input, instructions, options)
+        payload[:async] = async unless async.nil?
+
+        @client.post("/extract_async", payload)
+      end
+
+      private
+
+      def build_payload(input, instructions, options)
+        normalized_input = normalize_input(input)
+        normalized_instructions = normalize_instructions(instructions)
+
+        { input: normalized_input, instructions: normalized_instructions, **options }.compact
+      end
+
+      def normalize_input(input)
+        return input unless input.is_a?(Hash)
+
+        input[:url] || input["url"] || input
+      end
+
+      def normalize_instructions(instructions)
+        return { schema: instructions } unless instructions.is_a?(Hash)
+        return instructions if instructions.key?(:schema) || instructions.key?("schema")
+
+        { schema: instructions }
+      end
+    end
+  end
+end

data/lib/reducto_ai/resources/jobs.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module ReductoAI
+  module Resources
+    class Jobs
+      def initialize(client)
+        @client = client
+      end
+
+      def version
+        @client.request(:get, "/version")
+      end
+
+      def list(**options)
+        params = options.compact
+        @client.request(:get, "/jobs", params: params)
+      end
+
+      def cancel(job_id:)
+        raise ArgumentError, "job_id is required" if job_id.nil? || job_id.to_s.strip.empty?
+
+        @client.request(:post, "/cancel/#{job_id}")
+      end
+
+      def retrieve(job_id:)
+        raise ArgumentError, "job_id is required" if job_id.nil? || job_id.to_s.strip.empty?
+
+        @client.request(:get, "/job/#{job_id}")
+      end
+
+      def upload(file:, extension: nil)
+        raise ArgumentError, "file is required" if file.nil?
+
+        upload_io = build_upload_io(file)
+        body = { file: upload_io }
+        params = {}
+        params[:extension] = extension unless extension.nil?
+
+        @client.request(:post, "/upload", body: body, params: params)
+      end
+
+      def configure_webhook
+        @client.request(:post, "/configure_webhook")
+      end
+
+      private
+
+      def build_upload_io(file)
+        if file.is_a?(String)
+          raise ArgumentError, "file path does not exist" unless File.exist?(file)
+
+          filename = File.basename(file)
+        else
+          filename = if file.respond_to?(:path) && file.path
+                       File.basename(file.path)
+                     else
+                       "upload"
+                     end
+
+        end
+        Faraday::UploadIO.new(file, "application/octet-stream", filename)
+      end
+    end
+  end
+end

data/lib/reducto_ai/resources/parse.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ReductoAI
+  module Resources
+    class Parse
+      def initialize(client)
+        @client = client
+      end
+
+      def sync(input:, **options)
+        raise ArgumentError, "input is required" if input.nil?
+
+        normalized_input = normalize_input(input)
+        payload = { input: normalized_input, **options }.compact
+        @client.post("/parse", payload)
+      end
+
+      def async(input:, async: nil, **options)
+        raise ArgumentError, "input is required" if input.nil?
+
+        normalized_input = normalize_input(input)
+        payload = { input: normalized_input }
+        payload[:async] = async unless async.nil?
+        payload.merge!(options.compact)
+
+        @client.post("/parse_async", payload)
+      end
+
+      private
+
+      def normalize_input(input)
+        return input unless input.is_a?(Hash)
+
+        input[:url] || input["url"] || input
+      end
+    end
+  end
+end

data/lib/reducto_ai/resources/pipeline.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ReductoAI
+  module Resources
+    class Pipeline
+      def initialize(client)
+        @client = client
+      end
+
+      def sync(input:, steps:, **options)
+        raise ArgumentError, "input is required" if input.nil?
+        raise ArgumentError, "steps are required" if steps.nil? || (steps.respond_to?(:empty?) && steps.empty?)
+
+        payload = { input: input, steps: steps, **options }.compact
+        @client.post("/pipeline", payload)
+      end
+
+      def async(input:, steps:, async: nil, **options)
+        raise ArgumentError, "input is required" if input.nil?
+        raise ArgumentError, "steps are required" if steps.nil? || (steps.respond_to?(:empty?) && steps.empty?)
+
+        payload = { input: input, steps: steps }
+        payload[:async] = async unless async.nil?
+        payload.merge!(options.compact)
+
+        @client.post("/pipeline_async", payload)
+      end
+    end
+  end
+end

data/lib/reducto_ai/resources/split.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ReductoAI
+  module Resources
+    class Split
+      def initialize(client)
+        @client = client
+      end
+
+      def sync(input:, **options)
+        raise ArgumentError, "input is required" if input.nil?
+
+        normalized_input = normalize_input(input)
+        payload = { input: normalized_input, **options }.compact
+        @client.post("/split", payload)
+      end
+
+      def async(input:, async: nil, **options)
+        raise ArgumentError, "input is required" if input.nil?
+
+        normalized_input = normalize_input(input)
+        payload = { input: normalized_input }
+        payload[:async] = async unless async.nil?
+        payload.merge!(options.compact)
+
+        @client.post("/split_async", payload)
+      end
+
+      private
+
+      def normalize_input(input)
+        return input unless input.is_a?(Hash)
+
+        input[:url] || input["url"] || input
+      end
+    end
+  end
+end

data/lib/reducto_ai/version.rb

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

data/lib/reducto_ai.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "reducto_ai/version"
+require_relative "reducto_ai/config"
+require_relative "reducto_ai/errors"
+require_relative "reducto_ai/client"
+require_relative "reducto_ai/engine"
+
+module ReductoAI
+  class << self
+    def config
+      @config ||= Config.new
+    end
+
+    def configure
+      yield(config)
+    end
+
+    def reset_configuration!
+      @config = nil
+    end
+  end
+end
+
+# Provide a compatibility alias without requiring Rails inflector acronym config
+ReductoAi = ReductoAI unless defined?(ReductoAi)

data/sig/reducto_ai.rbs

@@ -0,0 +1,4 @@
+module ReductoAI
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: reducto_ai
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- dpaluy
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+- !ruby/object:Gem::Dependency
+  name: faraday-multipart
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: ReductoAI provides a lightweight Faraday-based wrapper for Reducto's
+  Parse, Split, Extract, Edit, and Pipeline endpoints including async helpers and
+  Rails-friendly configuration.
+email:
+- dpaluy@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/reducto_ai.rb
+- lib/reducto_ai/client.rb
+- lib/reducto_ai/config.rb
+- lib/reducto_ai/engine.rb
+- lib/reducto_ai/errors.rb
+- lib/reducto_ai/resources/edit.rb
+- lib/reducto_ai/resources/extract.rb
+- lib/reducto_ai/resources/jobs.rb
+- lib/reducto_ai/resources/parse.rb
+- lib/reducto_ai/resources/pipeline.rb
+- lib/reducto_ai/resources/split.rb
+- lib/reducto_ai/version.rb
+- sig/reducto_ai.rbs
+homepage: https://github.com/dpaluy/reducto_ai
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/dpaluy/reducto_ai
+  source_code_uri: https://github.com/dpaluy/reducto_ai
+  changelog_uri: https://github.com/dpaluy/reducto_ai/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Ruby client for the Reducto document intelligence API.
+test_files: []