fal 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 294f1aa2fea312c2b0a42b2fe97753e45a8d8807083d5a60a3c739b7bdd722f6
-  data.tar.gz: 93fb4193c178ffd22bfddeffab3926a4288afd89e42f9bd418d9a71ce45c2645
+  metadata.gz: 4ff4bd4724ee6b7ea39f7c72f51503e4e918b50f019972a08836efd6d22fdffc
+  data.tar.gz: 4f9020293f0b639487e836668116fadfcd51768ef0401e335a18394be155c930
 SHA512:
-  metadata.gz: 3d328838cdf0dc3eff20b2275ecff9528d90bf8d549272b663f0b985b7fd2d3744e4a60e5b621a96a7a3f9a549b506e28f83776c5c84514d9d541fc376ed27d0
-  data.tar.gz: 112f8673d40fd9195c1b157656e2f1c9dc8208e14c460207672cefd8e2264fac2f9857df17a11d2d174f9617c7771700f71e71ed797d6f1c820fcd9613cd472d
+  metadata.gz: d7646551a9cffa3a58b9ce0ac08f48e258cedd9e19f7ad18e9ae8fc3fe0aa85c774e5a21a283026ef5a22e0126c8c3db52d2667bc7cca285f8d9b6d74c4ac3b7
+  data.tar.gz: 0f1f6137e731796d859ff4bd51eb92078453530498dfd72d436e8c9999dd4f1f26087a99c010f533fb231bb2012186d10fee972811ff44d268e77a71d1180e3a

data/.env.example

@@ -0,0 +1 @@
+FAL_KEY=

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

@@ -7,3 +7,8 @@ gemspec
 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,62 +1,126 @@
 PATH
   remote: .
   specs:
-    fal (0.0.1)
+    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
   fal!
   minitest (~> 5.0)
   rake (~> 13.0)
   rubocop (~> 1.21)
+  sorbet
+  tapioca
+  vcr
+  webmock
 
 BUNDLED WITH
    2.5.7

data/README.md

@@ -9,3 +9,275 @@ Install the gem and add to the application"s Gemfile by executing:
 If bundler is not being used to manage dependencies, install the gem by executing:
 
     $ gem install fal
+
+## Usage
+
+### Configuration
+
+Configure the client once at boot (e.g., in Rails an initializer) using `Fal.configure`.
+
+```ruby
+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 `endpoint_id` in "namespace/name" format and an input payload.
+
+```ruby
+endpoint_id = "fal-ai/fast-sdxl"
+
+request = Fal::Request.create!(
+  endpoint_id: endpoint_id,
+  input: { prompt: "a cat" }
+)
+
+request.id       # => request_id from fal
+request.status   # => "IN_QUEUE" | "IN_PROGRESS" | "COMPLETED"
+```
+
+You can also specify a webhook URL to be notified when the request is finished.
+
+```ruby
+request = Fal::Request.create!(
+  endpoint_id: endpoint_id,
+  input: { prompt: "a cat playing piano" },
+  webhook_url: "https://example.com/fal/webhook"
+)
+```
+
+### Get request status (find and reload)
+
+Fetch the current status by id:
+
+```ruby
+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
+```
+
+Reload an instance in-place, optionally including logs.
+
+```ruby
+request.reload!           # refreshes state
+request.reload!(logs: true)
+request.logs              # => array of log entries (if provided by model and logs=1)
+# When status is COMPLETED, reload! will also fetch and set request.response
+```
+
+Status constants are available for direct comparisons:
+
+```ruby
+Fal::Request::Status::IN_QUEUE
+Fal::Request::Status::IN_PROGRESS
+Fal::Request::Status::COMPLETED
+```
+
+### Fetch the response payload after completion
+
+Call `reload!` to populate `request.response`:
+
+```ruby
+# poll until completed
+until request.completed?
+  request.reload!
+  sleep 1
+end
+
+request.response   # => model-specific response body
+```
+
+### Cancel a request
+
+Requests that are still in the queue can be cancelled:
+
+```ruby
+request.cancel! # => { "status" => "CANCELLATION_REQUESTED" }
+```
+
+### Webhooks
+
+fal can POST a webhook to your server when a request completes. Use `Fal::WebhookRequest` to parse the incoming payload.
+
+```ruby
+# rails controller example
+class FalWebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def create
+    webhook = Fal::WebhookRequest.from_rack_request(request)
+
+    if webhook.success?
+      # webhook.response contains the model-specific payload
+      # webhook.logs, webhook.metrics may also be present
+      head :ok
+    else
+      Rails.logger.error("fal webhook error: #{webhook.error} detail=#{webhook.error_detail}")
+      head :ok
+    end
+  end
+end
+```
+
+### Error handling
+
+HTTP and API errors raise typed exceptions:
+
+- `Fal::UnauthorizedError` (401)
+- `Fal::ForbiddenError` (403)
+- `Fal::NotFoundError` (404)
+- `Fal::ServerError` (other non-success)
+
+Rescue them as needed:
+
+```ruby
+begin
+  Fal::Request.create!(endpoint_id: endpoint_id, input: { prompt: "hi" })
+rescue Fal::UnauthorizedError
+  # handle invalid/missing FAL_KEY
+end
+```
+
+### Stream synchronous responses
+
+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
+endpoint_id = "fal-ai/flux/dev"
+
+last = Fal::Request.stream!(endpoint_id: endpoint_id, input: { prompt: "a cat" }) do |chunk|
+  # chunk is a Hash, e.g. { images: [...] }
+  puts chunk
+end
+
+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.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to rubygems.org.
+
+For local development, copy the example environment file and set your API key so `bin/console` can load it automatically:
+
+```
+cp .env.example .env
+echo 'FAL_KEY=your_api_key_here' >> .env
+```
+
+The console uses dotenv to load `.env`, so `Fal.configure` will default to `ENV["FAL_KEY"]`.

data/lib/fal/client.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Fal
+  class Client
+    attr_accessor :configuration
+
+    def initialize(configuration = Fal.configuration)
+      @configuration = configuration
+    end
+
+    def post(path, payload = {}, headers: {})
+      response = connection.post(build_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 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]
+    # @param payload [Hash]
+    # @param on_data [Proc] called with chunks as they arrive
+    # @return [void]
+    def post_stream(path, payload = {}, on_data:)
+      url = build_sync_url(path)
+      connection.post(url) do |request|
+        request.headers["Authorization"] = "Key #{@configuration.api_key}" if @configuration.api_key
+        request.headers["Accept"] = "text/event-stream"
+        request.headers["Cache-Control"] = "no-store"
+        request.headers["Content-Type"] = "application/json"
+        request.body = payload.compact.to_json
+        request.options.on_data = on_data
+      end
+    end
+
+    def get(path, query: nil, headers: {})
+      url = build_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
+
+    # 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
+        request.headers["Content-Type"] = "application/json"
+        request.headers["Accept"] = "application/json"
+        request.body = {}.to_json
+      end
+
+      handle_error(response) unless response.success?
+
+      parse_json(response.body)
+    end
+
+    def handle_error(response)
+      case response.status
+      when 401
+        raise UnauthorizedError, response.body
+      when 403
+        raise ForbiddenError, response.body
+      when 404
+        raise NotFoundError, response.body
+      else
+        raise ServerError, response.body
+      end
+    end
+
+    private
+
+    def parse_json(body)
+      return nil if body.nil? || body.strip.empty?
+
+      JSON.parse(body)
+    end
+
+    def build_url(path)
+      "#{@configuration.queue_base}#{path}"
+    end
+
+    def build_sync_url(path)
+      "#{@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
+        faraday.options.timeout = @configuration.request_timeout
+        faraday.options.open_timeout = @configuration.request_timeout
+      end
+    end
+  end
+end