fal 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f22dff48b2f5121df441220f3fffe41f3e548c8a2c229dd0f1c7d3c19072b74f
-  data.tar.gz: 8e5c092fb5246f8ea7ee88b80123e63d5ed7384f37b1cfc61474bcd3daef1431
+  metadata.gz: 4ff4bd4724ee6b7ea39f7c72f51503e4e918b50f019972a08836efd6d22fdffc
+  data.tar.gz: 4f9020293f0b639487e836668116fadfcd51768ef0401e335a18394be155c930
 SHA512:
-  metadata.gz: '05697e66efb4f7d26fb110d707627755395244fa5a9fca86d3624e4bd6d33cae7a42ccbe625cd14dd8646b4a934496e2f169247a387ad046cf049ece487eb0d4'
-  data.tar.gz: b7bd9bf3bddb0f1a62ed61bb9d681a5531f4e00ff628cbc4a77b720e4367ef9a6d7a45253bb4777654e078c1e55e67ab6aaa95cebb2bf83ebc0e4a28df5b49c0
+  metadata.gz: d7646551a9cffa3a58b9ce0ac08f48e258cedd9e19f7ad18e9ae8fc3fe0aa85c774e5a21a283026ef5a22e0126c8c3db52d2667bc7cca285f8d9b6d74c4ac3b7
+  data.tar.gz: 0f1f6137e731796d859ff4bd51eb92078453530498dfd72d436e8c9999dd4f1f26087a99c010f533fb231bb2012186d10fee972811ff44d268e77a71d1180e3a

data/.rubocop.yml

@@ -40,3 +40,11 @@ Style/HashSyntax:
 Naming/FileName:
   Exclude:
     - "lib/fal.rb"
+
+Style/RedundantInitialize:
+  Exclude:
+    - "rbi/**/*.rbi"
+
+Naming/BlockForwarding:
+  Exclude:
+    - "rbi/**/*.rbi"

data/Gemfile

@@ -8,3 +8,7 @@ gem "minitest", "~> 5.0"
 gem "rake", "~> 13.0"
 gem "rubocop", "~> 1.21"
 gem "dotenv"
+gem "sorbet"
+gem "tapioca"
+gem "vcr"
+gem "webmock"

data/Gemfile.lock

@@ -1,57 +1,115 @@
 PATH
   remote: .
   specs:
-    fal (0.0.3)
+    fal (0.1.0)
       faraday (>= 1)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.2)
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    benchmark (0.5.0)
+    bigdecimal (3.3.1)
+    crack (1.0.1)
+      bigdecimal
+      rexml
     dotenv (3.1.8)
+    erubi (1.13.1)
     faraday (2.14.0)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
     faraday-net_http (3.4.1)
       net-http (>= 0.5.0)
-    json (2.7.2)
-    language_server-protocol (3.17.0.3)
+    hashdiff (1.2.1)
+    json (2.15.2)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
     logger (1.7.0)
-    minitest (5.23.1)
-    net-http (0.6.0)
+    minitest (5.26.0)
+    net-http (0.7.0)
       uri
-    parallel (1.24.0)
-    parser (3.3.1.0)
+    netrc (0.11.0)
+    parallel (1.27.0)
+    parser (3.3.10.0)
       ast (~> 2.4.1)
       racc
-    racc (1.8.0)
+    prism (1.6.0)
+    public_suffix (6.0.2)
+    racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.2.1)
-    regexp_parser (2.9.2)
-    rexml (3.2.8)
-      strscan (>= 3.0.9)
-    rubocop (1.64.0)
+    rake (13.3.1)
+    rbi (0.3.7)
+      prism (~> 1.0)
+      rbs (>= 3.4.4)
+    rbs (3.9.5)
+      logger
+    regexp_parser (2.11.3)
+    rexml (3.4.4)
+    rubocop (1.81.7)
       json (~> 2.3)
-      language_server-protocol (>= 3.17.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
       parallel (~> 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.31.1, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.31.3)
-      parser (>= 3.3.1.0)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.47.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
     ruby-progressbar (1.13.0)
-    strscan (3.1.0)
-    unicode-display_width (2.5.0)
-    uri (1.0.3)
+    sorbet (0.6.12689)
+      sorbet-static (= 0.6.12689)
+    sorbet-runtime (0.6.12689)
+    sorbet-static (0.6.12689-aarch64-linux)
+    sorbet-static (0.6.12689-universal-darwin)
+    sorbet-static (0.6.12689-x86_64-linux)
+    sorbet-static-and-runtime (0.6.12689)
+      sorbet (= 0.6.12689)
+      sorbet-runtime (= 0.6.12689)
+    spoom (1.6.3)
+      erubi (>= 1.10.0)
+      prism (>= 0.28.0)
+      rbi (>= 0.3.3)
+      rexml (>= 3.2.6)
+      sorbet-static-and-runtime (>= 0.5.10187)
+      thor (>= 0.19.2)
+    tapioca (0.16.11)
+      benchmark
+      bundler (>= 2.2.25)
+      netrc (>= 0.11.0)
+      parallel (>= 1.21.0)
+      rbi (~> 0.2)
+      sorbet-static-and-runtime (>= 0.5.11087)
+      spoom (>= 1.2.0)
+      thor (>= 1.2.0)
+      yard-sorbet
+    thor (1.4.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.1.0)
+    uri (1.1.0)
+    vcr (6.3.1)
+      base64
+    webmock (3.26.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+    yard (0.9.37)
+    yard-sorbet (0.9.0)
+      sorbet-runtime
+      yard
 
 PLATFORMS
-  ruby
-  x86_64-darwin-23
+  aarch64-linux
+  universal-darwin
+  x86_64-linux
 
 DEPENDENCIES
   dotenv
@@ -59,6 +117,10 @@ DEPENDENCIES
   minitest (~> 5.0)
   rake (~> 13.0)
   rubocop (~> 1.21)
+  sorbet
+  tapioca
+  vcr
+  webmock
 
 BUNDLED WITH
    2.5.7

data/README.md

@@ -21,19 +21,20 @@ Fal.configure do |config|
   config.api_key = "your-key" # Optional. Defaults to ENV["FAL_KEY"] if not set.
   config.queue_base = "https://queue.fal.run" # Optional (default: https://queue.fal.run)
   config.sync_base = "https://fal.run" # Optional (default: https://fal.run)
+  config.api_base = "https://api.fal.ai/v1" # Optional (default: https://api.fal.ai/v1)
   config.request_timeout = 120 # Optional (default: 120)
 end
 ```
 
 ### Create a queued request
 
-The Queue API is the recommended way to call models on fal. Provide a `model_id` in "namespace/name" format and an input payload.
+The Queue API is the recommended way to call models on fal. Provide a `endpoint_id` in "namespace/name" format and an input payload.
 
 ```ruby
-model_id = "fal-ai/fast-sdxl"
+endpoint_id = "fal-ai/fast-sdxl"
 
 request = Fal::Request.create!(
-  model_id: model_id,
+  endpoint_id: endpoint_id,
   input: { prompt: "a cat" }
 )
 
@@ -45,7 +46,7 @@ You can also specify a webhook URL to be notified when the request is finished.
 
 ```ruby
 request = Fal::Request.create!(
-  model_id: model_id,
+  endpoint_id: endpoint_id,
   input: { prompt: "a cat playing piano" },
   webhook_url: "https://example.com/fal/webhook"
 )
@@ -56,7 +57,7 @@ request = Fal::Request.create!(
 Fetch the current status by id:
 
 ```ruby
-status = Fal::Request.find_by!(id: request.id, model_id: model_id)
+status = Fal::Request.find_by!(id: request.id, endpoint_id: endpoint_id)
 status.in_queue?      # => true/false
 status.in_progress?   # => true/false
 status.completed?     # => true/false
@@ -138,7 +139,7 @@ Rescue them as needed:
 
 ```ruby
 begin
-  Fal::Request.create!(model_id: model_id, input: { prompt: "hi" })
+  Fal::Request.create!(endpoint_id: endpoint_id, input: { prompt: "hi" })
 rescue Fal::UnauthorizedError
   # handle invalid/missing FAL_KEY
 end
@@ -149,9 +150,9 @@ end
 Use `stream!` for SSE streaming from synchronous endpoints. It yields each chunk’s data Hash and returns a `Fal::Request` whose `response` contains the last chunk’s payload.
 
 ```ruby
-model_id = "fal-ai/flux/dev"
+endpoint_id = "fal-ai/flux/dev"
 
-last = Fal::Request.stream!(model_id: model_id, input: { prompt: "a cat" }) do |chunk|
+last = Fal::Request.stream!(endpoint_id: endpoint_id, input: { prompt: "a cat" }) do |chunk|
   # chunk is a Hash, e.g. { images: [...] }
   puts chunk
 end
@@ -160,6 +161,112 @@ last.completed?    # => true/false
 last.response      # => last streamed data hash (e.g., { "response" => { ... } } or final payload)
 ```
 
+### Pricing
+
+Use the Platform API to fetch per-endpoint pricing.
+
+Find pricing for a single endpoint:
+
+```ruby
+price = Fal::Price.find_by(endpoint_id: "fal-ai/flux/dev")
+price.unit_price  # => e.g., 0.025
+price.unit        # => e.g., "image"
+price.currency    # => e.g., "USD"
+```
+
+Iterate through all prices (auto-paginates):
+
+```ruby
+Fal::Price.each do |p|
+  puts "#{p.endpoint_id} => #{p.unit_price} #{p.currency} per #{p.unit}"
+end
+```
+
+Collect all prices as an array:
+
+```ruby
+prices = Fal::Price.all
+```
+
+### Estimate cost
+
+Compute a total cost estimate across endpoints using historical API price or unit price.
+
+Unit price (uses billing units like images/videos):
+
+```ruby
+estimate = Fal::PriceEstimate.create(
+  estimate_type: Fal::PriceEstimate::EstimateType::UNIT_PRICE,
+  endpoints: [
+    # You can pass unit_quantity directly
+    Fal::PriceEstimate::Endpoint.new(endpoint_id: "fal-ai/flux/dev", unit_quantity: 50),
+    # Or use call_quantity as a convenience alias for units
+    Fal::PriceEstimate::Endpoint.new(endpoint_id: "fal-ai/flux-pro", call_quantity: 25)
+  ]
+)
+
+estimate.estimate_type  # => "unit_price"
+estimate.total_cost     # => e.g., 1.88
+estimate.currency       # => "USD"
+```
+
+Historical API price (uses calls per endpoint):
+
+```ruby
+estimate = Fal::PriceEstimate.create(
+  estimate_type: Fal::PriceEstimate::EstimateType::HISTORICAL_API_PRICE,
+  endpoints: [
+    Fal::PriceEstimate::Endpoint.new(endpoint_id: "fal-ai/flux/dev", call_quantity: 100)
+  ]
+)
+```
+
+### Models
+
+List, search, and find models via the Models API.
+
+Find a model by endpoint ID:
+
+```ruby
+model = Fal::Model.find_by(endpoint_id: "fal-ai/flux/dev")
+model.endpoint_id   # => "fal-ai/flux/dev"
+model.display_name  # => e.g., "FLUX.1 [dev]"
+model.category      # => e.g., "text-to-image"
+model.status        # => "active" | "deprecated"
+model.tags          # => ["fast", "pro"]
+model.model_url     # => "https://fal.run/..."
+model.thumbnail_url # => "https://..."
+```
+
+Iterate or collect all models (auto-paginates):
+
+```ruby
+Fal::Model.each do |m|
+  puts m.endpoint_id
+end
+
+all_models = Fal::Model.all
+```
+
+Search with filters:
+
+```ruby
+results = Fal::Model.search(query: "text to image", status: "active")
+```
+
+Get a model’s price (memoized):
+
+```ruby
+price = model.price
+price.unit_price  # => e.g., 0.025
+```
+
+Run a request for a model (uses the model's `endpoint_id` as `endpoint_id`):
+
+```ruby
+request = model.run(input: { prompt: "a cat" })
+```
+
 ### Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/fal/client.rb

@@ -22,6 +22,25 @@ module Fal
       parse_json(response.body)
     end
 
+    # Perform a POST against the platform API base (api.fal.ai/v1)
+    # @param path [String]
+    # @param payload [Hash]
+    # @param headers [Hash]
+    # @return [Hash, nil]
+    def post_api(path, payload = {}, headers: {})
+      response = connection.post(build_api_url(path)) do |request|
+        request.headers["Authorization"] = "Key #{@configuration.api_key}" if @configuration.api_key
+        request.headers["Content-Type"] = "application/json"
+        request.headers["Accept"] = "application/json"
+        request.headers.merge!(headers)
+        request.body = payload.compact.to_json
+      end
+
+      handle_error(response) unless response.success?
+
+      parse_json(response.body)
+    end
+
     # Perform a POST to the streaming (sync) base with SSE/text-event-stream handling.
     # The provided on_data Proc will be used to receive chunked data.
     # @param path [String]
@@ -55,6 +74,26 @@ module Fal
       parse_json(response.body)
     end
 
+    # Perform a GET against the platform API base (api.fal.ai/v1)
+    # @param path [String]
+    # @param query [Hash, nil]
+    # @param headers [Hash]
+    # @return [Hash, nil]
+    def get_api(path, query: nil, headers: {})
+      url = build_api_url(path)
+      url = "#{url}?#{URI.encode_www_form(query)}" if query && !query.empty?
+
+      response = connection.get(url) do |request|
+        request.headers["Authorization"] = "Key #{@configuration.api_key}" if @configuration.api_key
+        request.headers["Accept"] = "application/json"
+        request.headers.merge!(headers)
+      end
+
+      handle_error(response) unless response.success?
+
+      parse_json(response.body)
+    end
+
     def put(path)
       response = connection.put(build_url(path)) do |request|
         request.headers["Authorization"] = "Key #{@configuration.api_key}" if @configuration.api_key
@@ -97,6 +136,10 @@ module Fal
       "#{@configuration.sync_base}#{path}"
     end
 
+    def build_api_url(path)
+      "#{@configuration.api_base}#{path}"
+    end
+
     def connection
       Faraday.new do |faraday|
         faraday.request :url_encoded

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