AIFaker 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7bde2c3f571fa5b745523114e1313f79ea768b1c48408918cbe9a1f2975e9c2a
-  data.tar.gz: 1fe46a60220f6fb95ef4308db036b317a8e17ac7508c4af8b72db0f480ee9b2c
+  metadata.gz: ddbf0a8c9db82f66bf23693b731ccebf9998277c13f290257d50ce6b67042fa9
+  data.tar.gz: fd3219303d5164f2df18255fbd8bb6c3820cbaf17c48c5a94bd8361ab8e78dcb
 SHA512:
-  metadata.gz: bf33a25da19a490ef4337bb59794c59919b380ccf76138617c42015de4f0243b56cf0d54fd6958c21db02721930674f0f7575e20d2b38e4a7d9032a9e9a88e78
-  data.tar.gz: 54ad8a9d77abd245309fd8c0fa0f1b8791b2e46b28ff2a8c4913a0fc4959a675aac2d277d5b4645069641f84804a6ad7e55fa2bdbd1b56bcf2eea754d15eee7a
+  metadata.gz: cca0aaba360d89afd686dfc4b46e08ad32aa8c737ab14589ee585c7b8813dff0bac9755625baea8b1628bda2e5cbb341f479ae40cc04c34914ff99d2a4d59c84
+  data.tar.gz: a2ef54fd5527801185e47f265d0ba75f2035ebbeeb13fe1a8ebe1a4ba02defa97d8c3334345d4e4b0cd302cf0da8097c15b93a252ad2f8a11327a23de9994572

data/lib/AIFaker/client.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "stringio"
+require "securerandom"
+
+require_relative "errors"
+require_relative "ui"
+require_relative "schema_introspector"
+require_relative "model_introspector"
+require_relative "seed_planner"
+require_relative "seed_runner"
+require_relative "llm_adapters/ruby_llm"
+
+module AIFaker
+  class Client
+    def self.connect(provider = nil, **options)
+      provider = normalize_provider(provider || ENV["AIFAKER_PROVIDER"] || "openai")
+
+      ui = options.delete(:ui) || UI.new
+
+      unless LLMAdapters::RubyLLM.available?
+        raise ConnectionError, 'Missing dependency: add `gem "ruby_llm"` to your Gemfile.'
+      end
+
+      adapter = LLMAdapters::RubyLLM.new(provider:, ui:, **options)
+
+      new(adapter:, ui:)
+    end
+
+    def self.normalize_provider(raw)
+      value = raw.to_s.strip.downcase
+      value = "anthropic" if value == "claude"
+      value
+    end
+
+    def initialize(adapter:, ui: UI.new)
+      @adapter = adapter
+      @ui = ui
+      @schema = nil
+      @models = nil
+      @associations = nil
+      @plan = nil
+      @automode = false
+    end
+
+    attr_reader :automode
+
+    def automode=(value)
+      @automode = !!value
+    end
+
+    # Enables/disables non-interactive mode.
+    # When enabled, AIFaker assumes "yes" for all prompts and picks a random count 10..20.
+    def automode!(value = true)
+      self.automode = value
+      self
+    end
+
+    def connected?
+      @adapter.connected?
+    end
+
+    def connect!
+      @adapter.connect!
+      @ui.banner("AIFaker successfully connected")
+      self
+    end
+
+    def read_schema
+      @schema = SchemaIntrospector.dump_schema
+      @adapter.share_schema!(@schema)
+      @ui.section("Schema shared")
+      @schema
+    end
+    alias_method :read_db_schema, :read_schema
+
+    def read_model_associations
+      data = ModelIntrospector.describe_models_and_associations
+      @models = data.fetch(:models)
+      @associations = data.fetch(:associations)
+      @adapter.share_models!(@models, @associations)
+      @ui.section("Model associations shared")
+      data
+    end
+    alias_method :read_associations, :read_model_associations
+
+    def plan_seed
+      ensure_schema_and_models!
+      @plan = SeedPlanner.new(models: @models, associations: @associations).plan
+      @adapter.share_seed_plan!(@plan)
+      @plan
+    end
+    alias_method :seed_plan, :plan_seed
+
+    def seed!
+      connect! unless connected?
+      read_schema if @schema.nil?
+      read_model_associations if @models.nil?
+      plan_seed if @plan.nil?
+
+      proceed =
+        if automode
+          true
+        else
+          @ui.ask_yes_no("Do you want to proceed with creation of dummy realistic data?")
+        end
+      return :skipped unless proceed
+
+      count =
+        if automode
+          rand(10..20)
+        else
+          @ui.ask_integer("How much count you needed approx for creation dummy data in each tables?", min: 5, max: 50)
+        end
+
+      SeedRunner.new(
+        ui: @ui,
+        adapter: @adapter,
+        plan: @plan,
+        default_count: count
+      ).run(assume_yes: automode)
+    end
+    alias_method :run!, :seed!
+
+    private
+
+    def ensure_schema_and_models!
+      read_schema if @schema.nil?
+      read_model_associations if @models.nil?
+    end
+  end
+end
+

data/lib/AIFaker/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module AIFaker
+  class Error < StandardError; end
+  class ConnectionError < Error; end
+  class MissingRailsError < Error; end
+  class UnsupportedProviderError < Error; end
+end
+

data/lib/AIFaker/llm_adapters/ruby_llm.rb

@@ -0,0 +1,482 @@
+# frozen_string_literal: true
+
+module AIFaker
+  module LLMAdapters
+    class RubyLLM
+      def self.available?
+        require "ruby_llm"
+        true
+      rescue LoadError
+        false
+      end
+
+      def initialize(provider:, ui: nil, **options)
+        @provider = provider
+        @ui = ui
+        @options = options
+        @connected = false
+        @schema = nil
+        @models = nil
+        @associations = nil
+        @plan = nil
+        @generated_uniques = Hash.new { |h, k| h[k] = Hash.new { |hh, kk| hh[kk] = [] } }
+        @failure_feedback = {}
+      end
+
+      def connected?
+        @connected
+      end
+
+      def connect!
+        self.class.available? or raise ConnectionError, "Missing dependency: add `gem \"ruby_llm\"` to your Gemfile."
+
+        @provider_sym = @provider.to_sym
+        configure_ruby_llm!
+        @connected = true
+      rescue StandardError => e
+        raise ConnectionError, "Failed to connect via ruby_llm (provider=#{@provider}): #{e.class}: #{e.message}"
+      end
+
+      def share_schema!(schema)
+        @schema = schema
+      end
+
+      def share_models!(models, associations)
+        @models = models
+        @associations = associations
+      end
+
+      def share_seed_plan!(plan)
+        @plan = plan
+      end
+
+      def generate_attributes(model)
+        prompt = build_prompt_for(model)
+        response_text = chat_with_indicator(prompt, label: "Searching #{model.name}")
+        parsed = parse_json_hash(response_text)
+        attrs = coerce_attributes(model, parsed)
+        remember_generated_unique_values(model, attrs)
+        attrs
+      rescue StandardError => e
+        raise Error, "LLM attribute generation failed for #{model.name}: #{e.class}: #{e.message}"
+      end
+
+      def suggest_fix(model, error:, last_attributes:)
+        prompt = build_fix_prompt_for(model, error:, last_attributes:)
+        chat_with_indicator(prompt, label: "Searching fix for #{model.name}")
+      rescue StandardError
+        nil
+      end
+
+      def register_failure(model, error:, attempted_attributes:)
+        taken_by_column = uniqueness_taken_values(model, error, attempted_attributes)
+        @failure_feedback[model.name] = {
+          message: "#{error.class}: #{error.message}",
+          details: validation_error_details(error),
+          attempted_attributes: attempted_attributes,
+          dont_suggest: taken_by_column
+        }
+      rescue StandardError
+        nil
+      end
+
+      def apply_fix!(_fix)
+        # The fix is typically guidance; in v0 we just retry with fresh attributes.
+      end
+
+      private
+
+      def build_prompt_for(model)
+        {
+          role: "system",
+          content: <<~TEXT
+            You are generating realistic seed data for a Rails app.
+
+            Return ONLY a JSON object of attributes for the ActiveRecord model "#{model.name}".
+            Rules:
+            - Do NOT include id, created_at, updated_at
+            - For belongs_to associations, include the foreign key field (e.g. user_id) as an integer id that exists.
+            - Use the schema + model context provided below.
+
+            SCHEMA:
+            #{@schema}
+
+            MODELS:
+            #{@models}
+
+            ASSOCIATIONS:
+            #{@associations}
+
+            SEED PLAN:
+            #{@plan}
+
+            UNIQUENESS CONSTRAINTS FOR #{model.name}:
+            #{uniqueness_constraints_text(model)}
+
+            VALIDATIONS FOR #{model.name}:
+            #{model_validations_text(model)}
+
+            LAST FAILURE FOR #{model.name} (if any):
+            #{failure_feedback_text(model)}
+
+            DO NOT SUGGEST THESE VALUES FOR #{model.name}:
+            #{dont_suggest_text(model)}
+
+            Important:
+            - If a previous attempt failed due to uniqueness, generate NEW values for those fields.
+            - Never reuse exact values shown in attempted_attributes/recent_generated/existing_sample/dont_suggest for unique columns.
+          TEXT
+        }
+      end
+
+      def build_fix_prompt_for(model, error:, last_attributes:)
+        require "json"
+        {
+          role: "system",
+          content: <<~TEXT
+            We failed to create a #{model.name} record.
+            Error: #{error.class}: #{error.message}
+            Validation details: #{validation_error_details(error)}
+            Last attributes (JSON): #{JSON.generate(last_attributes)}
+
+            Uniqueness constraints:
+            #{uniqueness_constraints_text(model)}
+
+            Validations:
+            #{model_validations_text(model)}
+
+            Do not suggest:
+            #{dont_suggest_text(model)}
+
+            Provide a corrected JSON object of attributes ONLY.
+          TEXT
+        }
+      end
+
+      def parse_json_hash(text)
+        require "json"
+        JSON.parse(text)
+      end
+
+      def coerce_attributes(model, attrs)
+        attrs = attrs.transform_keys(&:to_s)
+        allowed = model.columns.map(&:name) - [model.primary_key, "created_at", "updated_at"]
+        attrs.slice(*allowed)
+      end
+
+      def chat_with_indicator(prompt, label:)
+        runner = lambda do
+          last_error = nil
+
+          candidate_chat_models.each do |model_id|
+            begin
+              chat = ::RubyLLM.chat(model: model_id, provider: @provider_sym, **@options)
+              chat.with_instructions(prompt.fetch(:content), replace: false)
+              response = chat.ask("Return only the JSON object.")
+              return message_to_text(response)
+            rescue StandardError => e
+              last_error = e
+              next if model_not_supported_error?(e)
+              raise
+            end
+          end
+
+          raise(last_error || "LLM call failed")
+        end
+
+        if @ui && @ui.respond_to?(:with_searching)
+          @ui.with_searching(label) { runner.call }
+        else
+          runner.call
+        end
+      end
+
+      def message_to_text(message)
+        content = message.respond_to?(:content) ? message.content : message
+        return content if content.is_a?(String)
+        return "" if content.nil?
+
+        if content.is_a?(Array)
+          content.filter_map { |p| p.is_a?(Hash) ? p["text"] || p[:text] : nil }.join
+        else
+          content.to_s
+        end
+      end
+
+      def configure_ruby_llm!
+        ::RubyLLM.configure do |config|
+          # Provider credentials (prefer existing config; otherwise env).
+          case @provider_sym
+          when :openai
+            config.openai_api_key ||= ENV["OPENAI_API_KEY"]
+          when :anthropic, :claude
+            config.anthropic_api_key ||= ENV["ANTHROPIC_API_KEY"]
+          when :gemini
+            config.gemini_api_key ||= ENV["GEMINI_API_KEY"]
+          when :deepseek
+            config.deepseek_api_key ||= ENV["DEEPSEEK_API_KEY"]
+          when :bedrock
+            config.bedrock_api_key ||= ENV["BEDROCK_API_KEY"]
+            config.bedrock_secret_key ||= ENV["BEDROCK_SECRET_KEY"]
+            config.bedrock_region ||= ENV["BEDROCK_REGION"]
+            config.bedrock_session_token ||= ENV["BEDROCK_SESSION_TOKEN"]
+          end
+
+          # Optional global tuning
+          config.default_model ||= ENV["AIFAKER_MODEL"] if ENV["AIFAKER_MODEL"]
+          config.request_timeout ||= ENV["AIFAKER_TIMEOUT"].to_i if ENV["AIFAKER_TIMEOUT"]
+        end
+
+        # If the configured default model doesn't exist for this provider, pick one dynamically.
+        begin
+          current = ::RubyLLM.config.default_model
+          ::RubyLLM.models.find(current, @provider_sym)
+        rescue StandardError
+          picked = provider_default_chat_model
+          ::RubyLLM.configure { |c| c.default_model = picked } if picked
+        end
+
+        # Fail fast if still not configured (ruby_llm will also raise later).
+        provider = ::RubyLLM::Provider.providers[@provider_sym]
+        return if provider && provider.configured?
+
+        missing =
+          case @provider_sym
+          when :openai then "OPENAI_API_KEY"
+          when :anthropic, :claude then "ANTHROPIC_API_KEY"
+          when :gemini then "GEMINI_API_KEY"
+          when :deepseek then "DEEPSEEK_API_KEY"
+          when :bedrock then "BEDROCK_API_KEY/BEDROCK_SECRET_KEY/BEDROCK_REGION"
+          else "provider credentials"
+          end
+
+        raise ConnectionError, "#{@provider_sym} is not configured. Set #{missing} (or configure RubyLLM in an initializer)."
+      end
+
+      def provider_default_chat_model
+        provider_chat_model_ids.first
+      rescue StandardError
+        nil
+      end
+
+      def candidate_chat_models
+        # 1) explicit override always wins
+        explicit = ENV["AIFAKER_MODEL"]&.strip
+        return [explicit] if explicit && !explicit.empty?
+
+        # 2) RubyLLM global default, if set, then try all provider chat models
+        begin
+          current = ::RubyLLM.config.default_model
+          if current && !current.to_s.strip.empty?
+            return [current.to_s.strip, *provider_chat_model_ids].compact.uniq
+          end
+        rescue StandardError
+          # ignore and fall back to provider models
+        end
+
+        # 3) provider chat models
+        provider_chat_model_ids
+      end
+
+      def provider_chat_model_ids
+        models = ::RubyLLM.models.by_provider(@provider_sym).chat_models.all
+        ids = models.map(&:id).compact.map(&:to_s).map(&:strip).reject(&:empty?)
+
+        # RubyLLM may surface Gemini models that the API rejects (e.g. `models/aqa`).
+        # We'll both filter obvious mismatches here and also rely on runtime fallback.
+        ids = ids.reject { |id| id.match?(/\/aqa\b/i) } if @provider_sym == :gemini
+
+        ids.uniq
+      rescue StandardError
+        []
+      end
+
+      def model_not_supported_error?(error)
+        msg = error.message.to_s
+        return false if msg.empty?
+
+        msg.include?("is not found for API version") ||
+          msg.include?("is not supported for generateContent") ||
+          msg.match?(/models\/aqa/i)
+      end
+
+      def uniqueness_constraints_text(model)
+        constraints = unique_columns_for(model)
+        return "none" if constraints.empty?
+
+        constraints.map do |col|
+          recent = @generated_uniques.dig(model.name, col)&.last(8) || []
+          existing = safe_existing_values(model, col, limit: 8)
+          <<~ROW.chomp
+            - #{col}: must be unique
+              recent_generated: #{recent.empty? ? "[]" : recent.inspect}
+              existing_sample: #{existing.empty? ? "[]" : existing.inspect}
+          ROW
+        end.join("\n")
+      rescue StandardError
+        "none"
+      end
+
+      def unique_columns_for(model)
+        columns = []
+
+        begin
+          idx_cols =
+            model.connection.indexes(model.table_name)
+              .select(&:unique)
+              .select { |i| i.columns.size == 1 }
+              .map { |i| i.columns.first.to_s }
+          columns.concat(idx_cols)
+        rescue StandardError
+          # ignore
+        end
+
+        begin
+          validator_cols =
+            model.validators
+              .select { |v| v.kind == :uniqueness }
+              .flat_map { |v| v.attributes.map(&:to_s) }
+          columns.concat(validator_cols)
+        rescue StandardError
+          # ignore
+        end
+
+        columns.uniq
+      end
+
+      def remember_generated_unique_values(model, attrs)
+        return unless attrs.is_a?(Hash)
+
+        unique_columns_for(model).each do |col|
+          value = attrs[col] || attrs[col.to_sym]
+          next if value.nil?
+
+          bucket = @generated_uniques[model.name][col]
+          bucket << value
+          bucket.shift while bucket.length > 30
+        end
+      rescue StandardError
+        nil
+      end
+
+      def safe_existing_values(model, column, limit:)
+        model.where.not(column => nil).limit(limit).pluck(column).compact
+      rescue StandardError
+        []
+      end
+
+      def failure_feedback_text(model)
+        data = @failure_feedback[model.name]
+        return "none" unless data
+
+        attrs_json =
+          begin
+            require "json"
+            JSON.generate(data[:attempted_attributes] || {})
+          rescue StandardError
+            (data[:attempted_attributes] || {}).to_s
+          end
+
+        <<~TEXT.chomp
+          message: #{data[:message]}
+          details: #{data[:details]}
+          attempted_attributes: #{attrs_json}
+          dont_suggest: #{data[:dont_suggest].to_s}
+        TEXT
+      end
+
+      def dont_suggest_text(model)
+        data = @failure_feedback[model.name]
+        suggestions = data && data[:dont_suggest].is_a?(Hash) ? data[:dont_suggest] : {}
+        return "none" if suggestions.empty?
+
+        suggestions.map do |column, values|
+          clean = Array(values).compact.map(&:to_s).map(&:strip).reject(&:empty?).uniq
+          "- #{column}: #{clean.first(25).inspect}"
+        end.join("\n")
+      rescue StandardError
+        "none"
+      end
+
+      def validation_error_details(error)
+        return "none" unless defined?(ActiveRecord::RecordInvalid) && error.is_a?(ActiveRecord::RecordInvalid)
+
+        record = error.respond_to?(:record) ? error.record : nil
+        return "none" unless record && record.respond_to?(:errors)
+
+        details = record.errors.details
+        return "none" unless details.is_a?(Hash)
+
+        details.transform_values do |v|
+          Array(v).map { |d| d.is_a?(Hash) ? d[:error] : d }.compact
+        end.to_s
+      rescue StandardError
+        "none"
+      end
+
+      def model_validations_text(model)
+        validators = model.validators
+        return "none" if validators.nil? || validators.empty?
+
+        validators.map do |validator|
+          attributes = validator.attributes.map(&:to_s)
+          kind = validator.kind.to_s
+          options = validator.options.dup
+          options.delete(:class)
+          options_text = options.empty? ? "{}" : serialize_validator_options(options)
+
+          "- #{kind} on #{attributes.join(', ')} options=#{options_text}"
+        end.join("\n")
+      rescue StandardError
+        "none"
+      end
+
+      def uniqueness_taken_values(model, error, attempted_attributes)
+        cols = uniqueness_error_columns(error)
+        return {} if cols.empty?
+
+        attrs = attempted_attributes.is_a?(Hash) ? attempted_attributes.transform_keys(&:to_s) : {}
+        cols.each_with_object({}) do |col, out|
+          values = []
+          values.concat(safe_existing_values(model, col, limit: 30))
+          attempted = attrs[col]
+          values << attempted unless attempted.nil?
+          values.concat(@generated_uniques.dig(model.name, col) || [])
+          out[col] = values.compact.map(&:to_s).map(&:strip).reject(&:empty?).uniq.first(30)
+        end
+      rescue StandardError
+        {}
+      end
+
+      def uniqueness_error_columns(error)
+        return [] unless defined?(ActiveRecord::RecordInvalid) && error.is_a?(ActiveRecord::RecordInvalid)
+
+        record = error.respond_to?(:record) ? error.record : nil
+        return [] unless record && record.respond_to?(:errors) && record.errors.respond_to?(:details)
+
+        record.errors.details.each_with_object([]) do |(attr, details), out|
+          next unless Array(details).any? { |d| d.is_a?(Hash) && d[:error] == :taken }
+          out << attr.to_s
+        end
+      rescue StandardError
+        []
+      end
+
+      def serialize_validator_options(options)
+        sanitized = options.transform_values do |v|
+          case v
+          when Regexp then v.inspect
+          when Proc then "proc"
+          else v
+          end
+        end
+
+        require "json"
+        JSON.generate(sanitized)
+      rescue StandardError
+        options.to_s
+      end
+    end
+  end
+end
+

data/lib/AIFaker/model_introspector.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module AIFaker
+  module ModelIntrospector
+    module_function
+
+    def describe_models_and_associations
+      ensure_active_record!
+
+      eager_load_models!
+      models = app_models
+      associations = models.to_h { |m| [m.name, describe_associations(m)] }
+
+      {
+        models: models.map { |m| describe_model(m) },
+        associations:
+      }
+    end
+
+    def ensure_active_record!
+      return if defined?(ActiveRecord::Base)
+
+      raise MissingRailsError, "ActiveRecord is not loaded. Run AIFaker from a Rails app."
+    end
+
+    def eager_load_models!
+      return unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+
+      # In development, Rails often doesn't eager-load models, so descendants can be empty.
+      # We force-load model files so association introspection works during `db:seed`.
+      Rails.application.eager_load!
+
+      models_dir = Rails.root.join("app/models")
+      loader =
+        if defined?(ActiveSupport::Dependencies) && ActiveSupport::Dependencies.respond_to?(:require_dependency)
+          ActiveSupport::Dependencies.method(:require_dependency)
+        else
+          method(:require)
+        end
+
+      Dir.glob(models_dir.join("**/*.rb")).sort.each { |f| loader.call(f) }
+    rescue LoadError, StandardError
+      # best-effort; not fatal (but if this fails, seeding may not see all models)
+    end
+
+    def app_models
+      base =
+        if defined?(ApplicationRecord)
+          ApplicationRecord
+        else
+          ActiveRecord::Base
+        end
+
+      base.descendants
+        .reject(&:abstract_class?)
+        .reject { |m| m.name.nil? || m.name.empty? }
+        .sort_by(&:name)
+    end
+
+    def describe_model(model)
+      {
+        name: model.name,
+        table_name: model.table_name,
+        primary_key: model.primary_key,
+        columns: model.columns.map do |c|
+          {
+            name: c.name,
+            type: c.type.to_s,
+            null: c.null,
+            default: c.default
+          }
+        end
+      }
+    end
+
+    def describe_associations(model)
+      model.reflections.values.map do |r|
+        {
+          name: r.name.to_s,
+          macro: r.macro.to_s,
+          class_name: r.class_name.to_s,
+          foreign_key: r.foreign_key.to_s,
+          optional: (r.respond_to?(:options) ? !!r.options[:optional] : false)
+        }
+      end
+    end
+  end
+end
+

data/lib/AIFaker/schema_introspector.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module AIFaker
+  module SchemaIntrospector
+    module_function
+
+    def dump_schema
+      ensure_active_record!
+
+      conn = ActiveRecord::Base.connection
+      io = StringIO.new
+      ActiveRecord::SchemaDumper.dump(conn, io)
+      io.string
+    end
+
+    def ensure_active_record!
+      return if defined?(ActiveRecord::Base)
+
+      raise MissingRailsError, "ActiveRecord is not loaded. Run AIFaker from a Rails app (or require ActiveRecord)."
+    end
+  end
+end
+

data/lib/AIFaker/seed_planner.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module AIFaker
+  class SeedPlanner
+    def initialize(models:, associations:)
+      @models = models
+      @associations = associations
+    end
+
+    def plan
+      graph = build_dependency_graph
+      order = topo_sort(graph)
+
+      {
+        order:,
+        graph:
+      }
+    end
+
+    private
+
+    def build_dependency_graph
+      # edge: model -> depends_on_model
+      by_name = @models.to_h { |m| [m.fetch(:name), m] }
+
+      graph = Hash.new { |h, k| h[k] = [] }
+      by_name.each_key { |name| graph[name] ||= [] }
+
+      @associations.each do |model_name, refs|
+        deps =
+          refs
+            .select { |r| r[:macro] == "belongs_to" }
+            .map { |r| r[:class_name] }
+            .select { |klass| by_name.key?(klass) }
+
+        graph[model_name].concat(deps).uniq!
+      end
+
+      graph
+    end
+
+    def topo_sort(graph)
+      # `graph` maps: node -> dependencies (deps must come before node)
+      deps = graph.transform_values(&:dup)
+      order = []
+
+      loop do
+        ready = deps.select { |_, v| v.empty? }.keys.sort
+        break if ready.empty?
+
+        ready.each do |n|
+          order << n
+          deps.delete(n)
+        end
+
+        deps.each_value { |v| v.reject! { |d| order.include?(d) } }
+      end
+
+      # If there is a cycle (or missing nodes), append remaining in stable order.
+      order.concat(deps.keys.sort)
+    end
+  end
+end
+

data/lib/AIFaker/seed_runner.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+module AIFaker
+  class SeedRunner
+    def initialize(ui:, adapter:, plan:, default_count:)
+      @ui = ui
+      @adapter = adapter
+      @plan = plan
+      @default_count = default_count
+      @created = {}
+      @seeding_stack = {}
+    end
+
+    def run(assume_yes: false)
+      order = @plan.fetch(:order)
+
+      if order.empty?
+        @ui.info("No seedable models found. Create some models/migrations first, then re-run `rails db:seed`.")
+        return :noop
+      end
+
+      order.each do |model_name|
+        next unless constantize(model_name)
+
+        should_seed =
+          if assume_yes
+            true
+          else
+            @ui.ask_yes_no("Do you want to feed #{model_name} table data?")
+          end
+        next unless should_seed
+
+        seed_model(model_name, @default_count)
+      end
+
+      print_summary(order)
+      :ok
+    end
+
+    private
+
+    def seed_model(model_name, count)
+      model = constantize(model_name)
+      return unless model
+
+      return if @seeding_stack[model_name]
+      @seeding_stack[model_name] = true
+
+      ensure_required_parents!(model)
+      @ui.table_start(model_name)
+
+      idx = 0
+      attempts = 0
+
+      while idx < count
+        attempts += 1
+        begin
+          attrs = @adapter.generate_attributes(model)
+          record = model.create!(attrs)
+          @created[model_name] ||= []
+          @created[model_name] << record
+          idx += 1
+          @ui.record_created(idx, model_name, record.id)
+        rescue StandardError => e
+          @ui.error("#{model_name} create failed: #{e.class}: #{e.message}")
+          @adapter.register_failure(model, error: e, attempted_attributes: attrs) if @adapter.respond_to?(:register_failure)
+
+          # Auto-repair common relational validations before asking the adapter.
+          repair_notes = []
+          repaired =
+            if @ui.respond_to?(:with_auto_repair)
+              @ui.with_auto_repair("Auto-repairing #{model_name}") { auto_repair!(model, attrs, e, notes: repair_notes) }
+            else
+              auto_repair!(model, attrs, e, notes: repair_notes)
+            end
+
+          repair_notes.each do |note|
+            if @ui.respond_to?(:auto_repair)
+              @ui.auto_repair(note)
+            else
+              @ui.info(note)
+            end
+          end
+
+          if repaired
+            # retry quickly after repair
+            next
+          end
+
+          fix = @adapter.suggest_fix(model, error: e, last_attributes: attrs)
+          @adapter.apply_fix!(fix) if fix
+          raise e if attempts > (count * 10)
+        end
+      end
+    ensure
+      @seeding_stack.delete(model_name)
+    end
+
+    def auto_repair!(model, attrs, error, notes:)
+      return false unless defined?(ActiveRecord::RecordInvalid) && error.is_a?(ActiveRecord::RecordInvalid)
+
+      record = error.respond_to?(:record) ? error.record : nil
+      return false unless record
+
+      repaired = false
+
+      # A) If any required parent table is empty, seed it.
+      record.class.reflections.values.select { |r| r.macro == :belongs_to }.each do |r|
+        assoc_class = constantize(r.class_name)
+        next unless assoc_class
+        next if assoc_class.count.positive?
+
+        notes << "Seeding missing parent #{assoc_class.name} (needed for #{record.class.name})"
+        seed_model(assoc_class.name, [@default_count, 5].min)
+        repaired = true
+      end
+
+      # B) If we reference multiple parents, ensure join rows exist for fk pairs.
+      repaired ||= ensure_join_rows_exist!(record, attrs, notes:)
+      repaired ||= repair_uniqueness!(record, attrs, notes:)
+
+      repaired
+    rescue StandardError => e
+      @ui.error("Auto-repair failed: #{e.class}: #{e.message}")
+      false
+    end
+
+    def ensure_join_rows_exist!(record, attrs, notes:)
+      return false unless attrs.is_a?(Hash)
+
+      belongs_to_refs = record.class.reflections.values.select { |r| r.macro == :belongs_to }
+      return false if belongs_to_refs.size < 2
+
+      fk_values = belongs_to_refs.to_h do |r|
+        fk = r.foreign_key.to_s
+        value = attrs[fk] || attrs[fk.to_sym]
+        [fk, value]
+      end
+      fk_values.compact!
+
+      # Only attempt join repair when we have at least 2 fk values present.
+      present = fk_values.select { |_, v| !v.nil? }
+      return false if present.size < 2
+
+      repaired_any = false
+      present.keys.combination(2).each do |fk_a, fk_b|
+        id_a = fk_values[fk_a]
+        id_b = fk_values[fk_b]
+        next if id_a.nil? || id_b.nil?
+
+        join_models_for(fk_a, fk_b).each do |join_model|
+          begin
+            join_model.find_or_create_by!(fk_a => id_a, fk_b => id_b)
+            notes << "Ensured #{join_model.name}(#{fk_a}=#{id_a}, #{fk_b}=#{id_b}) exists"
+            repaired_any = true
+          rescue StandardError
+            # ignore and try other join models / pairs
+          end
+        end
+      end
+
+      repaired_any
+    end
+
+    def repair_uniqueness!(record, attrs, notes:)
+      return false unless attrs.is_a?(Hash)
+      return false unless record.respond_to?(:errors) && record.errors.respond_to?(:details)
+
+      taken_fields =
+        record.errors.details.each_with_object([]) do |(attr, details), out|
+          next unless details.is_a?(Array)
+          out << attr.to_s if details.any? { |d| d.is_a?(Hash) && d[:error] == :taken }
+        end
+
+      return false if taken_fields.empty?
+
+      mutated = attrs.transform_keys(&:to_s).dup
+      changed = false
+
+      taken_fields.each do |field|
+        original = mutated[field]
+        next if original.nil?
+
+        unique_value = build_unique_value(original, field)
+        next if unique_value == original
+
+        mutated[field] = unique_value
+        changed = true
+      end
+
+      return false unless changed
+
+      fresh = record.class.create!(mutated)
+      @created[record.class.name] ||= []
+      @created[record.class.name] << fresh
+      notes << "Uniqueness conflict fixed for #{record.class.name} (created id: #{fresh.id})"
+      true
+    rescue StandardError
+      false
+    end
+
+    def build_unique_value(value, field)
+      suffix = Time.now.to_i.to_s(36) + rand(10_000).to_s(36)
+      return value unless value.is_a?(String)
+
+      if field.to_s.include?("domain")
+        if value.include?(".")
+          base, ext = value.split(".", 2)
+          "#{base}-#{suffix}.#{ext}"
+        else
+          "#{value}-#{suffix}"
+        end
+      elsif value.match?(/\A[^@\s]+@[^@\s]+\z/)
+        local, domain = value.split("@", 2)
+        "#{local}+#{suffix}@#{domain}"
+      else
+        "#{value} #{suffix}"
+      end
+    end
+
+    def join_models_for(fk_a, fk_b)
+      all_application_models.select do |m|
+        next false if m.abstract_class?
+        next false unless m.table_exists? rescue false
+
+        refs = m.reflections.values.select { |r| r.macro == :belongs_to }
+        fks = refs.map { |r| r.foreign_key.to_s }
+        (fks.include?(fk_a) && fks.include?(fk_b))
+      end
+    end
+
+    def all_application_models
+      base =
+        if defined?(ApplicationRecord)
+          ApplicationRecord
+        else
+          ActiveRecord::Base
+        end
+
+      base.descendants.reject(&:abstract_class?).reject { |m| m.name.nil? || m.name.empty? }
+    end
+
+    def ensure_required_parents!(model)
+      model.reflections.values
+        .select { |r| r.macro == :belongs_to }
+        .each do |r|
+          assoc_class = constantize(r.class_name)
+          next unless assoc_class
+
+          next if assoc_class.count.positive?
+
+          @ui.info("Auto-seeding required parent table #{assoc_class.name} (needed for #{model.name})")
+          seed_model(assoc_class.name, [@default_count, 5].min)
+        end
+    end
+
+    def constantize(name)
+      Object.const_get(name)
+    rescue NameError
+      nil
+    end
+
+    def print_summary(order)
+      rows =
+        order.filter_map do |model_name|
+          model = constantize(model_name)
+          next if model.nil?
+          next if model.respond_to?(:abstract_class?) && model.abstract_class?
+
+          table = (model.respond_to?(:table_name) ? model.table_name : model_name)
+          count = model.respond_to?(:count) ? model.count : 0
+
+          { model: model_name, table: table, count: count }
+        end
+
+      @ui.summary("✅ Seeding Summary", rows)
+    rescue StandardError => e
+      @ui.error("Summary failed: #{e.class}: #{e.message}")
+    end
+  end
+end

data/lib/AIFaker/ui.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module AIFaker
+  class UI
+    RESET = "\e[0m"
+    COLORS = {
+      primary: "\e[1;36m",   # bold cyan
+      section: "\e[1;35m",   # bold magenta
+      info: "\e[0;34m",      # blue
+      success: "\e[0;32m",   # green
+      warning: "\e[0;33m",   # yellow
+      error: "\e[1;31m",     # bold red
+      muted: "\e[0;90m"      # gray
+    }.freeze
+
+    def initialize(io: $stdout, input: $stdin)
+      @io = io
+      @input = input
+    end
+
+    def banner(text)
+      @io.puts paint("✨ ##### #{text} #####", :primary)
+    end
+
+    def section(text)
+      @io.puts paint("🧭 ##======    #{text}  =====##", :section)
+    end
+
+    def ask_yes_no(prompt)
+      loop do
+        @io.print paint("❓ #{prompt} y/n\n", :warning)
+        answer = @input.gets&.strip&.downcase
+        return true if answer == "y"
+        return false if answer == "n"
+      end
+    end
+
+    def ask_integer(prompt, min:, max:)
+      loop do
+        @io.print paint("🔢 #{prompt}\n", :warning)
+        raw = @input.gets&.strip
+        next if raw.nil? || raw.empty?
+        int = Integer(raw, exception: false)
+        next if int.nil?
+        next if int < min || int > max
+        return int
+      end
+    end
+
+    def info(text)
+      @io.puts paint("ℹ️  #{text}", :info)
+    end
+
+    def auto_repair(text)
+      @io.puts paint("🛠️  #{text}", :warning)
+    end
+
+    def table_start(name)
+      section("🏗️ #{name} Creating")
+    end
+
+    def record_created(idx, model_name, id)
+      @io.puts paint("✅ ====> #{idx}. #{model_name} created successfully with id: #{id}", :success)
+    end
+
+    def error(text)
+      @io.puts paint("❌ !! ERROR: #{text}", :error)
+    end
+
+    def summary(title, rows)
+      section("📊 #{title}")
+      @io.puts paint(render_table(rows), :muted)
+    end
+
+    # Shows a "Searching..." animation while the block runs.
+    # Only animates on TTY; otherwise prints a single line.
+    def with_searching(label = "Searching")
+      with_activity(
+        label,
+        emoji: "🔎",
+        color: :info,
+        interval: 0.2,
+        frames: [".", "..", "...", "....", ".....", "......"]
+      ) { yield }
+    end
+
+    # Shows an "Auto-repairing..." animation while a repair block runs.
+    def with_auto_repair(label = "Auto-repairing")
+      with_activity(
+        label,
+        emoji: "🛠️",
+        color: :warning,
+        interval: 0.08,
+        frames: %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏],
+        min_duration: 1.0
+      ) { yield }
+    end
+
+    private
+
+    def with_activity(label, emoji:, color:, interval:, frames:, min_duration: 0.0)
+      return yield unless block_given?
+
+      unless @io.respond_to?(:tty?) && @io.tty?
+        @io.puts paint("#{emoji} #{label}...", color)
+        return yield
+      end
+
+      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      stop = false
+      tick = 0
+      last_line = ""
+      thread =
+        Thread.new do
+          Thread.current.abort_on_exception = false
+          while !stop
+            frame = frames[tick % frames.length]
+            line = "#{frame} #{emoji} #{label} "
+            @io.print "\r#{paint(line, color)}"
+            @io.flush if @io.respond_to?(:flush)
+            last_line = line
+            tick += 1
+            sleep interval
+          end
+        end
+
+      yield
+    ensure
+      elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at if defined?(started_at)
+      remaining = min_duration.to_f - elapsed.to_f
+      sleep remaining if remaining.positive?
+      stop = true if defined?(stop)
+      thread&.join(0.5)
+      if @io.respond_to?(:tty?) && @io.tty?
+        @io.print "\r#{' ' * last_line.length}\r"
+        @io.puts
+        @io.flush if @io.respond_to?(:flush)
+      end
+    end
+
+    def paint(text, color_key)
+      return text unless color_enabled?
+
+      color = COLORS[color_key] || ""
+      "#{color}#{text}#{RESET}"
+    end
+
+    def color_enabled?
+      return false if ENV["NO_COLOR"]
+      @io.respond_to?(:tty?) && @io.tty?
+    end
+
+    def render_table(rows)
+      headers = ["📦 Model", "🗃️ Table", "🔢 Count"]
+      data = rows.map { |r| [r.fetch(:model), r.fetch(:table), r.fetch(:count).to_s] }
+
+      widths = headers.map(&:length)
+      data.each do |row|
+        row.each_with_index { |cell, i| widths[i] = [widths[i], cell.to_s.length].max }
+      end
+
+      line = "+-#{widths.map { |w| "-" * w }.join("-+-")}-+"
+      out = []
+      out << line
+      out << "| #{headers.each_with_index.map { |h, i| h.ljust(widths[i]) }.join(" | ")} |"
+      out << line
+      data.each do |row|
+        out << "| #{row.each_with_index.map { |c, i| c.to_s.ljust(widths[i]) }.join(" | ")} |"
+      end
+      out << line
+      out.join("\n")
+    end
+  end
+end
+

data/lib/AIFaker/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: AIFaker
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Vaibhav Jain
@@ -37,6 +37,14 @@ files:
 - README.md
 - Rakefile
 - lib/AIFaker.rb
+- lib/AIFaker/client.rb
+- lib/AIFaker/errors.rb
+- lib/AIFaker/llm_adapters/ruby_llm.rb
+- lib/AIFaker/model_introspector.rb
+- lib/AIFaker/schema_introspector.rb
+- lib/AIFaker/seed_planner.rb
+- lib/AIFaker/seed_runner.rb
+- lib/AIFaker/ui.rb
 - lib/AIFaker/version.rb
 - sig/AIFaker.rbs
 homepage: https://github.com/VaibhavDJain/AIFaker
@@ -45,7 +53,8 @@ licenses:
 metadata:
   homepage_uri: https://github.com/VaibhavDJain/AIFaker
   source_code_uri: https://github.com/VaibhavDJain/AIFaker
-  changelog_uri: https://github.com/VaibhavDJain/AIFaker
+  changelog_uri: https://github.com/VaibhavDJain/AIFaker/releases
+  documentation_uri: https://www.rubydoc.info/gems/AIFaker
 post_install_message:
 rdoc_options: []
 require_paths: