fal-ai 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8c31c5366749b46a776ea9f3805c748ba27b8a1db046caa47ed16675313acc3b
+  data.tar.gz: ecbcc1de0c64dd4a9f11921b64c4a1cb8c5aa8fb30607b0990a80281976a990a
+SHA512:
+  metadata.gz: e8ae00e9d1c02a4e69ea7448bfa1ddfa47e108a918259bed282e8e1e0c61ffe57a8000a39cc06c1943d5ea3fd45226d523bac465698028848d500ee294a5d1bd
+  data.tar.gz: c74109cc7c27b43fd987f39fa57f3a25ef6767e802b5333cbcb36591f5e77285e8e0b4de8361e7b449ba5581fa0181637ccb67bf2712cd095954db15ed34f737

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.0
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/.ruby-version

@@ -0,0 +1 @@
+3.3.6

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-12-05
+
+### Added
+
+- Initial release
+- Synchronous `run` method for direct model inference
+- Queue-based `subscribe` method with polling for long-running tasks
+- Direct queue operations (`submit`, `status`, `result`)
+- Support for all fal.ai models (Flux, Stable Diffusion, etc.)
+- Configurable timeout and poll intervals
+- Comprehensive error handling with typed exceptions
+- Full test coverage

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Matt Culpepper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,133 @@
+# fal-ai
+
+[![Gem Version](https://badge.fury.io/rb/fal-ai.svg)](https://badge.fury.io/rb/fal-ai)
+
+Ruby client for [fal.ai](https://fal.ai) - the generative AI platform with 600+ models.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "fal-ai"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install fal-ai
+```
+
+## Usage
+
+### Configuration
+
+```ruby
+require "fal-ai"
+
+# Configure with API key (or set FAL_KEY environment variable)
+Fal.configure do |config|
+  config.api_key = "your-api-key"
+  config.timeout = 300          # seconds (default: 300)
+  config.poll_interval = 0.5    # seconds (default: 0.5)
+end
+```
+
+### Synchronous Run
+
+For quick operations, use `run` to execute synchronously:
+
+```ruby
+client = Fal.client
+
+result = client.run("fal-ai/flux/dev", {
+  prompt: "a beautiful sunset over mountains",
+  image_size: "landscape_16_9"
+})
+
+puts result["images"].first["url"]
+```
+
+### Subscribe (Queue with Polling)
+
+For longer operations, use `subscribe` to submit to the queue and poll until complete:
+
+```ruby
+client = Fal.client
+
+result = client.subscribe("fal-ai/flux/dev", { prompt: "a cat" }) do |status|
+  case status
+  when Fal::Status::Queued
+    puts "Queued at position #{status.position}"
+  when Fal::Status::InProgress
+    puts "Processing..."
+  end
+end
+
+puts "Completed! Image: #{result['images'].first['url']}"
+```
+
+### Direct Queue Operations
+
+For more control, use queue operations directly:
+
+```ruby
+client = Fal.client
+
+# Submit to queue
+request_id = client.queue.submit("fal-ai/flux/dev", {
+  prompt: "a dog playing fetch"
+})
+
+puts "Submitted: #{request_id}"
+
+# Poll for status
+loop do
+  status = client.queue.status("fal-ai/flux/dev", request_id)
+
+  if status.completed?
+    result = client.queue.result("fal-ai/flux/dev", request_id)
+    puts "Done! #{result['images'].first['url']}"
+    break
+  end
+
+  puts "Status: #{status.class.name}"
+  sleep 1
+end
+```
+
+### Error Handling
+
+```ruby
+begin
+  result = client.run("fal-ai/flux/dev", { prompt: "a cat" })
+rescue Fal::AuthenticationError
+  puts "Check your API key"
+rescue Fal::RateLimitError => e
+  puts "Rate limited. Status: #{e.status_code}"
+rescue Fal::ApiError => e
+  puts "API error: #{e.message}"
+rescue Fal::ConnectionError => e
+  puts "Network issue: #{e.original_error}"
+rescue Fal::TimeoutError
+  puts "Request timed out"
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/mculp/fal-ai-ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/fal/client.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Fal
+  # Main client facade providing public API.
+  #
+  # @example
+  #   client = Fal.client
+  #   result = client.run("fal-ai/flux/dev", { prompt: "a cat" })
+  class Client
+    def initialize(config:, connection: nil)
+      @config = config
+      @connection = connection || Connection.new(config: config)
+    end
+
+    def run(app_id, input)
+      endpoint = Endpoints::Run.new(app_id: app_id, base_url: @config.run_url)
+      response = @connection.post(endpoint, body: input)
+      response.data
+    end
+
+    def subscribe(app_id, input, &on_queue_update)
+      request_id = queue.submit(app_id, input)
+      subscriber.wait_for_completion(app_id, request_id, &on_queue_update)
+    end
+
+    def queue
+      @queue ||= Queue.new(connection: @connection, config: @config)
+    end
+
+    private
+
+    def subscriber
+      @subscriber ||= Subscriber.new(
+        queue: queue,
+        poll_interval: @config.poll_interval,
+        timeout: @config.timeout
+      )
+    end
+  end
+end

data/lib/fal/configuration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Fal
+  # Holds configuration for the Fal client.
+  #
+  # @example
+  #   Fal.configure do |config|
+  #     config.api_key = "your-api-key"
+  #     config.timeout = 300
+  #   end
+  class Configuration
+    attr_accessor :timeout, :poll_interval
+    attr_writer :api_key
+
+    DEFAULT_TIMEOUT = 300
+    DEFAULT_POLL_INTERVAL = 0.5
+    RUN_HOST = "fal.run"
+    QUEUE_HOST = "queue.fal.run"
+
+    def initialize
+      @api_key = ENV.fetch("FAL_KEY", nil)
+      @timeout = DEFAULT_TIMEOUT
+      @poll_interval = DEFAULT_POLL_INTERVAL
+    end
+
+    def api_key
+      @api_key or raise ConfigurationError, "API key not configured. Set FAL_KEY or call Fal.configure"
+    end
+
+    def run_url
+      "https://#{RUN_HOST}"
+    end
+
+    def queue_url
+      "https://#{QUEUE_HOST}"
+    end
+  end
+end

data/lib/fal/connection.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "http"
+
+module Fal
+  # HTTP connection wrapper using http.rb gem.
+  # Dependency-injected for testability.
+  class Connection
+    def initialize(config:, http: HTTP)
+      @config = config
+      @http = http
+      @request = Request.new(config: config)
+    end
+
+    def post(endpoint, body: nil)
+      response = perform_post(endpoint, body)
+      handle_response(response)
+    end
+
+    def get(endpoint)
+      response = perform_get(endpoint)
+      handle_response(response)
+    end
+
+    private
+
+    def perform_post(endpoint, body)
+      @http
+        .headers(@request.headers)
+        .timeout(@config.timeout)
+        .post(endpoint.url, body: body ? @request.body(body) : nil)
+    rescue HTTP::Error => e
+      raise ConnectionError.new("HTTP request failed: #{e.message}", original_error: e)
+    end
+
+    def perform_get(endpoint)
+      @http
+        .headers(@request.headers)
+        .timeout(@config.timeout)
+        .get(endpoint.url)
+    rescue HTTP::Error => e
+      raise ConnectionError.new("HTTP request failed: #{e.message}", original_error: e)
+    end
+
+    def handle_response(http_response)
+      response = Response.new(http_response)
+      return response if response.success?
+
+      raise_api_error(response)
+    end
+
+    def raise_api_error(response)
+      error_class = error_class_for(response.status_code)
+      raise error_class.new(
+        response.error_message,
+        status_code: response.status_code,
+        response_body: response.data
+      )
+    end
+
+    def error_class_for(status_code)
+      case status_code
+      when 401 then AuthenticationError
+      when 404 then NotFoundError
+      when 429 then RateLimitError
+      when 500..599 then ServerError
+      else ApiError
+      end
+    end
+  end
+end

data/lib/fal/endpoints.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Fal
+  module Endpoints
+    # Endpoint for synchronous run: POST https://fal.run/{app_id}
+    class Run
+      def initialize(app_id:, base_url:)
+        @app_id = app_id
+        @base_url = base_url
+      end
+
+      def url
+        "#{@base_url}/#{@app_id}"
+      end
+
+      def method
+        :post
+      end
+    end
+
+    # Endpoint for queue submit: POST https://queue.fal.run/{app_id}
+    class Submit
+      def initialize(app_id:, base_url:)
+        @app_id = app_id
+        @base_url = base_url
+      end
+
+      def url
+        "#{@base_url}/#{@app_id}"
+      end
+
+      def method
+        :post
+      end
+    end
+
+    # Endpoint for queue status: GET https://queue.fal.run/{app_id}/requests/{request_id}/status
+    class Status
+      def initialize(app_id:, request_id:, base_url:)
+        @app_id = app_id
+        @request_id = request_id
+        @base_url = base_url
+      end
+
+      def url
+        "#{@base_url}/#{@app_id}/requests/#{@request_id}/status"
+      end
+
+      def method
+        :get
+      end
+    end
+
+    # Endpoint for queue result: GET https://queue.fal.run/{app_id}/requests/{request_id}
+    class Result
+      def initialize(app_id:, request_id:, base_url:)
+        @app_id = app_id
+        @request_id = request_id
+        @base_url = base_url
+      end
+
+      def url
+        "#{@base_url}/#{@app_id}/requests/#{@request_id}"
+      end
+
+      def method
+        :get
+      end
+    end
+  end
+end

data/lib/fal/errors.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Fal
+  # Base error for all Fal errors
+  class Error < StandardError; end
+
+  # Raised when configuration is invalid or missing
+  class ConfigurationError < Error; end
+
+  # Raised when HTTP connection fails
+  class ConnectionError < Error
+    attr_reader :original_error
+
+    def initialize(message, original_error: nil)
+      super(message)
+      @original_error = original_error
+    end
+  end
+
+  # Base class for API errors (non-2xx responses)
+  class ApiError < Error
+    attr_reader :status_code, :response_body
+
+    def initialize(message, status_code:, response_body: nil)
+      super(message)
+      @status_code = status_code
+      @response_body = response_body
+    end
+  end
+
+  # 401 Unauthorized
+  class AuthenticationError < ApiError; end
+
+  # 404 Not Found
+  class NotFoundError < ApiError; end
+
+  # 429 Too Many Requests
+  class RateLimitError < ApiError; end
+
+  # 5xx Server Errors
+  class ServerError < ApiError; end
+
+  # Raised when polling times out
+  class TimeoutError < Error; end
+end

data/lib/fal/queue.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Fal
+  # Queue operations: submit, status, result.
+  class Queue
+    def initialize(connection:, config:)
+      @connection = connection
+      @config = config
+    end
+
+    def submit(app_id, input)
+      endpoint = Endpoints::Submit.new(app_id: app_id, base_url: @config.queue_url)
+      response = @connection.post(endpoint, body: input)
+      response.request_id
+    end
+
+    def status(app_id, request_id)
+      endpoint = Endpoints::Status.new(
+        app_id: app_id,
+        request_id: request_id,
+        base_url: @config.queue_url
+      )
+      response = @connection.get(endpoint)
+      response.to_status
+    end
+
+    def result(app_id, request_id)
+      endpoint = Endpoints::Result.new(
+        app_id: app_id,
+        request_id: request_id,
+        base_url: @config.queue_url
+      )
+      response = @connection.get(endpoint)
+      response.data
+    end
+  end
+end

data/lib/fal/request.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Fal
+  # Builds HTTP request components (headers, body).
+  class Request
+    CONTENT_TYPE = "application/json"
+    USER_AGENT = "fal-ruby/#{VERSION}"
+
+    def initialize(config:)
+      @config = config
+    end
+
+    def headers
+      {
+        "Authorization" => "Key #{@config.api_key}",
+        "Content-Type" => CONTENT_TYPE,
+        "User-Agent" => USER_AGENT
+      }
+    end
+
+    def body(input)
+      JSON.generate(input)
+    end
+  end
+end

data/lib/fal/response.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Fal
+  # Parses HTTP responses and creates appropriate objects.
+  class Response
+    def initialize(http_response)
+      @http_response = http_response
+    end
+
+    def status_code
+      @http_response.status.to_i
+    end
+
+    def success?
+      status_code >= 200 && status_code < 300
+    end
+
+    def data
+      @data ||= parse_body
+    end
+
+    def request_id
+      data["request_id"]
+    end
+
+    def error_message
+      data["detail"] || data["message"] || "Unknown error"
+    end
+
+    def to_status
+      status_class.new(data)
+    end
+
+    private
+
+    def parse_body
+      JSON.parse(@http_response.body.to_s)
+    rescue JSON::ParserError
+      { "raw" => @http_response.body.to_s }
+    end
+
+    def status_class
+      case data["status"]
+      when "IN_QUEUE" then Status::Queued
+      when "IN_PROGRESS" then Status::InProgress
+      when "COMPLETED" then Status::Completed
+      else Status::Base
+      end
+    end
+  end
+end

data/lib/fal/status.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Fal
+  module Status
+    # Base class for all status types
+    class Base
+      attr_reader :raw_data
+
+      def initialize(raw_data)
+        @raw_data = raw_data
+      end
+
+      def queued?
+        false
+      end
+
+      def in_progress?
+        false
+      end
+
+      def completed?
+        false
+      end
+    end
+
+    # Request is queued, waiting to be processed
+    class Queued < Base
+      def position
+        raw_data["queue_position"] || raw_data["position"]
+      end
+
+      def queued?
+        true
+      end
+    end
+
+    # Request is currently being processed
+    class InProgress < Base
+      def logs
+        raw_data["logs"] || []
+      end
+
+      def in_progress?
+        true
+      end
+    end
+
+    # Request has completed successfully
+    class Completed < Base
+      def logs
+        raw_data["logs"] || []
+      end
+
+      def metrics
+        raw_data["metrics"] || {}
+      end
+
+      def completed?
+        true
+      end
+    end
+  end
+end

data/lib/fal/subscriber.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Fal
+  # Polls queue until completion, yielding status updates.
+  class Subscriber
+    def initialize(queue:, poll_interval:, timeout:)
+      @queue = queue
+      @poll_interval = poll_interval
+      @timeout = timeout
+    end
+
+    def wait_for_completion(app_id, request_id, &on_update)
+      deadline = Time.now + @timeout
+
+      loop do
+        check_timeout(deadline)
+        status = @queue.status(app_id, request_id)
+        yield_status(status, &on_update)
+        return fetch_result(app_id, request_id) if status.completed?
+
+        sleep(@poll_interval)
+      end
+    end
+
+    private
+
+    def check_timeout(deadline)
+      return if Time.now < deadline
+
+      raise TimeoutError, "Polling timed out after #{@timeout} seconds"
+    end
+
+    def yield_status(status, &on_update)
+      on_update&.call(status)
+    end
+
+    def fetch_result(app_id, request_id)
+      @queue.result(app_id, request_id)
+    end
+  end
+end

data/lib/fal/version.rb

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

data/lib/fal-ai.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Entry point for `require "fal-ai"`
+# Delegates to the main Fal module
+require_relative "fal"

data/lib/fal.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "fal/version"
+require_relative "fal/errors"
+require_relative "fal/configuration"
+require_relative "fal/endpoints"
+require_relative "fal/status"
+require_relative "fal/request"
+require_relative "fal/response"
+require_relative "fal/connection"
+require_relative "fal/queue"
+require_relative "fal/subscriber"
+require_relative "fal/client"
+
+# Ruby client for fal.ai Model APIs
+#
+# @example
+#   Fal.configure do |config|
+#     config.api_key = "your-api-key"
+#   end
+#
+#   client = Fal.client
+#   result = client.run("fal-ai/flux/dev", { prompt: "a cat" })
+module Fal
+  class << self
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def client(config: configuration)
+      Client.new(config: config)
+    end
+
+    def reset_configuration!
+      @configuration = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: fal-ai
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matt Culpepper
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: A Ruby client library for fal.ai's generative AI platform. Run inference
+  on 600+ AI models including Flux, Stable Diffusion, and more with synchronous and
+  queue-based APIs.
+email:
+- matt@culpepper.co
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/fal-ai.rb
+- lib/fal.rb
+- lib/fal/client.rb
+- lib/fal/configuration.rb
+- lib/fal/connection.rb
+- lib/fal/endpoints.rb
+- lib/fal/errors.rb
+- lib/fal/queue.rb
+- lib/fal/request.rb
+- lib/fal/response.rb
+- lib/fal/status.rb
+- lib/fal/subscriber.rb
+- lib/fal/version.rb
+homepage: https://github.com/mculp/fal-ai-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://fal.ai
+  source_code_uri: https://github.com/mculp/fal-ai-ruby
+  changelog_uri: https://github.com/mculp/fal-ai-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/fal-ai
+  bug_tracker_uri: https://github.com/mculp/fal-ai-ruby/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.0
+specification_version: 4
+summary: Ruby client for fal.ai generative AI platform
+test_files: []