fal 0.0.1 → 0.1.0

data/lib/fal/model.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Fal
+  # Represents a model endpoint discoverable via the Models API.
+  # Provides helpers to list, search, and fetch pricing and to run requests.
+  class Model
+    MODELS_PATH = "/models"
+
+    # @return [String]
+    attr_reader :endpoint_id
+    # Flattened metadata fields
+    # @return [String, nil]
+    attr_reader :display_name
+    # @return [String, nil]
+    attr_reader :category
+    # @return [String, nil]
+    attr_reader :description
+    # @return [String, nil]
+    attr_reader :status
+    # @return [Array<String>, nil]
+    attr_reader :tags
+    # @return [String, nil]
+    attr_reader :updated_at
+    # @return [Boolean, nil]
+    attr_reader :is_favorited
+    # @return [String, nil]
+    attr_reader :thumbnail_url
+    # @return [String, nil]
+    attr_reader :thumbnail_animated_url
+    # @return [String, nil]
+    attr_reader :model_url
+    # @return [String, nil]
+    attr_reader :github_url
+    # @return [String, nil]
+    attr_reader :license_type
+    # @return [String, nil]
+    attr_reader :date
+    # @return [Hash, nil]
+    attr_reader :group
+    # @return [Boolean, nil]
+    attr_reader :highlighted
+    # @return [String, nil]
+    attr_reader :kind
+    # @return [Array<String>, nil]
+    attr_reader :training_endpoint_ids
+    # @return [Array<String>, nil]
+    attr_reader :inference_endpoint_ids
+    # @return [String, nil]
+    attr_reader :stream_url
+    # @return [Float, nil]
+    attr_reader :duration_estimate
+    # @return [Boolean, nil]
+    attr_reader :pinned
+    # @return [Hash, nil]
+    attr_reader :openapi
+
+    # @param attributes [Hash]
+    # @param client [Fal::Client]
+    def initialize(attributes, client: Fal.client)
+      @client = client
+      reset_attributes(attributes)
+    end
+
+    # Fetch and memoize the price object for this model's endpoint.
+    # @return [Fal::Price, nil]
+    def price
+      @price ||= Fal::Price.find_by(endpoint_id: @endpoint_id, client: @client)
+    end
+
+    # Run a queued request for this model endpoint.
+    # @param input [Hash]
+    # @param webhook_url [String, nil]
+    # @return [Fal::Request]
+    def run(input:, webhook_url: nil)
+      Fal::Request.create!(endpoint_id: @endpoint_id, input: input, webhook_url: webhook_url, client: @client)
+    end
+
+    class << self
+      # Find a specific model by endpoint_id.
+      # @param endpoint_id [String]
+      # @param client [Fal::Client]
+      # @return [Fal::Model, nil]
+      def find_by(endpoint_id:, client: Fal.client)
+        response = client.get_api(MODELS_PATH, query: { endpoint_id: endpoint_id })
+        entry = Array(response && response["models"]).find { |m| m["endpoint_id"] == endpoint_id }
+        entry ? new(entry, client: client) : nil
+      end
+
+      # Iterate through models with optional search filters.
+      # @param client [Fal::Client]
+      # @param query [String, nil] Free-text search query
+      # @param category [String, nil]
+      # @param status [String, nil]
+      # @param expand [Array<String>, String, nil]
+      # @yield [Fal::Model]
+      # @return [void]
+      def each(client: Fal.client, query: nil, category: nil, status: nil, expand: nil, &block)
+        cursor = nil
+        loop do
+          query_hash = { limit: 50, cursor: cursor, q: query, category: category, status: status }.compact
+          query_hash[:expand] = expand if expand
+          response = client.get_api(MODELS_PATH, query: query_hash)
+          models = Array(response && response["models"])
+          models.each { |attributes| block.call(new(attributes, client: client)) }
+          cursor = response && response["next_cursor"]
+          break if cursor.nil?
+        end
+      end
+
+      # Return an array of models for the given filters (or all models).
+      # @param client [Fal::Client]
+      # @param query [String, nil]
+      # @param category [String, nil]
+      # @param status [String, nil]
+      # @param expand [Array<String>, String, nil]
+      # @return [Array<Fal::Model>]
+      def all(client: Fal.client, query: nil, category: nil, status: nil, expand: nil)
+        results = []
+        each(client: client, query: query, category: category, status: status, expand: expand) { |m| results << m }
+        results
+      end
+
+      # Convenience search wrapper that returns all matching models.
+      # @param client [Fal::Client]
+      # @param query [String, nil]
+      # @param category [String, nil]
+      # @param status [String, nil]
+      # @param expand [Array<String>, String, nil]
+      # @return [Array<Fal::Model>]
+      def search(query: nil, category: nil, status: nil, expand: nil, client: Fal.client)
+        all(client: client, query: query, category: category, status: status, expand: expand)
+      end
+    end
+
+    private
+
+    def reset_attributes(attributes)
+      @endpoint_id = attributes["endpoint_id"]
+
+      meta = attributes["metadata"] || {}
+      @display_name = meta["display_name"]
+      @category = meta["category"]
+      @description = meta["description"]
+      @status = meta["status"]
+      @tags = meta["tags"]
+      @updated_at = meta["updated_at"]
+      @is_favorited = meta["is_favorited"]
+      @thumbnail_url = meta["thumbnail_url"]
+      @thumbnail_animated_url = meta["thumbnail_animated_url"]
+      @model_url = meta["model_url"]
+      @github_url = meta["github_url"]
+      @license_type = meta["license_type"]
+      @date = meta["date"]
+      @group = meta["group"]
+      @highlighted = meta["highlighted"]
+      @kind = meta["kind"]
+      @training_endpoint_ids = meta["training_endpoint_ids"]
+      @inference_endpoint_ids = meta["inference_endpoint_ids"]
+      @stream_url = meta["stream_url"]
+      @duration_estimate = meta["duration_estimate"]
+      @pinned = meta["pinned"]
+
+      @openapi = attributes["openapi"]
+    end
+  end
+end

data/lib/fal/price.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Fal
+  # Represents pricing information for a model endpoint.
+  # Fetches data from the Platform API at /models and /models/pricing.
+  class Price
+    MODELS_PATH = "/models"
+    PRICING_PATH = "/models/pricing"
+
+    # Billing units returned by the pricing service.
+    module Unit
+      # Output-based units
+      IMAGES = "image"
+      VIDEOS = "video"
+      MEGAPIXELS = "megapixels"
+
+      # Compute-based units (provider-specific)
+      GPU_SECONDS = "gpu_second"
+      GPU_MINUTES = "gpu_minute"
+      GPU_HOURS = "gpu_hour"
+    end
+
+    # @return [String]
+    attr_reader :endpoint_id
+    # @return [Float]
+    attr_reader :unit_price
+    # @return [String]
+    attr_reader :unit
+    # @return [String]
+    attr_reader :currency
+
+    # @param attributes [Hash] Raw attributes from pricing API
+    # @param client [Fal::Client]
+    def initialize(attributes, client: Fal.client)
+      @client = client
+      reset_attributes(attributes)
+    end
+
+    class << self
+      # Find pricing for a specific model endpoint.
+      # @param endpoint_id [String]
+      # @param client [Fal::Client]
+      # @return [Fal::Price, nil]
+      def find_by(endpoint_id:, client: Fal.client)
+        response = client.get_api(PRICING_PATH, query: { endpoint_id: endpoint_id })
+        entry = Array(response && response["prices"]).find { |p| p["endpoint_id"] == endpoint_id }
+        entry ? new(entry, client: client) : nil
+      end
+
+      # Iterate over all prices by paging through models and fetching pricing in batches.
+      # @param client [Fal::Client]
+      # @yield [Fal::Price]
+      # @return [void]
+      def each(client: Fal.client, &block)
+        cursor = nil
+        loop do
+          models_response = client.get_api(MODELS_PATH, query: { limit: 50, cursor: cursor }.compact)
+          models = Array(models_response && models_response["models"])
+          endpoint_ids = models.map { |m| m["endpoint_id"] }.compact
+
+          if endpoint_ids.any?
+            pricing_response = client.get_api(PRICING_PATH, query: { endpoint_id: endpoint_ids })
+            Array(pricing_response && pricing_response["prices"]).each do |attributes|
+              block.call(new(attributes, client: client))
+            end
+          end
+
+          cursor = models_response && models_response["next_cursor"]
+          break if cursor.nil?
+        end
+      end
+
+      # Return an array of all prices.
+      # @param client [Fal::Client]
+      # @return [Array<Fal::Price>]
+      def all(client: Fal.client)
+        results = []
+        each(client: client) { |price| results << price }
+        results
+      end
+    end
+
+    private
+
+    def reset_attributes(attributes)
+      @endpoint_id = attributes["endpoint_id"]
+      @unit_price = attributes["unit_price"]
+      @unit = attributes["unit"]
+      @currency = attributes["currency"]
+    end
+  end
+end

data/lib/fal/price_estimate.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Fal
+  # Represents a cost estimate response from the Platform API.
+  # Computes estimates via POST /models/pricing/estimate.
+  class PriceEstimate
+    ESTIMATE_PATH = "/models/pricing/estimate"
+
+    # Supported estimate types.
+    module EstimateType
+      # @return [String]
+      HISTORICAL_API_PRICE = "historical_api_price"
+      # @return [String]
+      UNIT_PRICE = "unit_price"
+    end
+
+    # Simple value object for endpoint inputs.
+    class Endpoint
+      # @return [String]
+      attr_reader :endpoint_id
+      # @return [Integer, nil]
+      attr_reader :call_quantity
+      # @return [Float, nil]
+      attr_reader :unit_quantity
+
+      # @param endpoint_id [String]
+      # @param call_quantity [Integer, nil]
+      # @param unit_quantity [Float, nil]
+      def initialize(endpoint_id:, call_quantity: nil, unit_quantity: nil)
+        @endpoint_id = endpoint_id
+        @call_quantity = call_quantity
+        @unit_quantity = unit_quantity
+      end
+    end
+
+    # @return [String]
+    attr_reader :estimate_type
+    # @return [Float]
+    attr_reader :total_cost
+    # @return [String]
+    attr_reader :currency
+
+    # @param attributes [Hash]
+    # @param client [Fal::Client]
+    def initialize(attributes, client: Fal.client)
+      @client = client
+      reset_attributes(attributes)
+    end
+
+    class << self
+      # Create a new cost estimate.
+      # Corresponds to POST https://api.fal.ai/v1/models/pricing/estimate
+      # @param estimate_type [String] one of EstimateType constants
+      # @param endpoints [Array<Fal::PriceEstimate::Endpoint, Hash>]
+      # @param client [Fal::Client]
+      # @return [Fal::PriceEstimate]
+      def create(estimate_type:, endpoints:, client: Fal.client)
+        endpoint_map = {}
+        Array(endpoints).each do |ep|
+          endpoint = ep.is_a?(Endpoint) ? ep : Endpoint.new(**ep)
+          quantity = endpoint.unit_quantity || endpoint.call_quantity
+
+          if estimate_type == EstimateType::UNIT_PRICE
+            # Accept either unit_quantity or call_quantity (treated as units) for convenience.
+            endpoint_map[endpoint.endpoint_id] = { "unit_quantity" => quantity }
+          else
+            endpoint_map[endpoint.endpoint_id] = { "call_quantity" => quantity }
+          end
+        end
+
+        payload = {
+          estimate_type: estimate_type,
+          endpoints: endpoint_map
+        }
+
+        attributes = client.post_api(ESTIMATE_PATH, payload)
+        new(attributes, client: client)
+      end
+    end
+
+    private
+
+    def reset_attributes(attributes)
+      @estimate_type = attributes["estimate_type"]
+      @total_cost = attributes["total_cost"]
+      @currency = attributes["currency"]
+    end
+  end
+end

data/lib/fal/request.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Fal
+  # Represents a queued request submitted to a fal model endpoint.
+  # Provides helpers to create, query status, cancel, and fetch response payloads
+  # using the Queue API described in the fal docs.
+  # See: https://docs.fal.ai/model-apis/model-endpoints/queue
+  class Request
+    # Request status values returned by the Queue API.
+    module Status
+      # @return [String]
+      IN_QUEUE = "IN_QUEUE"
+      # @return [String]
+      IN_PROGRESS = "IN_PROGRESS"
+      # @return [String]
+      COMPLETED = "COMPLETED"
+    end
+
+    # @return [String] The request identifier (request_id)
+    attr_reader :id
+    # @return [String] The current status, one of Fal::Request::Status constants
+    attr_reader :status
+    # @return [Integer, nil] The current position in the queue, if available
+    attr_reader :queue_position
+    # @return [Array<Hash>, nil] Log entries when requested via logs=1
+    attr_reader :logs
+    # @return [Hash, nil] Response payload when status is COMPLETED
+    attr_reader :response
+    # @return [String] The model identifier used when creating this request
+    attr_reader :endpoint_id
+
+    # @param attributes [Hash] Raw attributes from fal Queue API
+    # @param endpoint_id [String] Model ID in "namespace/name" format
+    # @param client [Fal::Client] HTTP client to use for subsequent calls
+    def initialize(attributes, endpoint_id:, client: Fal.client)
+      @client = client
+      @endpoint_id = endpoint_id
+      reset_attributes(attributes)
+    end
+
+    class << self
+      # Create a new queued request for a model.
+      # Corresponds to POST https://queue.fal.run/{endpoint_id}
+      # Optionally appends fal_webhook query param per docs.
+      # @param endpoint_id [String]
+      # @param input [Hash]
+      # @param webhook_url [String, nil]
+      # @param client [Fal::Client]
+      # @return [Fal::Request]
+      def create!(endpoint_id:, input:, webhook_url: nil, client: Fal.client)
+        path = "/#{endpoint_id}"
+        body = input || {}
+        path = "#{path}?fal_webhook=#{CGI.escape(webhook_url)}" if webhook_url
+        attributes = client.post(path, body)
+        new(attributes, endpoint_id: endpoint_id, client: client)
+      end
+
+      # Find the current status for a given request.
+      # Corresponds to GET https://queue.fal.run/{endpoint_id}/requests/{request_id}/status
+      # @param id [String]
+      # @param endpoint_id [String]
+      # @param logs [Boolean] include logs if true
+      # @param client [Fal::Client]
+      # @return [Fal::Request]
+      def find_by!(id:, endpoint_id:, logs: false, client: Fal.client)
+        endpoint_id_without_subpath = endpoint_id.split("/").slice(0, 2).join("/")
+        attributes = client.get("/#{endpoint_id_without_subpath}/requests/#{id}/status",
+                                query: (logs ? { logs: 1 } : nil))
+        new(attributes, endpoint_id: endpoint_id, client: client)
+      end
+
+      # Stream a synchronous request using SSE and yield response chunks as they arrive.
+      # It returns a Fal::Request initialized with the last streamed data in the response field.
+      # @param endpoint_id [String]
+      # @param input [Hash]
+      # @param client [Fal::Client]
+      # @yield [chunk] yields each parsed chunk Hash from the stream
+      # @yieldparam chunk [Hash]
+      # @return [Fal::Request]
+      def stream!(endpoint_id:, input:, client: Fal.client, &block)
+        path = "/#{endpoint_id}/stream"
+        last_data = nil
+
+        Stream.new(path: path, input: input, client: client).each do |event|
+          data = event["data"]
+          last_data = data
+          block&.call(data)
+        end
+
+        # Wrap last chunk into a Request-like object for convenience
+        # Build attributes from last event, using inner response if available
+        response_payload = if last_data&.key?("response")
+                             last_data["response"]
+                           else
+                             last_data
+                           end
+        attributes = {
+          "request_id" => last_data && last_data["request_id"],
+          "status" => last_data && last_data["status"],
+          "response" => response_payload
+        }.compact
+        new(attributes, endpoint_id: endpoint_id, client: client)
+      end
+    end
+
+    # @return [String] The model ID without the subpath
+    def endpoint_id_without_subpath
+      @endpoint_id.split("/").slice(0, 2).join("/")
+    end
+
+    # Reload the current status from the Queue API.
+    # @param logs [Boolean] include logs if true
+    # @return [Fal::Request]
+    def reload!(logs: false)
+      if @status == Status::IN_PROGRESS || @status == Status::IN_QUEUE
+        attributes = @client.get("/#{endpoint_id_without_subpath}/requests/#{@id}/status",
+                                 query: (logs ? { logs: 1 } : nil))
+        reset_attributes(attributes)
+      end
+
+      @response = @client.get("/#{endpoint_id_without_subpath}/requests/#{@id}") if @status == Status::COMPLETED
+
+      self
+    end
+
+    # Attempt to cancel the request if still in queue.
+    # @return [Hash] cancellation response
+    def cancel!
+      @client.put("/#{endpoint_id_without_subpath}/requests/#{@id}/cancel")
+    end
+
+    # @return [Boolean]
+    def in_queue?
+      @status == Status::IN_QUEUE
+    end
+
+    # @return [Boolean]
+    def in_progress?
+      @status == Status::IN_PROGRESS
+    end
+
+    # @return [Boolean]
+    def completed?
+      @status == Status::COMPLETED
+    end
+
+    private
+
+    # Normalize attributes from different Queue API responses.
+    # @param attributes [Hash]
+    # @return [void]
+    def reset_attributes(attributes)
+      @id = attributes["request_id"] || @id
+      # Default to IN_QUEUE if no status provided and no previous status
+      @status = attributes["status"] || @status || Status::IN_QUEUE
+      @queue_position = attributes["queue_position"]
+      @logs = attributes["logs"]
+      @response = attributes["response"]
+    end
+  end
+end

data/lib/fal/stream.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Fal
+  # Streaming helper for Server-Sent Events from fal.run synchronous endpoints.
+  # It parses SSE lines and yields decoded event hashes with symbolized keys.
+  class Stream
+    # @return [String] endpoint path under fal.run, e.g. "/fal-ai/flux/dev/stream"
+    attr_reader :path
+
+    # @param path [String] full path under sync_base (leading slash), ex: "/fal-ai/flux/dev/stream"
+    # @param input [Hash] request input payload
+    # @param client [Fal::Client] HTTP client
+    def initialize(path:, input:, client: Fal.client)
+      @path = path
+      @input = input
+      @client = client
+    end
+
+    # Stream events; yields a Hash for each event data chunk. Blocks until stream ends.
+    # @yield [event] yields decoded event hash
+    # @yieldparam event [Hash]
+    # @return [void]
+    def each(&block)
+      buffer = ""
+      decoder = SSEDecoder.new
+
+      @client.post_stream(@path, @input, on_data: proc do |chunk, _total_bytes|
+        buffer = (buffer + chunk).gsub(/\r\n?/, "\n")
+        lines = buffer.split("\n", -1)
+        buffer = lines.pop || ""
+        lines.each do |line|
+          event = decoder.decode(line)
+          block.call(event) if event
+        end
+      end)
+    end
+
+    # Minimal SSE decoder for parsing standard server-sent event stream lines.
+    class SSEDecoder
+      def initialize
+        @event = ""
+        @data = ""
+        @id = nil
+        @retry = nil
+      end
+
+      # @param line [String]
+      # @return [Hash, nil]
+      def decode(line)
+        return flush_event if line.empty?
+        return if line.start_with?(":")
+
+        field, _, value = line.partition(":")
+        value = value.lstrip
+
+        case field
+        when "event"
+          @event = value
+        when "data"
+          @data += "#{value}\n"
+        when "id"
+          @id = value
+        when "retry"
+          @retry = value.to_i
+        end
+
+        nil
+      end
+
+      private
+
+      def flush_event
+        return if @data.empty?
+
+        data = @data.chomp
+        parsed = JSON.parse(data)
+
+        event = { "data" => parsed }
+        event["event"] = @event unless @event.empty?
+        event["id"] = @id if @id
+        event["retry"] = @retry if @retry
+
+        @event = ""
+        @data = ""
+        @id = nil
+        @retry = nil
+
+        event
+      end
+    end
+  end
+end

data/lib/fal/version.rb

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