sai-sdk 0.1.0

data/lib/sai/errors.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Sai
+  # A non-2xx response from the Sai API (the surface's +SaiError+). +code+ is the machine-readable
+  # +error+ string when the server sent one (+machine_busy+, +link_only+, ...); +message+ is the
+  # human text; +body+ is the parsed JSON body, unchanged.
+  class Error < StandardError
+    attr_reader :status, :code, :body, :retry_after
+
+    def initialize(message = nil, status: 0, code: nil, body: {}, retry_after: nil)
+      super(message)
+      @status = status
+      @code = code
+      @body = body || {}
+      @retry_after = retry_after
+    end
+  end
+
+  # The API could not be reached (DNS, TLS, timeout).
+  class ConnectionError < Error; end
+  # 400: the request was invalid, e.g. several computers and no +machine+.
+  class BadRequestError < Error; end
+  # 401: no key, or the key is unknown or revoked.
+  class AuthenticationError < Error; end
+  # 403: the key is valid but the account may not do this (plan, ownership).
+  class PermissionDeniedError < Error; end
+  # 404.
+  class NotFoundError < Error; end
+  # 409: e.g. +machine_busy+, +link_only+, approval no longer pending.
+  class ConflictError < Error; end
+  # 410 +control_closed+: the control lease has ended; +body["reason"]+ says why. Open a new one.
+  class GoneError < Error; end
+  # 429: a rate limit, or a free-plan budget that resets daily.
+  class RateLimitError < Error; end
+  # 503: the computer did not come online, or no capacity. Honor +retry_after+.
+  class ServiceUnavailableError < Error; end
+
+  # A control helper's Simulang block failed on the computer. +kind+ is +exception+, +timeout+ or
+  # +interrupted+.
+  class BlockError < Error
+    attr_reader :kind
+
+    def initialize(kind, message)
+      super("#{kind}: #{message}", code: kind)
+      @kind = kind
+    end
+  end
+
+  # The approval must be answered by a human in a browser: open +approval_url+.
+  class LinkOnlyApprovalError < ConflictError
+    def approval_url
+      url = body["approvalUrl"]
+      url.is_a?(String) ? url : nil
+    end
+  end
+
+  # 403 +spend_cap_reached+: the key reached its monthly spend limit, or (on a cloud machine
+  # create, +body["scope"] == "tenant"+) the Tenant reached its budget. Not retryable: the limit
+  # resets at +resets_at+ (ISO 8601), or raise it for the key in the portal.
+  class SpendCapReachedError < PermissionDeniedError
+    def resets_at
+      at = body["resetsAt"]
+      at.is_a?(String) ? at : nil
+    end
+  end
+
+  # @api private
+  module Errors
+    BY_CODE = {
+      "link_only" => LinkOnlyApprovalError,
+      "spend_cap_reached" => SpendCapReachedError
+    }.freeze
+
+    BY_STATUS = {
+      400 => BadRequestError,
+      401 => AuthenticationError,
+      403 => PermissionDeniedError,
+      404 => NotFoundError,
+      409 => ConflictError,
+      410 => GoneError,
+      429 => RateLimitError,
+      503 => ServiceUnavailableError
+    }.freeze
+
+    module_function
+
+    def for(status, body, retry_after)
+      err = body["error"]
+      detail = body["message"]
+      # Two body shapes: { error: "<human text>" } (/v1/agents) and
+      # { error: "<code>", message: "<human text>" } (/v1/machines/{id}/control, newer errors).
+      code = err.is_a?(String) && (body.key?("message") || looks_like_code?(err)) ? err : nil
+      message = if detail.is_a?(String) then detail
+                elsif err.is_a?(String) then err
+                else "HTTP #{status}"
+                end
+      message += " (SAI_API_KEY was rejected: it may be revoked.)" if status == 401
+      cls = BY_CODE[code] || BY_STATUS[status] || Error
+      # The Retry-After header wins; retryAfterSeconds is the same value in the body (rate_limited).
+      wait = retry_after
+      wait = body["retryAfterSeconds"] if wait.nil? && body["retryAfterSeconds"].is_a?(Numeric)
+      cls.new(message, status: status, code: code, body: body, retry_after: wait)
+    end
+
+    def looks_like_code?(s)
+      !s.empty? && !s.include?(" ") && s == s.downcase
+    end
+  end
+end

data/lib/sai/http.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+
+module Sai
+  DEFAULT_BASE_URL = "https://api.simular.ai"
+
+  # @api private
+  # The one place requests are made: auth header, error mapping, timeouts.
+  class Http
+    Response = Struct.new(:status, :reason, :body, :headers, keyword_init: true)
+
+    # +credential+ is the bearer token, or a callable that returns it before each request.
+    def initialize(credential, base_url, timeout, version_tag)
+      @credential = credential
+      @base_url = base_url.sub(%r{/+\z}, "")
+      @timeout = timeout
+      @headers = { "User-Agent" => "sai-ruby/#{VERSION}" }
+      @headers["Authorization"] = "Bearer #{credential}" unless credential.respond_to?(:call)
+      # routes the request to a tagged API revision
+      @headers["x-sai-version"] = version_tag if version_tag && !version_tag.empty?
+    end
+
+    def request(method, path, json: UNSET, params: nil, body: nil, headers: nil, timeout: nil)
+      uri = URI(@base_url + path)
+      query = (params || {}).reject { |_, v| v.nil? }
+      uri.query = URI.encode_www_form(query.map { |k, v| [k.to_s, v.to_s] }) unless query.empty?
+      req = Net::HTTPGenericRequest.new(
+        method, !body.nil? || !json.equal?(UNSET), true, uri.request_uri
+      )
+      @headers.merge(headers || {}).each { |k, v| req[k] = v }
+      req["Authorization"] = "Bearer #{@credential.call}" if @credential.respond_to?(:call)
+      if !json.equal?(UNSET)
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(json)
+      elsif body
+        req.body = body
+      end
+      res = perform(uri, req, timeout || @timeout)
+      raise to_error(res) if res.status >= 400
+
+      res
+    end
+
+    def json(method, path, **opts)
+      res = request(method, path, **opts)
+      text = res.body.to_s.dup.force_encoding(Encoding::UTF_8)
+      text.empty? ? nil : JSON.parse(text)
+    end
+
+    UNSET = Object.new.freeze
+
+    private
+
+    def perform(uri, req, timeout)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http.write_timeout = timeout
+      res = http.start { http.request(req) }
+      headers = {}
+      res.each_header { |k, v| headers[k] = v }
+      Response.new(status: res.code.to_i, reason: res.message.to_s, body: (res.body || "").b, headers: headers)
+    rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout
+      raise ConnectionError, "Request to #{host(uri)} timed out."
+    rescue SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError => e
+      raise ConnectionError,
+            "Could not reach the Sai API at #{host(uri)}: #{e.message}. Check the network and SAI_API_URL."
+    end
+
+    def host(uri)
+      uri.port == uri.default_port ? uri.host : "#{uri.host}:#{uri.port}"
+    end
+
+    def to_error(res)
+      text = res.body.dup.force_encoding(Encoding::UTF_8)
+      body = begin
+        parsed = JSON.parse(text)
+        if parsed.is_a?(Hash) then parsed
+        elsif parsed.is_a?(Array) then { "error" => parsed.join(",") }
+        else { "error" => parsed.nil? ? "null" : parsed.to_s }
+        end
+      rescue JSON::ParserError
+        short = text[0, 500]
+        { "error" => short.nil? || short.empty? ? res.reason : short }
+      end
+      Errors.for(res.status, body, retry_after(res.headers["retry-after"]))
+    end
+
+    def retry_after(raw)
+      return nil if raw.nil? || raw.strip.empty?
+
+      v = Float(raw)
+      v == v.floor ? v.to_i : v
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/sai/learn.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module Sai
+  # Learn (research preview): turn recorded turns, or a task the agent does first, into Simulang
+  # code you own; repair that code; run, judge and repair it on a machine until it passes.
+  class Learn
+    # A conversion is two model calls of up to a minute or two each, plus one retry.
+    TIMEOUT = 600
+    # How often +wait+ reads a learn job; a job's steps take tens of seconds to minutes.
+    POLL_INTERVAL = 10
+    # Options sent as given, by their API name.
+    PASSTHROUGH = {
+      history: "history",
+      runs_without_reset: "runsWithoutReset",
+      max_iterations: "maxIterations",
+      rollouts: "rollouts",
+      reset: "reset",
+      judge_initial_agent_run: "judgeInitialAgentRun",
+      continue_with_agent: "continueWithAgent",
+      rollout_minutes: "rolloutMinutes",
+      agent_run_minutes: "agentRunMinutes",
+      continuation_minutes: "continuationMinutes",
+      max_job_minutes: "maxJobMinutes",
+      model: "model",
+      idempotency_key: "idempotency_key"
+    }.freeze
+    private_constant :PASSTHROUGH
+
+    # @api private
+    def initialize(http)
+      @http = http
+    end
+
+    # Make Simulang code, and optionally run, judge and repair it on a machine.
+    #
+    # - +create([turn])+: code from recorded turns (one session, each sent with
+    #   +record_trajectory: true+). Answers with the code.
+    # - +create(initial_code:, guidance: or evaluations:)+: a repair. Answers with the code.
+    # - +create(turns, max_iterations: 3)+ or +create(task_template:, inputs:, max_iterations: 3)+:
+    #   a job on the machine. Answers at once with +status == "running"+; read it with +wait+.
+    #
+    # +criteria+ is a sentence or a list of Check; +reset+ is +{ code: }+ or +{ task: }+;
+    # +evaluations+ a list of Evaluation. +template+ and +feedback+ are the old names of
+    # +task_template+ and +guidance+. +timeout+ is in seconds.
+    # @return [LearnResult]
+    def create(turns = [], task_template: nil, template: nil, inputs: nil, initial_code: nil, evaluations: nil,
+               guidance: nil, feedback: nil, machine: nil, criteria: nil, timeout: TIMEOUT, **options)
+      unknown = options.keys - PASSTHROUGH.keys
+      raise ArgumentError, "unknown keyword#{'s' if unknown.length > 1}: #{unknown.join(', ')}" unless unknown.empty?
+
+      body = { "turns" => turns.map { |t| Util.turn_id(t) } }
+      # The old names go out as sent, so code that uses them keeps working with an older API.
+      if !task_template.nil? then body["taskTemplate"] = task_template
+      elsif !template.nil? then body["template"] = template
+      end
+      body["inputs"] = inputs unless inputs.nil?
+      body["initialCode"] = initial_code unless initial_code.nil?
+      body["evaluations"] = evaluations.map { |e| Evaluation.to_api(e) } if evaluations
+      if !guidance.nil? then body["guidance"] = guidance
+      elsif !feedback.nil? then body["feedback"] = feedback
+      end
+      body["machineId"] = Util.id_of(machine) unless machine.nil?
+      body["criteria"] = Check.list_to_api(criteria) unless criteria.nil?
+      PASSTHROUGH.each { |k, name| body[name] = options[k] unless options[k].nil? }
+      LearnResult.parse(Parse.obj(@http.json("POST", "/v1/agents/learn", json: body, timeout: timeout)))
+    end
+
+    # A learn call's result, or a job's progress so far.
+    # @return [LearnResult]
+    def get(learn_id)
+      LearnResult.parse(Parse.obj(@http.json("GET", "/v1/agents/learn/#{Util.q(learn_id)}")))
+    end
+
+    # Read a learn job (a LearnResult or its id) until it ends (+succeeded+, +failed+ or
+    # +stopped+), every +poll_interval+ seconds. +timeout+ (seconds) raises Timeout::Error with the
+    # job still running; it keeps running.
+    # @return [LearnResult]
+    def wait(job, timeout: nil, poll_interval: POLL_INTERVAL)
+      learn_id = Util.id_of(job)
+      deadline = timeout.nil? ? nil : Util.monotonic + timeout
+      loop do
+        begin
+          r = get(learn_id)
+        rescue RateLimitError => e
+          sleep(e.retry_after.nil? ? 30 : e.retry_after)
+          next
+        end
+        return r if r.status != "running"
+        raise Timeout::Error, "Learn job #{learn_id} is still running." if deadline && Util.monotonic + poll_interval > deadline
+
+        sleep(poll_interval)
+      end
+    end
+
+    # Stop a learn job at once, whatever step it is on. It keeps the last complete results.
+    # @return [nil]
+    def cancel(job)
+      @http.json("POST", "/v1/agents/learn/#{Util.q(Util.id_of(job))}/cancel")
+      nil
+    end
+
+    # One run of a learn job's code: what it returned and logged, and its judgement.
+    # @return [LearnRun]
+    def rollout(job, iteration, rollout)
+      path = "/v1/agents/learn/#{Util.q(Util.id_of(job))}/iterations/#{iteration}/rollouts/#{rollout}"
+      LearnRun.parse(Parse.obj(@http.json("GET", path)))
+    end
+  end
+
+  # Judge recorded turns against new criteria (research preview).
+  class Judge
+    TIMEOUT = 180
+
+    # @api private
+    def initialize(http)
+      @http = http
+    end
+
+    # Judge recorded +turns+ (one session, as one task) against +criteria+: a sentence for a model
+    # to judge, or a list of Check. Nothing runs again, and the turns do not change. +task+
+    # defaults to the first turn's message.
+    # @return [Judgement]
+    def create(turns, criteria, task: nil, idempotency_key: nil, timeout: TIMEOUT)
+      body = { "turns" => turns.map { |t| Util.turn_id(t) }, "criteria" => Check.list_to_api(criteria) }
+      body["task"] = task unless task.nil?
+      body["idempotency_key"] = idempotency_key unless idempotency_key.nil?
+      Judgement.parse(Parse.obj(@http.json("POST", "/v1/agents/judge", json: body, timeout: timeout)))
+    end
+
+    # @return [Judgement]
+    def get(judgement_id)
+      Judgement.parse(Parse.obj(@http.json("GET", "/v1/agents/judge/#{Util.q(judgement_id)}")))
+    end
+  end
+end

data/lib/sai/machines.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Sai
+  # The computers Sai works on: cloud computers, or the customer's own PC with the Sai app.
+  class Machines
+    # @api private
+    def initialize(http)
+      @http = http
+    end
+
+    # @return [Array<Machine>]
+    def list
+      d = @http.json("GET", "/v1/agents/machines") || {}
+      Parse.list(d["machines"]).map { |m| Machine.parse(m) }
+    end
+
+    # @raise [NotFoundError] when the machine is not on this account
+    def get(machine_id)
+      m = list.find { |x| x.id == machine_id }
+      raise NotFoundError.new("Machine #{machine_id} not found on this account.", status: 404) unless m
+
+      m
+    end
+
+    # The live screen: +live_url+, a page a person can open without a Simular sign-in, and a
+    # Guacamole tunnel for a viewer of your own. The machine must be running.
+    # @return [LiveView]
+    def live(machine)
+      id = Util.id_of(machine)
+      d = @http.json("POST", "/v1/agents/machines/#{Util.q(id)}/live") || {}
+      LiveView.new(
+        machine_id: Parse.str(d["machineId"]) || id,
+        live_url: Parse.str(d["liveUrl"]),
+        expires_at: Parse.num_or_nil(d["expiresAt"]),
+        websocket_url: d["websocketUrl"].to_s,
+        width: Parse.num(d["width"]),
+        height: Parse.num(d["height"])
+      )
+    end
+
+    # Revokes every +live_url+ handed out for the machine.
+    # @return [Integer] how many were revoked
+    def revoke_live(machine)
+      d = @http.json("DELETE", "/v1/agents/machines/#{Util.q(Util.id_of(machine))}/live")
+      Parse.num(Parse.obj(d)["revoked"])
+    end
+  end
+end