Riffer
The all-in-one Ruby framework for building AI-powered applications and agents.
Requirements
Installation
Install the released gem:
gem install riffer
Or add to your application's Gemfile:
gem 'riffer'
Quick Start
require 'riffer'
# Configure your provider
Riffer.configure do |config|
config.openai.api_key = ENV['OPENAI_API_KEY']
end
# Define an agent
class EchoAgent < Riffer::Agent
model 'openai/gpt-5-mini'
instructions 'You are an assistant that repeats what the user says.'
end
# Use the agent
agent = EchoAgent.new
puts agent.generate('Hello world')
Documentation
Comprehensive guides live at riffer.ai:
The guide sources are in the docs directory.
API Reference
The full API reference is published at riffer.ai/api. Preview the site locally with:
bin/rake docs:serve
Then open http://localhost:8000. The site uses root-absolute paths, so it must be served over HTTP — opening _site/index.html via file:// won't work.
Development
After checking out the repo, run:
bin/setup
Common workflows are wrapped in bin/. Each is a thin exec bundle exec … script — use them
instead of typing bundle exec yourself:
| Command | Description |
|---|
bin/rake | Default task: test + rubocop + steep:check |
bin/test | Run tests |
bin/lint | Check code style (pass -a to auto-fix) |
bin/typecheck | Run Steep type checker |
bin/rbs | Generate RBS type signatures |
bin/rbs-watch | Watch and regenerate RBS files |
bin/docs | Build the docs site + API reference |
bin/build | Build the gem package |
bin/console | Interactive console |
bin/rake <task> is the escape hatch for any rake task without a named wrapper (e.g.
bin/rake test:slow, bin/rake release).
Recording VCR Cassettes
Integration tests use VCR to record and replay HTTP interactions. When adding new tests that hit provider APIs, you need to record cassettes with real API keys.
Create a .env file in the project root (it is gitignored):
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
AWS_BEDROCK_API_TOKEN=...
GEMINI_API_KEY=...
GOOGLE_CLOUD_PROJECT=my-project
The test helper loads this file automatically via dotenv. Then run the specific tests that need new cassettes:
bundle exec ruby -Itest test/riffer/providers/open_ai_test.rb
bundle exec ruby -Itest test/riffer/providers/anthropic_test.rb
bundle exec ruby -Itest test/riffer/providers/amazon_bedrock_test.rb
GOOGLE_CLOUD_ACCESS_TOKEN=$(gcloud auth application-default print-access-token) \
bundle exec ruby -Itest test/riffer/providers/anthropic_vertex_test.rb
Google Cloud tests take a short-lived access token rather than a key, so pass it on the command line instead of storing it in .env.
Acceptance tests
test/acceptance/ runs every riffer feature against each provider it lists, one file per feature. Its cassettes live under test/fixtures/vcr_cassettes/acceptance/ and only replay. To record, set RIFFER_RECORD to a VCR record mode: once records missing cassettes, all re-records every cassette the run touches. Narrow the run to one provider with -n:
RIFFER_RECORD=once bin/test test/acceptance/tool_calling_test.rb -n "/::gemini/"
GOOGLE_CLOUD_ACCESS_TOKEN=$(gcloud auth application-default print-access-token) \
RIFFER_RECORD=once bin/test test/acceptance/tool_calling_test.rb -n "/::google_cloud/"
eval "$(aws configure export-credentials --profile your-profile --format env)" && \
RIFFER_RECORD=once bin/test test/acceptance/tool_calling_test.rb -n "/::amazon_bedrock/"
Bedrock records with the AWS credentials in the environment when AWS_ACCESS_KEY_ID is set, and with AWS_BEDROCK_API_TOKEN otherwise. Export a profile's credentials as above instead of setting AWS_PROFILE, so the SDK doesn't fetch them over HTTP during a test.
A test that fails while recording leaves a partial cassette behind; delete it before recording again.
To add a provider, add its entry to ACCEPTANCE_PROVIDERS in test/acceptance/acceptance_helper.rb, including the reasoning levels its model accepts, and its model's pricing to test/acceptance/fixtures/catalog.json. Every feature file then runs against it. A feature the provider can't support excludes it with a reason: acceptance_providers(except: { amazon_bedrock: "Converse has no web search tool" }).
VCR records the HTTP interactions to test/fixtures/vcr_cassettes/ on the first run. Subsequent runs replay from the cassettes without hitting the API. API keys are automatically filtered from recorded cassettes.
Contributing
- Fork the repository and create your branch:
git checkout -b feature/foo
- Run tests and linters locally:
bin/rake
- Submit a pull request with a clear description of the change
Please follow the Code of Conduct.
Changelog
All notable changes to this project are documented in CHANGELOG.md.
License
Licensed under the MIT License. See LICENSE.txt for details.
