buble 0.1.0

data/lib/buble/chat.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative 'streaming'
+
+module Buble
+  class ChatModelsResource
+    def initialize(http)
+      @http = http
+    end
+
+    def list
+      @http.request('GET', '/api/v1/models')
+    end
+  end
+
+  class ChatCompletionsResource
+    def initialize(http)
+      @http = http
+    end
+
+    def create(body = nil, **params)
+      payload = normalize_body(body, params).merge('stream' => false)
+      @http.request('POST', '/api/v1/chat/completions', body: payload)
+    end
+
+    def stream(body = nil, **params)
+      payload = normalize_body(body, params).merge('stream' => true)
+      Streaming.events_from_lines(@http.stream_lines('POST', '/api/v1/chat/completions', body: payload))
+    end
+
+    def stream_text(body = nil, **params)
+      Streaming.text_stream(stream(body, **params), :openai)
+    end
+
+    private
+
+    def normalize_body(body, params)
+      source = body || params
+      source.each_with_object({}) { |(key, value), out| out[key.to_s] = value }
+    end
+  end
+
+  class MessagesResource
+    def initialize(http)
+      @http = http
+    end
+
+    def create(body = nil, **params)
+      payload = normalize_body(body, params).merge('stream' => false)
+      @http.request('POST', '/api/v1/messages', body: payload)
+    end
+
+    def stream(body = nil, **params)
+      payload = normalize_body(body, params).merge('stream' => true)
+      Streaming.events_from_lines(@http.stream_lines('POST', '/api/v1/messages', body: payload))
+    end
+
+    def stream_text(body = nil, **params)
+      Streaming.text_stream(stream(body, **params), :anthropic)
+    end
+
+    private
+
+    def normalize_body(body, params)
+      source = body || params
+      source.each_with_object({}) { |(key, value), out| out[key.to_s] = value }
+    end
+  end
+
+  class GeminiResource
+    def initialize(http)
+      @http = http
+    end
+
+    def generate_content(model, body)
+      @http.request('POST', "/api/v1beta/models/#{HTTP.encode_model_path(model)}:generateContent", body: body)
+    end
+
+    def stream_generate_content(model, body)
+      path = "/api/v1beta/models/#{HTTP.encode_model_path(model)}:streamGenerateContent"
+      Streaming.events_from_lines(
+        @http.stream_lines('POST', path, body: body)
+      )
+    end
+
+    def stream_text(model, body)
+      Streaming.text_stream(stream_generate_content(model, body), :gemini)
+    end
+  end
+
+  class ChatResource
+    attr_reader :models, :completions, :messages, :gemini
+
+    def initialize(http)
+      @models = ChatModelsResource.new(http)
+      @completions = ChatCompletionsResource.new(http)
+      @messages = MessagesResource.new(http)
+      @gemini = GeminiResource.new(http)
+    end
+  end
+end

data/lib/buble/client.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'generations'
+require_relative 'apps'
+require_relative 'chat'
+require_relative 'files'
+require_relative 'http'
+require_relative 'media_models'
+
+module Buble
+  class Client
+    attr_reader :media_models, :files, :generations, :apps, :chat
+
+    def initialize(api_key: nil, base_url: nil, timeout: HTTP::DEFAULT_TIMEOUT, headers: {}, transport: nil)
+      resolved_api_key = first_present(api_key, ENV.fetch('BUBLE_API_KEY', nil))
+      resolved_base_url = first_present(base_url, ENV.fetch('BUBLE_BASE_URL', nil), HTTP::DEFAULT_BASE_URL)
+      @transport = transport || HTTP.new(
+        api_key: resolved_api_key,
+        base_url: resolved_base_url,
+        timeout: timeout,
+        headers: headers
+      )
+      @media_models = MediaModelsResource.new(@transport)
+      @files = FilesResource.new(@transport)
+      @generations = GenerationsResource.new(@transport)
+      @apps = AppsResource.new(@transport)
+      @chat = ChatResource.new(@transport)
+    end
+
+    private
+
+    def first_present(*values)
+      values.find { |value| value && !value.to_s.strip.empty? }
+    end
+  end
+end

data/lib/buble/errors.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Buble
+  class Error < StandardError; end
+
+  class APIError < Error
+    attr_reader :status, :code, :details, :response_body
+
+    def initialize(message, status:, code: nil, details: nil, response_body: nil)
+      super(message)
+      @status = status
+      @code = code
+      @details = details
+      @response_body = response_body
+    end
+  end
+
+  class TimeoutError < Error
+    attr_reader :timeout
+
+    def initialize(message, timeout:)
+      super(message)
+      @timeout = timeout
+    end
+  end
+
+  class GenerationFailedError < Error
+    attr_reader :task
+
+    def initialize(message, task:)
+      super(message)
+      @task = task
+    end
+  end
+
+  class GenerationCanceledError < Error
+    attr_reader :task
+
+    def initialize(message, task:)
+      super(message)
+      @task = task
+    end
+  end
+
+  class UnsupportedGenerationFieldError < Error
+    attr_reader :field
+
+    def initialize(field)
+      super(%("#{field}" is an internal Buble field and is not supported by the public API.))
+      @field = field
+    end
+  end
+end

data/lib/buble/files.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Buble
+  class FileUpload
+    attr_reader :io, :filename, :content_type, :close_after
+
+    def initialize(io:, filename:, content_type: 'application/octet-stream', close_after: false)
+      @io = io
+      @filename = filename
+      @content_type = content_type
+      @close_after = close_after
+    end
+
+    def self.from_path(path, content_type: 'application/octet-stream')
+      new(
+        io: File.open(path, 'rb'),
+        filename: File.basename(path),
+        content_type: content_type,
+        close_after: true
+      )
+    end
+
+    def self.from_io(io, filename:, content_type: 'application/octet-stream')
+      new(io: io, filename: filename, content_type: content_type, close_after: false)
+    end
+
+    def to_http_part
+      HTTP::FilePart.new(io: io, filename: filename, content_type: content_type, close_after: close_after)
+    end
+  end
+
+  class FilesResource
+    def initialize(http)
+      @http = http
+    end
+
+    def upload(file, file_type: nil, model: nil, mode: nil, **fields)
+      upload = coerce_upload(file)
+      @http.multipart(
+        '/api/v1/files',
+        fields: { file_type: file_type, model: model, mode: mode }.merge(fields),
+        file: upload.to_http_part
+      )
+    end
+
+    private
+
+    def coerce_upload(file)
+      return file if file.is_a?(FileUpload)
+      return FileUpload.from_path(file) if file.is_a?(String)
+
+      if file.respond_to?(:read)
+        filename = file.respond_to?(:path) && file.path ? File.basename(file.path) : 'upload'
+        return FileUpload.from_io(file, filename: filename)
+      end
+
+      raise Error, 'file must be a path, IO, or Buble::FileUpload.'
+    end
+  end
+end

data/lib/buble/generations.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Buble
+  class GenerationsResource
+    FORBIDDEN_FIELDS = %w[
+      input
+      options
+      scene
+      sub_mode_id
+      subModeId
+      provider
+      mediaType
+      media_type
+      images
+      image_input
+      video_input
+      audio_input
+    ].freeze
+
+    TERMINAL_STATUSES = %w[success failed canceled].freeze
+
+    def initialize(http)
+      @http = http
+    end
+
+    def create(model:, mode: nil, prompt: nil, image_urls: nil, start_frame: nil, end_frame: nil,
+               video_urls: nil, audio_urls: nil, is_public: nil, copy_protected: nil, **params)
+      body = compact_body({
+        model: model,
+        mode: mode,
+        prompt: prompt,
+        image_urls: image_urls,
+        start_frame: start_frame,
+        end_frame: end_frame,
+        video_urls: video_urls,
+        audio_urls: audio_urls,
+        is_public: is_public,
+        copy_protected: copy_protected
+      }.merge(params))
+      assert_public_body!(body)
+      @http.request('POST', '/api/v1/generations', body: body)
+    end
+
+    def retrieve(id)
+      @http.request('GET', "/api/v1/generations/#{HTTP.encode_segment(id)}")
+    end
+
+    def wait(id, interval: 2, timeout: 600, throw_on_failed: true, throw_on_canceled: true)
+      deadline = Time.now + timeout
+
+      loop do
+        envelope = retrieve(id)
+        task = envelope['data'] || {}
+        status = task['status']
+        if TERMINAL_STATUSES.include?(status)
+          raise_if_terminal_error!(id, task, status, throw_on_failed, throw_on_canceled)
+          return envelope
+        end
+
+        if Time.now >= deadline
+          raise TimeoutError.new(
+            "Generation #{id} did not finish within #{timeout} seconds.",
+            timeout: timeout
+          )
+        end
+
+        sleep interval
+      end
+    end
+
+    private
+
+    def raise_if_terminal_error!(id, task, status, throw_on_failed, throw_on_canceled)
+      if status == 'failed' && throw_on_failed
+        error = task['error'] || {}
+        raise GenerationFailedError.new(error['message'] || 'Generation failed.', task: task)
+      end
+
+      return unless status == 'canceled' && throw_on_canceled
+
+      raise GenerationCanceledError.new("Generation #{id} was canceled.", task: task)
+    end
+
+    def compact_body(body)
+      body.each_with_object({}) do |(key, value), out|
+        next if value.nil?
+        next if value.respond_to?(:empty?) && value.empty?
+
+        out[key.to_s] = value
+      end
+    end
+
+    def assert_public_body!(body)
+      body.each_key do |key|
+        raise UnsupportedGenerationFieldError, key if FORBIDDEN_FIELDS.include?(key.to_s)
+      end
+    end
+  end
+end

data/lib/buble/http.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require 'cgi/escape'
+require 'json'
+require 'net/http'
+require 'openssl'
+require 'uri'
+
+module Buble
+  class HTTP
+    DEFAULT_BASE_URL = 'https://buble.ai'
+    DEFAULT_TIMEOUT = 60
+
+    FilePart = Struct.new(:io, :filename, :content_type, :close_after, keyword_init: true) do
+      def close
+        io.close if close_after && io.respond_to?(:close) && !io.closed?
+      end
+    end
+
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT, headers: {})
+      raise Error, 'Missing Buble API key. Pass api_key or set BUBLE_API_KEY.' if blank?(api_key)
+
+      @api_key = api_key
+      @base_url = base_url.to_s.sub(%r{/+\z}, '')
+      @timeout = timeout
+      @headers = stringify_hash(headers)
+    end
+
+    def request(method, path, query: nil, body: nil, headers: nil, timeout: nil)
+      response = perform(method, path, query: query, body: body, headers: headers, timeout: timeout)
+      decode_response(response)
+    end
+
+    def multipart(path, fields:, file:, query: nil, headers: nil, timeout: nil)
+      part = coerce_file_part(file)
+      request = Net::HTTP::Post.new(resolve(path, query))
+      request_headers(headers).each { |name, value| request[name] = value }
+      request['Accept'] = 'application/json'
+
+      form = stringify_hash(fields).reject { |_key, value| value.nil? || value == '' }.map do |key, value|
+        [key, value.to_s]
+      end
+      form << ['file', part.io, { filename: part.filename, content_type: part.content_type }]
+      request.set_form(form, 'multipart/form-data')
+
+      response = start_http(request.uri, timeout || @timeout) { |http| http.request(request) }
+      decode_response(response)
+    ensure
+      part&.close
+    end
+
+    def stream_lines(method, path, query: nil, body: nil, headers: nil, timeout: nil)
+      Enumerator.new do |yielder|
+        request = build_request(method, path, query: query, body: body, headers: {
+          'Accept' => 'text/event-stream'
+        }.merge(stringify_hash(headers || {})))
+
+        buffer = +''
+        start_http(request.uri, timeout || @timeout) do |http|
+          http.request(request) do |response|
+            raise api_error(response) unless success?(response)
+
+            response.read_body do |chunk|
+              buffer << chunk
+              while (index = buffer.index("\n"))
+                line = buffer.slice!(0..index)
+                yielder << line.chomp
+              end
+            end
+          end
+        end
+        yielder << buffer unless buffer.empty?
+      end
+    end
+
+    def self.encode_segment(value)
+      CGI.escape(value.to_s).gsub('+', '%20')
+    end
+
+    def self.encode_model_path(value)
+      value.to_s.split('/').map { |segment| encode_segment(segment) }.join('/')
+    end
+
+    private
+
+    def perform(method, path, query:, body:, headers:, timeout:)
+      request = build_request(method, path, query: query, body: body, headers: headers)
+      start_http(request.uri, timeout || @timeout) { |http| http.request(request) }
+    end
+
+    def build_request(method, path, query:, body:, headers:)
+      uri = resolve(path, query)
+      request_class = request_class_for(method)
+      request = request_class.new(uri)
+      request_headers(headers).each { |name, value| request[name] = value }
+
+      unless body.nil?
+        request['Content-Type'] = 'application/json'
+        request.body = JSON.generate(body)
+      end
+
+      request
+    end
+
+    def start_http(uri, timeout, &)
+      Net::HTTP.start(
+        uri.host,
+        uri.port,
+        use_ssl: uri.scheme == 'https',
+        open_timeout: timeout,
+        read_timeout: timeout, &
+      )
+    rescue Net::OpenTimeout, Net::ReadTimeout
+      raise TimeoutError.new("Buble API request timed out after #{timeout} seconds.", timeout: timeout)
+    end
+
+    def resolve(path, query)
+      normalized = path.start_with?('/') ? path : "/#{path}"
+      uri = URI.parse("#{@base_url}#{normalized}")
+      query_hash = stringify_hash(query || {}).compact
+      uri.query = URI.encode_www_form(query_hash) unless query_hash.empty?
+      uri
+    end
+
+    def request_headers(extra)
+      {
+        'Authorization' => "Bearer #{@api_key}",
+        'Accept' => 'application/json'
+      }.merge(@headers).merge(stringify_hash(extra || {}))
+    end
+
+    def request_class_for(method)
+      case method.to_s.upcase
+      when 'GET' then Net::HTTP::Get
+      when 'POST' then Net::HTTP::Post
+      when 'PUT' then Net::HTTP::Put
+      when 'PATCH' then Net::HTTP::Patch
+      when 'DELETE' then Net::HTTP::Delete
+      else
+        raise Error, "Unsupported HTTP method: #{method}"
+      end
+    end
+
+    def decode_response(response)
+      raise api_error(response) unless success?(response)
+      return {} if response.body.nil? || response.body.empty?
+
+      content_type = response['content-type'].to_s
+      return JSON.parse(response.body) if content_type.include?('application/json')
+
+      response.body
+    rescue JSON::ParserError => e
+      raise Error, "Failed to parse Buble API response: #{e.message}"
+    end
+
+    def api_error(response)
+      body = response.body.to_s
+      message = body.empty? ? "Buble API request failed with status #{response.code}." : body
+      code = nil
+      details = nil
+
+      begin
+        decoded = body.empty? ? nil : JSON.parse(body)
+        error = decoded.is_a?(Hash) ? decoded['error'] : nil
+        if error.is_a?(Hash)
+          message = error['message'] || message
+          code = error['code']
+          details = error['details']
+        end
+      rescue JSON::ParserError
+        # Keep the raw response body as the message.
+      end
+
+      APIError.new(message, status: response.code.to_i, code: code, details: details, response_body: body)
+    end
+
+    def success?(response)
+      response.code.to_i >= 200 && response.code.to_i < 300
+    end
+
+    def coerce_file_part(file)
+      return file if file.is_a?(FilePart)
+
+      if file.is_a?(String)
+        # The multipart request owns and closes this handle after Net::HTTP consumes it.
+        # rubocop:disable Style/FileOpen
+        io = File.open(file, 'rb')
+        # rubocop:enable Style/FileOpen
+        return FilePart.new(
+          io: io,
+          filename: File.basename(file),
+          content_type: 'application/octet-stream',
+          close_after: true
+        )
+      end
+
+      if file.respond_to?(:read)
+        filename = file.respond_to?(:path) && file.path ? File.basename(file.path) : 'upload'
+        return FilePart.new(io: file, filename: filename, content_type: 'application/octet-stream', close_after: false)
+      end
+
+      raise Error, 'file must be a path, IO, or Buble::HTTP::FilePart.'
+    end
+
+    def stringify_hash(hash)
+      hash.each_with_object({}) { |(key, value), out| out[key.to_s] = value }
+    end
+
+    def blank?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+  end
+end

data/lib/buble/media_models.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Buble
+  class MediaModelsResource
+    def initialize(http)
+      @http = http
+    end
+
+    def list(media_type: nil, **query)
+      @http.request('GET', '/api/v1/media_models', query: { media_type: media_type }.merge(query))
+    end
+  end
+end

data/lib/buble/streaming.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Buble
+  module Streaming
+    Event = Struct.new(:event, :data, :json, keyword_init: true)
+
+    class SSEParser
+      def initialize
+        @event = nil
+        @data = []
+      end
+
+      def push_line(line)
+        line = line.to_s.sub(/\r\z/, '')
+        return finish_event if line.empty?
+        return nil if line.start_with?(':')
+
+        field, value = line.split(':', 2)
+        value = value ? value.sub(/\A /, '') : ''
+
+        case field
+        when 'event'
+          @event = value
+        when 'data'
+          @data << value
+        end
+        nil
+      end
+
+      def finish
+        finish_event
+      end
+
+      private
+
+      def finish_event
+        return nil if @event.nil? && @data.empty?
+
+        data = @data.join("\n")
+        json = parse_json(data)
+        event = Event.new(event: @event, data: data, json: json)
+        @event = nil
+        @data = []
+        event
+      end
+
+      def parse_json(data)
+        return nil if data.empty? || data == '[DONE]'
+
+        JSON.parse(data)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+
+    module_function
+
+    def events_from_lines(lines)
+      Enumerator.new do |yielder|
+        parser = SSEParser.new
+        lines.each do |line|
+          event = parser.push_line(line)
+          yielder << event if event
+        end
+        final = parser.finish
+        yielder << final if final
+      end
+    end
+
+    def text_from_event(event, protocol)
+      return nil if event.data == '[DONE]'
+
+      body = event.json
+      return nil unless body.is_a?(Hash)
+
+      case protocol
+      when :openai
+        body.dig('choices', 0, 'delta', 'content')
+      when :anthropic
+        body.dig('delta', 'text')
+      when :gemini
+        body.dig('candidates', 0, 'content', 'parts', 0, 'text')
+      end
+    end
+
+    def text_stream(events, protocol)
+      Enumerator.new do |yielder|
+        events.each do |event|
+          text = text_from_event(event, protocol)
+          yielder << text if text && !text.empty?
+        end
+      end
+    end
+  end
+end

data/lib/buble/version.rb

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

data/lib/buble.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative 'buble/version'
+require_relative 'buble/errors'
+require_relative 'buble/client'
+
+module Buble
+end