AIFaker

AI-powered, schema-aware Rails seeding for modern teams.

AIFaker helps developers, startups, and product teams generate realistic demo and test data in minutes instead of spending hours writing and maintaining manual db/seeds.rb logic.

It reads your Rails schema and model relationships, uses an LLM to generate meaningful attributes, and creates records in dependency order (belongs_to parents first) so your data is usable from day one.

Why teams use AIFaker:

  • realistic data for demos, QA, staging, and local development
  • faster onboarding for new developers (no manual seed setup)
  • schema-aware generation that respects model structure and validations
  • automatic retry + repair flow for common seeding failures
  • provider flexibility (openai, claude/anthropic, gemini, deepseek, bedrock)

Installation

Add both gems to your Rails app:

bundle add AIFaker
bundle add ruby_llm

Or in Gemfile:

gem "AIFaker"
gem "ruby_llm"

Quick Start

Set provider + API key in your shell:

export AIFAKER_PROVIDER=openai
export OPENAI_API_KEY="your_key_here"

Create db/seeds.rb:

client = AIFaker.connect
client.seed!

Run:

rails db:seed

What To Write In db/seeds.rb

1) Interactive mode (default)

If you do not set automode, it stays false by default.

client = AIFaker.connect
client.seed!

Behavior:

  • asks confirmation before seeding
  • asks count per table (range: 5..50)
  • asks per model/table whether to seed or skip

2) Non-interactive mode (client.automode = true)

client = AIFaker.connect
client.automode = true
client.seed!

Behavior:

  • no prompts (auto-yes everywhere)
  • random count per table (10..20)
  • seeds all models in planned order

Equivalent shorthand:

client = AIFaker.connect
client.automode!
client.seed!

3) Explicit provider in code

client = AIFaker.connect("gemini")
client.automode = true
client.seed!

AIFaker.connect provider fallback order:

  1. explicit argument (AIFaker.connect("gemini"))
  2. ENV["AIFAKER_PROVIDER"]
  3. default "openai"

claude is also supported as a friendly alias for Anthropic:

client = AIFaker.connect("claude") # internally uses anthropic provider
client.seed!

Environment Variables

Provider selection

  • AIFAKER_PROVIDER -> openai | anthropic | claude | gemini | deepseek | bedrock

Provider credentials

  • OPENAI_API_KEY for openai
  • ANTHROPIC_API_KEY for anthropic and claude
  • GEMINI_API_KEY for gemini
  • DEEPSEEK_API_KEY for deepseek
  • BEDROCK_API_KEY, BEDROCK_SECRET_KEY, BEDROCK_REGION for bedrock
  • BEDROCK_SESSION_TOKEN (optional)

Model and request tuning

  • AIFAKER_MODEL -> force a specific model id
  • AIFAKER_TIMEOUT -> request timeout in seconds

Examples:

export AIFAKER_PROVIDER=gemini
export GEMINI_API_KEY="your_key_here"
export AIFAKER_MODEL="models/gemini-1.5-flash"
export AIFAKER_TIMEOUT=120

export AIFAKER_PROVIDER=openai
export OPENAI_API_KEY="your_key_here"
export AIFAKER_MODEL="gpt-4.1-mini"

export AIFAKER_PROVIDER=claude
export ANTHROPIC_API_KEY="your_key_here"
# optional: choose a specific Claude model
export AIFAKER_MODEL="claude-3-5-sonnet-latest"

Provider Notes

Gemini

  • If a discovered model is unsupported for generateContent (for example models/aqa), AIFaker automatically tries other available provider models.
  • You can still force a model via AIFAKER_MODEL.

How Seeding Works

During client.seed!, AIFaker:

  1. connects to LLM provider
  2. reads schema
  3. reads models + associations
  4. builds dependency-aware seed plan
  5. generates attributes and creates records
  6. auto-repairs common failures (including uniqueness retries)

When record creation fails, AIFaker shares failure context back to the LLM (error details + attempted attributes + uniqueness exclusions) to improve the next attempt.

Typical db/seeds.rb Templates

Template A: local development (interactive)

client = AIFaker.connect
client.seed!

Template B: CI / scripted runs

client = AIFaker.connect
client.automode = true
client.seed!

Template C: fixed provider + fixed model

client = AIFaker.connect("gemini")
client.automode = true
client.seed!

Then:

export GEMINI_API_KEY="your_key_here"
export AIFAKER_MODEL="models/gemini-1.5-flash"
rails db:seed

Security

  • Never hardcode API keys in db/seeds.rb.
  • Prefer shell env vars, .env, or encrypted credentials.
  • If a key is ever exposed in logs/chat/history, rotate it immediately.

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.

Contributing

Bug reports and pull requests are welcome on GitHub at AIFaker. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

Author

Contributors

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the AIFaker project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.