riveter-sdk 0.1.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 908379b467d0f1129dc3794df97bd927aeb3cdbdaaadd3146fe96c887f2835b9
-  data.tar.gz: a23f012aaad173284d2759f1754de5bc5cf50d1225e437445774e3bc723245bc
+  metadata.gz: 867ffe82023d427f6584d46ad9d0e0e1799bbab22ac173a66eb542859d13fd7d
+  data.tar.gz: 6906da4985f0795a6074d4b3891f02cb27ccd02009165a13e9a550bb962449a6
 SHA512:
-  metadata.gz: 38b1aac5504c3eac8c6256a0e559c02d4b5e526fb9a55de1d41214eeb0306be245c4dc991abbc17600fdabf11fc66dd96fb94383a23937575330c8c76bebcdb5
-  data.tar.gz: a3e028f0a9e5db8842770b970c94a77b1525b0480b1564ca3e63dd30804e1a45eb2c9eabc0aee475b3496b35394ae599398d6965bc8afbd7fcaaa5c98f72818b
+  metadata.gz: 2663f0f05a85eb76a748775bae906427513d103d259ff9bab9cb7a8661ad8237bfbb65e3ce35c1cf94a39215749decd733640a8e739423a1358890f88c889bad
+  data.tar.gz: 45ef4e0f5b33e003ca0bc9916d0105f23d15a7fbd03280f5cd5ab84001884e86202673e48632f3e8100eee0e5fde2f8b58a8f17852aa7df0081f4c3c6375870d

data/README.md

@@ -55,12 +55,35 @@ riveter.runs.list(status: "success").auto_paging_each do |run|
 end
 ```
 
+## Datasets
+
+A dataset is a kept table: input rows you add, output columns an enrichment fills.
+
+```ruby
+dataset = riveter.datasets.create(
+  name: "Wineries",
+  input_columns: ["Winery URL"],
+  rows: [{ "Winery URL" => "ridgewine.com" }, { "Winery URL" => "bonnydoonvineyard.com" }]
+)
+riveter.datasets.update(dataset.id, output: { "Owner" => { prompt: "The winery's current owner" } })
+fill = riveter.enrich(dataset_id: dataset.id)
+riveter.runs.wait_for_result(fill.id)
+riveter.datasets.list_rows(dataset.id).auto_paging_each do |row|
+  puts [row.input["Winery URL"], row.cells["Owner"].value].join(": ")
+end
+csv = riveter.datasets.export(dataset.id)
+```
+
+`datasets.create(prompt: ..., count: ...)` generates the rows instead (paid; pass
+`estimate_cost: true` first). `datasets.import_rows(id, csv)` appends a CSV.
+
 ## Surface
 
-- `riveter.enrich(...)`, `riveter.quick_search(...)`, `riveter.scrape(...)`, `riveter.account`
+- `riveter.enrich(...)`, `riveter.quick_search(...)`, `riveter.search_agent(...)`, `riveter.scrape(...)`, `riveter.account`
 - `riveter.runs` — `get`, `result`, `stop`, `list`, `summary`, `wait_for_result`
-- `riveter.enrichments` — `list`, `create`, `get`, `update`, `build_dataset`
-- `riveter.datasets` — `build`, `extend_dataset`
+- `riveter.enrichments` — `list`, `create`, `get`, `update`, `delete`
+- `riveter.datasets` — `list`, `create`, `get`, `update`, `delete`, `list_rows`, `add_rows`, `delete_rows`, `update_row`, `import_rows`, `build_rows`, `promote_column`, `export`
+- `riveter.tools` — `list`
 - `riveter.configured_datasets` — `build`
 - `riveter.extractions` — `create`, `get`, `run`
 - `riveter.monitors` — `create`, `list`, `get`, `update`, `runs`
@@ -71,7 +94,8 @@ via `#raw` / `#[]`.
 ## Errors and retries
 
 API failures raise `Riveter::APIError` with `#status`, `#type` (`not_found`,
-`insufficient_credits`, ...), `#message`, and optional `#details`. Network failures raise
+`insufficient_credits`, `feature_not_enabled`, ...; the known values are
+`Riveter::APIError::TYPES`), `#message`, and optional `#details`. Network failures raise
 `Riveter::APIConnectionError` / `Riveter::APITimeoutError`. 429s are retried automatically
 using the `X-RateLimit-Reset` header; 5xx and network failures are retried for GETs.
 Configure with `max_retries:` and `timeout:`.
@@ -91,5 +115,5 @@ Riveter::Client.new(
 
 ```bash
 bundle install
-bundle exec rspec
+bundle exec ruby -Ilib -e "require 'riveter'"
 ```

data/lib/riveter/client.rb

@@ -12,7 +12,7 @@ module Riveter
 
     attr_reader :base_url, :timeout, :max_retries,
                 :runs, :enrichments, :datasets, :configured_datasets,
-                :extractions, :monitors
+                :extractions, :monitors, :tools
 
     # api_key falls back to ENV["RIVETER_API_KEY"]; base_url falls back to
     # ENV["RIVETER_BASE_URL"], then production. timeout (seconds) must exceed
@@ -34,9 +34,16 @@ module Riveter
       @configured_datasets = Resources::ConfiguredDatasets.new(self)
       @extractions = Resources::Extractions.new(self)
       @monitors = Resources::Monitors.new(self)
+      @tools = Resources::Tools.new(self)
     end
 
     # Start an enrichment run on rows of input data. (operationId: enrich)
+    # Rows come from `input:` (inline) or `dataset_id:` (a Dataset); column config from
+    # `enrichment_id:`, `output:`, or `prompt:` + `attributes:`. On a
+    # Dataset, `columns:` / `rows:` / `positions:` (or `targets:` boxes) scope the fill and
+    # `states:` names the cell states to re-run (`force: true` runs every cell).
+    # `estimate_cost: true` prices the run instead of starting it; `max_credits`
+    # refuses a run whose estimated maximum exceeds it. Same on every paid method.
     def enrich(**params)
       Run.new(request(:post, "/enrich", body: params))
     end
@@ -46,6 +53,12 @@ module Riveter
       Run.new(request(:post, "/quick_search", body: params))
     end
 
+    # Ask one research question; long-polls up to `wait` seconds (default 50) and
+    # returns the answer in #output["result"]. (operationId: searchAgent)
+    def search_agent(**params)
+      Run.new(request(:post, "/search_agent", body: params))
+    end
+
     # Scrape a webpage and return its text synchronously. (operationId: scrape)
     def scrape(**params)
       ScrapeResult.new(request(:post, "/scrape", body: params))
@@ -56,18 +69,22 @@ module Riveter
       AccountInfo.new(request(:get, "/account"))
     end
 
-    def request(method, path, query: nil, body: nil, timeout: nil)
+    # `body` is sent as JSON; `raw_body:` + `content_type:` send a body as-is (CSV imports).
+    # `response_format:` is :json (an empty or 204 body is nil), :text, or :bytes.
+    def request(method, path, query: nil, body: nil, raw_body: nil, content_type: nil, response_format: :json,
+                timeout: nil)
       uri = URI.parse(@base_url + path)
       if query
         compact = query.reject { |_key, value| value.nil? }
         uri.query = URI.encode_www_form(compact) unless compact.empty?
       end
 
+      encoded_body = encode_request_body(body, raw_body, content_type)
       retry_on_failure = method == :get
       attempt = 0
       loop do
         response = begin
-          perform_http_request(method, uri, body, timeout || @timeout)
+          perform_http_request(method, uri, encoded_body, timeout || @timeout)
         rescue Net::OpenTimeout, Net::ReadTimeout => e
           if retry_on_failure && attempt < @max_retries
             sleep(backoff_seconds(attempt))
@@ -85,7 +102,7 @@ module Riveter
         end
 
         status = response.code.to_i
-        return parse_json_body(response) if status.between?(200, 299)
+        return read_success_body(response, response_format) if status.between?(200, 299)
 
         if status == 429 && attempt < @max_retries
           sleep(rate_limit_delay_seconds(response, attempt))
@@ -104,24 +121,42 @@ module Riveter
 
     private
 
-    def perform_http_request(method, uri, body, timeout)
+    REQUEST_CLASSES = {
+      get: Net::HTTP::Get, post: Net::HTTP::Post, patch: Net::HTTP::Patch, delete: Net::HTTP::Delete
+    }.freeze
+    private_constant :REQUEST_CLASSES
+
+    def perform_http_request(method, uri, encoded_body, timeout)
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = uri.scheme == "https"
       http.open_timeout = timeout
       http.read_timeout = timeout
 
-      request_class = { get: Net::HTTP::Get, post: Net::HTTP::Post, patch: Net::HTTP::Patch }.fetch(method)
-      request = request_class.new(uri)
+      request = REQUEST_CLASSES.fetch(method).new(uri)
       request["Authorization"] = "Bearer #{@api_key}"
       request["User-Agent"] = "riveter-sdk-ruby/#{VERSION}"
-      if body
-        request["Content-Type"] = "application/json"
-        request.body = JSON.generate(body.reject { |_key, value| value.nil? })
+      if encoded_body
+        request["Content-Type"] = encoded_body[:content_type]
+        request.body = encoded_body[:content]
       end
 
       http.request(request)
     end
 
+    def encode_request_body(body, raw_body, content_type)
+      return { content: raw_body, content_type: content_type || "application/octet-stream" } if raw_body
+      return nil unless body
+
+      { content: JSON.generate(body.reject { |_key, value| value.nil? }), content_type: "application/json" }
+    end
+
+    def read_success_body(response, response_format)
+      return response.body.to_s.b if response_format == :bytes
+      return response.body.to_s if response_format == :text
+
+      parse_json_body(response)
+    end
+
     def parse_json_body(response)
       return nil if response.body.nil? || response.body.empty?
 

data/lib/riveter/errors.rb

@@ -10,8 +10,19 @@ module Riveter
   # A request or wait helper exceeded its time budget.
   class APITimeoutError < APIConnectionError; end
 
-  # A non-2xx HTTP response, normalized across both error body dialects.
+  # A non-2xx HTTP response, normalized across both error body dialects. #type is one of
+  # TYPES, or a type this SDK does not know yet.
   class APIError < Error
+    # The error types the API documents. `feature_not_enabled` (403) means the account has
+    # not migrated to Datasets: stop retrying and open https://app.riveterhq.com/v2/datasets.
+    # The 409 trio (`dataset_in_use`, `enrichment_in_use`, `row_in_use`) means a fill is
+    # running: wait or stop it.
+    TYPES = %w[
+      bad_request validation not_found forbidden unauthorized feature_not_enabled
+      duplicate_run_key insufficient_credits credit_cap_exceeded not_implemented
+      dataset_in_use enrichment_in_use row_in_use payload_too_large rate_limited
+    ].freeze
+
     FALLBACK_TYPES = {
       400 => "bad_request",
       401 => "unauthorized",

data/lib/riveter/models.rb

@@ -41,17 +41,32 @@ module Riveter
           :completed_cells, :total_cells_expected, :not_found_cells
   end
 
+  # Kickoff-time estimate. #maximum is the contract — a run never charges more.
+  class CreditEstimate < Model
+    field :minimum, :maximum, :charged_upfront
+  end
+
+  # The estimate next to what has been charged. #credits_remaining and
+  # #sufficient_credits are present on estimates and credit errors only.
+  class CreditDetail < Model
+    field :credits_used, :credits_remaining, :sufficient_credits
+    model_field :estimate, CreditEstimate
+  end
+
   # The uniform run envelope returned by kickoffs and every /runs endpoint.
   # Endpoint-specific kickoff extras (dataset_id, credits_charged, ...) are
-  # plain fields; #output is nil until the run finishes.
+  # plain fields; #output is nil until the run finishes. An `estimate_cost: true`
+  # kickoff returns this shape with #estimate_cost set, no #id, and the priced
+  # #credit_detail. #legacy ({"notice", "successor", "docs"}) is set when the
+  # kickoff took a legacy mode.
   class Run < Model
-    field :id, :type, :status, :credits_used, :app_url, :result_url,
-          :started_at, :finished_at, :error, :enrichment_id, :enrichment_name,
+    field :id, :type, :status, :credits_used, :estimate_cost, :app_url, :result_url,
+          :started_at, :finished_at, :error, :stopped_reason, :enrichment_id, :enrichment_name,
           :dataset_id, :extraction_id, :monitor_id, :webhook_url, :output,
-          :max_items, :enrichment_run_id, :source_dataset_id,
-          :configured_dataset_id, :credits_charged, :variables,
-          :validation_warning, :tier
+          :max_items, :configured_dataset_id, :credits_charged, :variables,
+          :validation_warning, :tier, :legacy
     model_field :progress, RunProgress
+    model_field :credit_detail, CreditDetail
 
     def finished?
       %w[success stopped].include?(status)
@@ -60,7 +75,7 @@ module Riveter
 
   class RunListItem < Model
     field :id, :type, :status, :enrichment_id, :enrichment_name, :row_count,
-          :credits_used, :error, :created_at, :started_at, :finished_at,
+          :credits_used, :error, :stopped_reason, :created_at, :started_at, :finished_at,
           :app_url, :result_url
   end
 
@@ -72,32 +87,143 @@ module Riveter
     field :counts
   end
 
+  # Compact list-endpoint shape. Column configuration is on Enrichments#get. #status,
+  # #app_url, and #dataset_id (the dataset copy to fill instead) are set on legacy
+  # enrichments only.
   class EnrichmentSummary < Model
-    field :id, :name, :status, :app_url, :columns
+    field :id, :name, :status, :app_url, :dataset_id, :column_count, :input_columns,
+          :output_columns, :column_names_truncated, :created_at, :updated_at
   end
 
+  # An enrichment: #prompt, #input_columns, #output as an array of column hashes ("name" /
+  # "prompt" / "output_schema" / "tool"), #tools, the budget fields, and #version.
+  # #dataset_id / #app_url are set on Enrichments#create. A legacy enrichment's id answers
+  # its older shape (the legacy API docs, kept in #raw) with #legacy set.
   class Enrichment < Model
-    field :id, :name, :status, :app_url, :input, :output, :dataset_id
+    field :id, :name, :prompt, :input_columns, :output, :tools, :budget_credits_per_row,
+          :budget_locked, :version, :created_at, :updated_at, :app_url, :dataset_id, :legacy
+  end
+
+  # One cell. #state is pending / running / ok / not_found / failed / manual / stale;
+  # #reason and #error are set on failed cells only.
+  class DatasetCell < Model
+    field :value, :state, :reason, :error, :sources
+  end
+
+  # A dataset row: #input by input column name, #cells by output column name
+  # (DatasetCell each). #position is 1-based; #credits is the row's charge across its runs.
+  class DatasetRow < Model
+    field :id, :position, :input, :credits, :not_found_reason, :created_at, :updated_at
+
+    def cells
+      (@raw["cells"] || {}).transform_values { |cell| DatasetCell.new(cell) }
+    end
+  end
+
+  # A run on a dataset as the dataset lists it; #type is dataset_build or enrichment.
+  class DatasetRunSummary < Model
+    field :id, :type, :status, :created_at, :finished_at
+  end
+
+  # A dataset (ds_...). #run is set on Datasets#create / #build_rows when a build or fill
+  # started; the column configuration is on Enrichments#get(enrichment_id).
+  class Dataset < Model
+    field :id, :name, :input_columns, :index_column, :enrichment_id, :output_columns,
+          :row_count, :rows_expired, :import_in_progress, :estimate_cost, :created_at, :updated_at
+    model_field :run, Run
+    model_field :credit_detail, CreditDetail
+
+    def runs
+      (@raw["runs"] || []).map { |run| DatasetRunSummary.new(run) }
+    end
+  end
+
+  class DatasetListItem < Model
+    field :id, :name, :input_column_count, :output_column_count, :row_count, :rows_expired,
+          :created_at, :updated_at
+    model_field :newest_run, DatasetRunSummary
+  end
+
+  class DatasetRowsAdded < Model
+    field :skipped_duplicates, :row_count
+
+    def rows
+      (@raw["rows"] || []).map { |row| DatasetRow.new(row) }
+    end
+  end
+
+  class DatasetRowsDeleted < Model
+    field :deleted, :row_count
+  end
+
+  # #status is "done" when the rows landed in the call, "importing" when a job is appending
+  # them (Datasets#get reports #import_in_progress until it does).
+  class DatasetImportResult < Model
+    field :row_count
+
+    def status
+      import_hash["status"]
+    end
+
+    def rows
+      import_hash["rows"]
+    end
+
+    def rows_added
+      import_hash["rows_added"]
+    end
+
+    def skipped_duplicates
+      import_hash["skipped_duplicates"]
+    end
+
+    private
+
+    def import_hash
+      @raw["import"] || {}
+    end
+  end
+
+  class ToolCatalogEntry < Model
+    field :name, :credits_per_call, :price_note, :default, :requires_opt_in, :enabled,
+          :requires_api_key, :api_key_linked, :companions, :inputs, :input_groups, :returns
+  end
+
+  # Every tool with its price, whether this account may use it, and the budget defaults.
+  class ToolCatalog < Model
+    field :budget
+
+    def tools
+      (@raw["tools"] || []).map { |tool| ToolCatalogEntry.new(tool) }
+    end
   end
 
   class Extraction < Model
     field :id, :name, :status, :app_url, :starting_url, :goal_description,
           :output_record_json_schema, :required_keys, :locked,
           :validation_passing, :discovered_at, :run_credits_required,
-          :credits_charged
+          :credits_charged, :estimate_cost
+    model_field :credit_detail, CreditDetail
   end
 
+  # A monitor fills #dataset_id's #columns (every output column when nil) again on a
+  # schedule. #enrichment_name and #has_input belong to a monitor on a legacy enrichment;
+  # #legacy is true on such a list item and the notice hash on Monitors#get / #update. An
+  # `estimate_cost: true` create returns this shape with #estimate_cost set, no #id, and
+  # the priced #credit_detail for one tick.
   class Monitor < Model
     field :id, :name, :enabled, :cadence, :minute, :hour, :day_of_week,
           :day_of_month, :timezone, :webhook_url, :alert_rule, :output_format,
-          :next_run_at, :schedule_summary, :enrichment_id, :enrichment_name,
-          :created_at, :has_input
+          :next_run_at, :schedule_summary, :dataset_id, :dataset_name, :columns,
+          :enrichment_id, :enrichment_name, :created_at, :has_input, :legacy, :estimate_cost
+    model_field :credit_detail, CreditDetail
   end
 
   # Synchronous scrape result (legacy request_status format, per the spec).
   class ScrapeResult < Model
     field :request_status, :text, :url, :base_url_for_links, :status_code,
-          :possibly_blocked, :credit_used, :riveter_app_link
+          :possibly_blocked, :credit_used, :riveter_app_link, :estimate_cost
+    model_field :credit_detail, CreditDetail
   end
 
   class Credit < Model

data/lib/riveter/page.rb

@@ -1,6 +1,87 @@
 # frozen_string_literal: true
 
 module Riveter
+  # One page of enrichments. #each iterates the page; #auto_paging_each walks
+  # every following page too.
+  class EnrichmentsPage
+    include Enumerable
+
+    attr_reader :enrichments, :pagination
+
+    def initialize(data, fetch_page)
+      data = data.is_a?(Hash) ? data : {}
+      @enrichments = (data["enrichments"] || []).map { |item| EnrichmentSummary.new(item) }
+      @pagination = Pagination.new(data["pagination"] || {})
+      @fetch_page = fetch_page
+    end
+
+    def each(&block)
+      @enrichments.each(&block)
+    end
+
+    def next_page?
+      (pagination.page || 1) < (pagination.total_pages || 1)
+    end
+
+    def next_page
+      EnrichmentsPage.new(@fetch_page.call((pagination.page || 1) + 1), @fetch_page)
+    end
+
+    def auto_paging_each(&block)
+      return enum_for(:auto_paging_each) unless block
+
+      page = self
+      loop do
+        page.enrichments.each(&block)
+        break unless page.next_page?
+
+        page = page.next_page
+      end
+    end
+  end
+
+  # One page of dataset rows (cursor-paginated). #each iterates the page;
+  # #auto_paging_each walks every following page too.
+  class DatasetRowsPage
+    include Enumerable
+
+    attr_reader :rows, :next_cursor, :row_count
+
+    def initialize(data, fetch_page)
+      data = data.is_a?(Hash) ? data : {}
+      @rows = (data["rows"] || []).map { |item| DatasetRow.new(item) }
+      @next_cursor = data["next_cursor"]
+      @row_count = data["row_count"]
+      @fetch_page = fetch_page
+    end
+
+    def each(&block)
+      @rows.each(&block)
+    end
+
+    def next_page?
+      !next_cursor.nil?
+    end
+
+    def next_page
+      raise Error, "No next page" unless next_page?
+
+      DatasetRowsPage.new(@fetch_page.call(next_cursor), @fetch_page)
+    end
+
+    def auto_paging_each(&block)
+      return enum_for(:auto_paging_each) unless block
+
+      page = self
+      loop do
+        page.rows.each(&block)
+        break unless page.next_page?
+
+        page = page.next_page
+      end
+    end
+  end
+
   # One page of runs. #each iterates the page; #auto_paging_each walks every
   # following page too.
   class RunsPage

data/lib/riveter/resources.rb

@@ -25,7 +25,8 @@ module Riveter
         Run.new(@client.request(:post, "/runs/#{run_id}/stop"))
       end
 
-      # List the account's runs, newest first. (operationId: listRuns)
+      # List the account's runs, newest first. Params: type:, status:, enrichment_id:,
+      # dataset_id:, monitor_id:, created_after:, created_before:, page:, per_page:. (operationId: listRuns)
       def list(**params)
         fetch_page = ->(page) { @client.request(:get, "/runs", query: params.merge(page: page)) }
         RunsPage.new(fetch_page.call(params[:page] || 1), fetch_page)
@@ -57,15 +58,20 @@ module Riveter
         @client = client
       end
 
-      # List enrichments with their output column configuration. (operationId: listEnrichments)
-      def list
-        response = @client.request(:get, "/enrichments")
-        (response["enrichments"] || []).map { |item| EnrichmentSummary.new(item) }
+      # Paginated compact list of enrichments: names, status, column names and
+      # counts. Params: status:, name:, page:, per_page:. (operationId: listEnrichments)
+      def list(**params)
+        fetch_page = ->(page) { @client.request(:get, "/enrichments", query: params.merge(page: page)) }
+        EnrichmentsPage.new(fetch_page.call(params[:page] || 1), fetch_page)
       end
 
-      # Create an enrichment (no run) from a completed dataset build. (operationId: createEnrichment)
-      def create(dataset_id:)
-        Enrichment.new(@client.request(:post, "/enrichments", body: { dataset_id: dataset_id }))
+      # Save an enrichment recipe (no run): `prompt:` + `output:` (column names, or hashes
+      # with name / prompt / output_schema / tool), optionally `name:`, `input_columns:`,
+      # `budget:`, `budget_locked:`, `only_tools:`, `additional_tools:`; an empty Dataset
+      # bound to it comes back as #dataset_id. `dataset_id:` alone takes a Dataset's own
+      # enrichment. (operationId: createEnrichment)
+      def create(**params)
+        Enrichment.new(@client.request(:post, "/enrichments", body: params))
       end
 
       # The enrichment's input columns and output column configuration. (operationId: getEnrichment)
@@ -73,32 +79,129 @@ module Riveter
         Enrichment.new(@client.request(:get, "/enrichments/#{enrichment_id}"))
       end
 
-      # Add, update, rename, delete, or reorder output columns. (operationId: updateEnrichment)
+      # Edit the recipe: `name:`, `prompt:`, `input_columns:`, `budget:`, `budget_locked:`,
+      # the tool lists, and `output:` column operations keyed by column name (add with
+      # prompt / output_schema / tool, rename, delete). (operationId: updateEnrichment)
       def update(enrichment_id, **params)
-        @client.request(:patch, "/enrichments/#{enrichment_id}", body: params)
+        Enrichment.new(@client.request(:patch, "/enrichments/#{enrichment_id}", body: params))
       end
 
-      # Build a dataset shaped for this enrichment. (operationId: buildDatasetForEnrichment)
-      def build_dataset(enrichment_id, **params)
-        Run.new(@client.request(:post, "/enrichments/#{enrichment_id}/datasets", body: params))
+      # Delete a saved recipe; datasets that used it keep their cells. Refused (409) while a
+      # fill runs on it. (operationId: deleteEnrichment)
+      def delete(enrichment_id)
+        @client.request(:delete, "/enrichments/#{enrichment_id}")
+        nil
       end
     end
 
-    # Dataset builds — generate rows from prompts or structured specs.
+    # Datasets (ds_...): kept tables of input rows and enriched cells. Fill the cells with
+    # Client#enrich(dataset_id:).
     class Datasets
       def initialize(client)
         @client = client
       end
 
-      # Build a dataset from a prompt, a structured spec, or both. (operationId: buildDataset)
-      def build(**params)
-        Run.new(@client.request(:post, "/datasets", body: params))
+      # The account's datasets, newest first (up to 200). (operationId: listDatasets)
+      def list
+        response = @client.request(:get, "/datasets")
+        (response["datasets"] || []).map { |item| DatasetListItem.new(item) }
+      end
+
+      # Create a dataset: rows sent inline (`rows:`, ≤ 100 per call), generated from
+      # `prompt:` + `count:` (a paid list build, #run on the dataset; `estimate_cost: true`
+      # prices it), or empty (`name:` / `input_columns:` alone). `enrichment_id:` binds a
+      # saved recipe; `auto_fill: true` starts the fill once the rows land. (operationId: buildDataset)
+      def create(**params)
+        Dataset.new(@client.request(:post, "/datasets", body: params))
+      end
+
+      # The dataset's columns, row count, and runs. (operationId: getDataset)
+      def get(dataset_id)
+        Dataset.new(@client.request(:get, "/datasets/#{dataset_id}"))
+      end
+
+      # Rename (`name:`), move the index column (`index_column:`), add / rename / delete
+      # input and output columns (`input_columns:` / `output:` operations keyed by column
+      # name), and set the bound enrichment's `budget:` / `budget_locked:`, in one
+      # transaction. (operationId: updateDataset)
+      def update(dataset_id, **params)
+        Dataset.new(@client.request(:patch, "/datasets/#{dataset_id}", body: params))
+      end
+
+      # Delete the dataset and its rows. Refused (409) while a run is active on it. (operationId: deleteDataset)
+      def delete(dataset_id)
+        @client.request(:delete, "/datasets/#{dataset_id}")
+        nil
+      end
+
+      # A page of rows in position order (`limit:`, `cursor:`, `updated_since:`);
+      # #auto_paging_each walks every following page. (operationId: listDatasetRows)
+      def list_rows(dataset_id, **params)
+        fetch_page = lambda do |cursor|
+          @client.request(:get, "/datasets/#{dataset_id}/rows", query: params.merge(cursor: cursor))
+        end
+        DatasetRowsPage.new(fetch_page.call(params[:cursor]), fetch_page)
+      end
+
+      # Append rows (≤ 100 per call) keyed by input column name; duplicates on the index
+      # column are skipped. Free. (operationId: addDatasetRows)
+      def add_rows(dataset_id, rows)
+        DatasetRowsAdded.new(@client.request(:post, "/datasets/#{dataset_id}/rows", body: { rows: rows }))
       end
 
-      # Generate new deduplicated rows for a completed dataset build.
-      # Named extend_dataset because Object#extend is taken. (operationId: extendDataset)
-      def extend_dataset(dataset_id, **params)
-        Run.new(@client.request(:post, "/datasets/#{dataset_id}/extend", body: params))
+      # Remove up to 100 rows by `ids:` (row_...) and / or 1-based `positions:`. (operationId: deleteDatasetRows)
+      def delete_rows(dataset_id, ids: nil, positions: nil)
+        query = { ids: ids&.join(","), positions: positions&.join(",") }
+        DatasetRowsDeleted.new(@client.request(:delete, "/datasets/#{dataset_id}/rows", query: query))
+      end
+
+      # Set a row's `input:` values and / or `cells:` by hand (nil clears one; cells land as
+      # manual). `row_id` is a row id (row_...) or a 1-based position. (operationId: updateDatasetRow)
+      def update_row(dataset_id, row_id, **params)
+        DatasetRow.new(@client.request(:patch, "/datasets/#{dataset_id}/rows/#{row_id}", body: params))
+      end
+
+      # Append a CSV whose headers are input and / or output column names (output values
+      # land as manual cells). Small files land in the call (#status "done"); big ones are
+      # appended by a job ("importing"). (operationId: importDatasetRows)
+      def import_rows(dataset_id, csv)
+        DatasetImportResult.new(
+          @client.request(:post, "/datasets/#{dataset_id}/rows/import", raw_body: csv, content_type: "text/csv")
+        )
+      end
+
+      # Generate `count:` more rows from a prompt (paid; `estimate_cost: true` prices it).
+      # The build run is #run on the dataset. (operationId: buildDatasetRows)
+      def build_rows(dataset_id, **params)
+        Dataset.new(@client.request(:post, "/datasets/#{dataset_id}/rows/build", body: params))
+      end
+
+      # Turn an output column into an input column, every row's value moving with it. (operationId: promoteDatasetColumn)
+      def promote_column(dataset_id, column)
+        Dataset.new(@client.request(:post, "/datasets/#{dataset_id}/columns/promote", body: { column: column }))
+      end
+
+      # The grid as CSV (default) or JSON Lines text, or an Excel workbook
+      # (`output_format: "xlsx"`, a binary String). (operationId: exportDataset)
+      def export(dataset_id, output_format: "csv")
+        @client.request(
+          :get, "/datasets/#{dataset_id}/export",
+          query: { output_format: output_format },
+          response_format: output_format == "xlsx" ? :bytes : :text
+        )
+      end
+    end
+
+    # The tool catalog the row agent draws from.
+    class Tools
+      def initialize(client)
+        @client = client
+      end
+
+      # Every tool with its price, whether this account may use it, its inputs, and the
+      # budget defaults. (operationId: listTools)
+      def list
+        ToolCatalog.new(@client.request(:get, "/tools"))
       end
     end
 
@@ -136,13 +239,18 @@ module Riveter
       end
     end
 
-    # Scheduled enrichment runs with webhooks.
+    # Monitors: a dataset's output columns filled again on a schedule, with diffs and webhooks.
     class Monitors
       def initialize(client)
         @client = client
       end
 
-      # Create a monitor that re-runs an enrichment on a schedule. (operationId: createMonitor)
+      # Create a monitor that fills a dataset again on a schedule: `dataset_id:` (or
+      # `enrichment_id:` naming the dataset's enrichment), the cadence fields, optionally
+      # `columns:` (output column names each tick fills; every one when omitted),
+      # `alert_rule:` (each_run / on_diff / disabled), `output_format:` (current_only /
+      # include_diffs). Creation is free; `estimate_cost: true` prices ONE tick and
+      # `max_credits` refuses the monitor when that estimate is higher. (operationId: createMonitor)
       def create(**params)
         Monitor.new(@client.request(:post, "/monitors", body: params))
       end
@@ -158,7 +266,8 @@ module Riveter
         Monitor.new(@client.request(:get, "/monitors/#{monitor_id}"))
       end
 
-      # Pause, resume, or repoint a monitor. (operationId: updateMonitor)
+      # Pause, resume, repoint the webhook, or change the `columns:` a tick fills
+      # (`columns: nil` means every output column again). (operationId: updateMonitor)
       def update(monitor_id, **params)
         Monitor.new(@client.request(:patch, "/monitors/#{monitor_id}", body: params))
       end

data/lib/riveter/version.rb

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

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: riveter-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Riveter
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-10-27 00:00:00.000000000 Z
 dependencies: []
 description: Client for the Riveter API — enrich data, build datasets, scrape pages,
   and run web searches. https://docs.riveterhq.com
@@ -32,6 +33,7 @@ licenses:
 metadata:
   homepage_uri: https://docs.riveterhq.com
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -46,7 +48,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Official Ruby SDK for the Riveter API
 test_files: []